---
title: "Zahlungsdatei pain.001 prüfen (SEPA oder AXZ)"
method: POST
path: "/payments/validate"
tags: ["Zahlungsverkehr"]
---

# Zahlungsdatei pain.001 prüfen (SEPA oder AXZ)

`POST /payments/validate`

## Request

- Base URL: `https://finisma.de/api/v1`
- URL: `https://finisma.de/api/v1/payments/validate`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://finisma.de/api/oauth/authorize`, token URL `https://finisma.de/api/oauth/token`, scopes: `invoice:verify`, `invoice:create`)

Prüft eine pain.001-Datei (Versionen .09 und .03) mit denselben fachlichen Regeln wie der pain.001-Validator auf finisma.de und dazu gegen das Schema (DK-TVS für SEPA bzw. AXZ, ISO-Schema für .03). Das Profil (SEPA oder AXZ) wird erkannt; 'profile' setzt es fest. Antwort: Profil, Version, Zusammenfassung (Anzahl, Summe je Währung), Befunde der Prüfregeln, Ergebnis der Schemaprüfung mit Zeile und Spalte und ein Gesamturteil. Ist der Validierungsdienst nicht erreichbar, steht xsd.available=false und das Urteil beruht nur auf den Prüfregeln. Nichts wird gespeichert. Kostenlos bis 5 Aufrufe pro Tag und Konto. Mit dem Zahlungsverkehr-Abo (Feature payments) ohne Limit. Ohne Abo kauft 1 Credit einen Prüfblock mit 10 weiteren Prüfungen (für Zahlungsdateien und Kontoauszüge gemeinsam, ohne Ablaufdatum). Ein Konto (API-Key oder OAuth) ist immer nötig.

## Request body

- object
  - `xml` string: Die Datei als XML-Text (max. 10 MB). Alternativ 'file_base64'.
  - `file_base64` string, byte: Die XML-Datei Base64-kodiert (max. 10 MB). Alternativ 'xml'.
  - `filename` string: Optionaler Dateiname, erscheint in den Meldungen.
  - `profile` 'auto' | 'sct' | 'axz': Profil der Prüfung: auto (Erkennung aus der Datei), sct (SEPA-Überweisung) oder axz (Auslandszahlung).

## Response `200`

Ergebnis; billing nennt, womit bezahlt wurde.

- object
  - `summary` string, required: Kurzfassung des Ergebnisses.
  - `result` object, required
    - `message` 'pain.001', required
    - `version` '09' | '03', required
    - `profile` 'sct' | 'axz', required
    - `profileSource` 'detected' | 'requested'
    - `profileReasons` string[]
    - `summary` object, required
      - `payments` integer
      - `declaredPayments` integer, nullable: NbOfTxs aus dem Kopf.
      - `controlSum` string: Gerechnete Summe aller Zahlungen.
      - `declaredControlSum` string, nullable: CtrlSum aus dem Kopf.
      - `currencies` object[]
        - `currency` string
        - `payments` integer
        - `total` string
      - `executionDates` string[]
      - `paymentBlocks` integer: Anzahl PmtInf-Blöcke.
      - `messageId` string, nullable
      - `createdAt` string, nullable
    - `findings` object[], required
      - `code` string, required: Maschinencode der Prüfregel.
      - `severity` 'error' | 'warning' | 'info', required
      - `message` string, required: Deutsche Meldung.
      - `path` string: Punkt-Pfad in das gelesene Modell.
    - `xsd` object, required: Schemaprüfung über den Validierungsdienst. available=false heißt: nicht verfügbar, das Urteil beruht dann nur auf den Prüfregeln.
      - `available` boolean, required
      - `ruleset` string, required: Prüfgrundlage, z. B. iso.20022:camt053:08.
      - `valid` boolean
      - `verdict` 'valid' | 'valid_with_warnings' | 'invalid'
      - `errorCount` integer
      - `warningCount` integer
      - `findings` object[]
        - `code` string, required
        - `severity` 'error' | 'warning' | 'info', required
        - `message` string, required
        - `line` integer, nullable
        - `column` integer, nullable
        - `location` string, nullable
      - `note` string
    - `verdict` 'valid' | 'valid_with_warnings' | 'invalid', required
    - `schemaChecked` boolean
    - `billing` object, required: Womit der Aufruf bezahlt wurde: free_quota (Freikontingent), subscription (Zahlungsverkehr-Abo), check_block (Prüfblock: 1 Credit für 10 Prüfungen) oder credit (Guthaben).
      - `via` 'free_quota' | 'subscription' | 'check_block' | 'credit', required
      - `freeRemaining` integer, nullable, required: Verbleibende kostenlose Aufrufe im laufenden Zeitraum (Europe/Berlin); beim Abo null.
      - `freePeriod` 'day' | 'month', required: Zeitraum des Freikontingents: day beim Prüfen, month beim Auslesen.
      - `checkBlockRemaining` integer: Nur bei via check_block: offene Prüfungen im Prüfblock nach diesem Aufruf.
      - `creditsCharged` integer: Abgebuchte Credits: bei via credit und beim Kauf eines neuen Prüfblocks.
      - `refunded` boolean: true, wenn der Aufruf zurückgebucht wurde, weil die Schemaprüfung nicht erreichbar war.

## Other responses

- `400`: Keine Datei, kein unterstütztes Format oder eine nicht unterstützte Version (code invalid_input). Abgewiesene Dateien kosten nichts.
- `401`: Kein oder ungültiges Credential.
- `402`: Tageskontingent (5 pro Tag) aufgebraucht, keine offene Prüfung im Prüfblock, kein Zahlungsverkehr-Abo und kein Guthaben (code payment_required). Retry-After nennt die Sekunden bis zum Neubeginn des Kontingents (Mitternacht, Europe/Berlin).
- `413`: Datei größer als 10 MB (code payload_too_large).
- `429`: Rate-Limit (30/min je Key).
- `502`: Fehler im nachgelagerten Dienst.

---

[API](https://skmtc.dev/finisma/apis/finisma-rest-api.md) · [All operations](https://skmtc.dev/finisma/apis/finisma-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finisma/apis/finisma-rest-api/revisions/c1a9acfab69b?raw)