---
title: "Auslandszahlungsdatei (pain.001.001.09, DK-AXZ) erzeugen"
method: POST
path: "/payments/axz"
tags: ["Zahlungsverkehr"]
---

# Auslandszahlungsdatei (pain.001.001.09, DK-AXZ) erzeugen

`POST /payments/axz`

## Request

- Base URL: `https://finisma.de/api/v1`
- URL: `https://finisma.de/api/v1/payments/axz`
- 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`)

Erzeugt aus einem Zahllauf (JSON) die Auslandszahlungsdatei im DK-AXZ-Profil (GBIC_5): beliebige ISO-Währungen, Entgeltregelung je Zahlung (Default SHAR), Empfängeradresse mit Ort und Länderkennung ist Pflicht, purposeCode (Zweckcode Purp/Cd, z. B. SUPP) optional; ultimateDebtor/ultimateCreditor brauchen hier einen Namen (max 140) und dürfen eine Adresse tragen, instructionId, creditorId, debtor.id und initiatingPartyId wie bei /payments/sepa. Erfordert das Feature 'paymentsAbroad' (Auslandsmodul-Add-on; 'payments' allein reicht NICHT). Ablauf, Fehlerformen (422 mit Issue-Liste, 502 mit QA-Befunden) und Accept-Regel wie bei /payments/sepa; die autoritative Prüfung läuft hier gegen das AXZ-TVS. Dateiname: axz-ausland-<Datum>.xml.

## Request body

- PaymentRun
  - `debtor` object, required
    - `name` string, required
    - `iban` string, required
    - `bic` string
    - `address` object
      - `townName` string
      - `countryCode` string
      - `postCode` string
      - `streetName` string
      - `buildingNumber` string
      - `addressLines` string[]
      - `department` string
      - `subDepartment` string
      - `buildingName` string
      - `floor` string
      - `postBox` string
      - `room` string
      - `townLocationName` string
      - `districtName` string
      - `countrySubDivision` string: CtrySubDvsn: Bundesstaat oder Provinz
    - `currency` string
    - `id` object: Dbtr/Id (T112): Kennung des Auftraggebers
      - `kind` 'org' | 'private', required: org = Organisation (OrgId), private = Privatperson (PrvtId)
      - `anyBic` string: OrgId/AnyBIC, nur org
      - `lei` string: OrgId/LEI, nur org
      - `otherId` string: Othr/Id, z. B. Gläubiger-ID oder Kundennummer
      - `otherSchemeCode` string: Othr/SchmeNm/Cd, z. B. CUST, NIDN
      - `otherSchemeProprietary` string: Othr/SchmeNm/Prtry
      - `otherIssuer` string: Othr/Issr
      - `birthDate` string: nur private: PrvtId/DtAndPlcOfBirth/BirthDt
      - `birthProvince` string
      - `birthCity` string
      - `birthCountry` string
    - `countryOfResidence` string: Dbtr/CtryOfRes: Sitzland des Auftraggebers (ISO 3166 alpha-2); nur AXZ.
  - `requestedExecutionDate` string, required
  - `payments` object[], required
    - `creditorName` string, required
    - `creditorIban` string, required
    - `creditorAccountOther` string
    - `creditorBic` string
    - `creditorAgent` object
      - `name` string
      - `address` object
        - `townName` string
        - `countryCode` string
        - `postCode` string
        - `streetName` string
        - `buildingNumber` string
        - `addressLines` string[]
        - `department` string
        - `subDepartment` string
        - `buildingName` string
        - `floor` string
        - `postBox` string
        - `room` string
        - `townLocationName` string
        - `districtName` string
        - `countrySubDivision` string: CtrySubDvsn: Bundesstaat oder Provinz
    - `amount` number, required
    - `currency` string, required
    - `remittanceInfo` string, required
    - `endToEndId` string
    - `creditorAddress` object
      - `townName` string
      - `countryCode` string
      - `postCode` string
      - `streetName` string
      - `buildingNumber` string
      - `addressLines` string[]
      - `department` string
      - `subDepartment` string
      - `buildingName` string
      - `floor` string
      - `postBox` string
      - `room` string
      - `townLocationName` string
      - `districtName` string
      - `countrySubDivision` string: CtrySubDvsn: Bundesstaat oder Provinz
    - `chargeBearer` 'SLEV' | 'SHAR' | 'DEBT' | 'CRED'
    - `executionDate` string
    - `serviceLevel` 'NURG' | 'URGP' | 'SDVA'
    - `categoryPurpose` 'SALA': Nur SEPA (/payments/sepa): "SALA" kennzeichnet die Zahlung als Lohn- oder Gehaltszahlung (PmtTpInf/CtgyPurp/Cd). Gehaltszahlungen kommen in einen eigenen PmtInf-Block. Im AXZ-Profil ist das Feld ein Fehler (PAY_CATEGORY_PURPOSE_AXZ).
    - `localInstrument` 'INST': Nur SEPA (/payments/sepa): "INST" kennzeichnet die Zahlung als Echtzeitüberweisung (PmtTpInf/LclInstrm/Cd). Echtzeitüberweisungen kommen in einen eigenen PmtInf-Block; die Bank verlangt dafür einen eigenen Einreichungsweg. Im AXZ-Profil ein Fehler (PAY_LOCAL_INSTRUMENT_AXZ).
    - `instrPrty` 'HIGH': Nur SEPA (/payments/sepa): "HIGH" setzt die Priorität PmtTpInf/InstrPrty; solche Zahlungen kommen in einen eigenen PmtInf-Block. Weglassen bedeutet NORM. Im AXZ-Profil ist das Feld ein Fehler (PAY_INSTR_PRTY_AXZ), dort kennzeichnet serviceLevel URGP eine eilige Zahlung.
    - `purposeCode` string: Zahlungszweck als ISO-20022-Code (CdtTrfTxInf/Purp/Cd, ExternalPurpose1Code), z. B. SUPP Lieferantenzahlung, SALA Gehalt, TAXS Steuer. Richtet sich an den Empfänger, nicht an die Bank; in SEPA- und AXZ-Dateien zulässig. Geprüft wird nur das Format (PAY_PURPOSE_CODE_FORMAT).
    - `instructionId` string: PmtId/InstrId: Auftragsreferenz des Einreichers, max 35 Zeichen, ohne Default.
    - `ultimateDebtor` object: UltmtDbtr: abweichender Auftraggeber (zahlt wirtschaftlich, ist aber nicht Kontoinhaber). SEPA: Name max 70 und/oder Kennung; AXZ: Name Pflicht, max 140, Adresse zulässig.
      - `name` string: SEPA max 70, AXZ Pflicht und max 140 (PAY_ULTIMATE_NAME_*)
      - `address` object: nur AXZ; der SEPA-Generator schreibt sie nicht
        - `townName` string
        - `countryCode` string
        - `postCode` string
        - `streetName` string
        - `buildingNumber` string
        - `addressLines` string[]
        - `department` string
        - `subDepartment` string
        - `buildingName` string
        - `floor` string
        - `postBox` string
        - `room` string
        - `townLocationName` string
        - `districtName` string
        - `countrySubDivision` string: CtrySubDvsn: Bundesstaat oder Provinz
      - `id` object
        - `kind` 'org' | 'private', required: org = Organisation (OrgId), private = Privatperson (PrvtId)
        - `anyBic` string: OrgId/AnyBIC, nur org
        - `lei` string: OrgId/LEI, nur org
        - `otherId` string: Othr/Id, z. B. Gläubiger-ID oder Kundennummer
        - `otherSchemeCode` string: Othr/SchmeNm/Cd, z. B. CUST, NIDN
        - `otherSchemeProprietary` string: Othr/SchmeNm/Prtry
        - `otherIssuer` string: Othr/Issr
        - `birthDate` string: nur private: PrvtId/DtAndPlcOfBirth/BirthDt
        - `birthProvince` string
        - `birthCity` string
        - `birthCountry` string
      - `countryOfResidence` string: CtryOfRes: Sitzland (ISO 3166 alpha-2); nur AXZ, der SEPA-Generator schreibt es nicht.
    - `ultimateCreditor` object: UltmtCdtr: abweichender Empfänger, Regeln wie ultimateDebtor.
      - `name` string: SEPA max 70, AXZ Pflicht und max 140 (PAY_ULTIMATE_NAME_*)
      - `address` object: nur AXZ; der SEPA-Generator schreibt sie nicht
        - `townName` string
        - `countryCode` string
        - `postCode` string
        - `streetName` string
        - `buildingNumber` string
        - `addressLines` string[]
        - `department` string
        - `subDepartment` string
        - `buildingName` string
        - `floor` string
        - `postBox` string
        - `room` string
        - `townLocationName` string
        - `districtName` string
        - `countrySubDivision` string: CtrySubDvsn: Bundesstaat oder Provinz
      - `id` object
        - `kind` 'org' | 'private', required: org = Organisation (OrgId), private = Privatperson (PrvtId)
        - `anyBic` string: OrgId/AnyBIC, nur org
        - `lei` string: OrgId/LEI, nur org
        - `otherId` string: Othr/Id, z. B. Gläubiger-ID oder Kundennummer
        - `otherSchemeCode` string: Othr/SchmeNm/Cd, z. B. CUST, NIDN
        - `otherSchemeProprietary` string: Othr/SchmeNm/Prtry
        - `otherIssuer` string: Othr/Issr
        - `birthDate` string: nur private: PrvtId/DtAndPlcOfBirth/BirthDt
        - `birthProvince` string
        - `birthCity` string
        - `birthCountry` string
      - `countryOfResidence` string: CtryOfRes: Sitzland (ISO 3166 alpha-2); nur AXZ, der SEPA-Generator schreibt es nicht.
    - `creditorId` object: Cdtr/Id: Kennung des Empfängers (LEI, BIC oder sonstige Kennung).
      - `kind` 'org' | 'private', required: org = Organisation (OrgId), private = Privatperson (PrvtId)
      - `anyBic` string: OrgId/AnyBIC, nur org
      - `lei` string: OrgId/LEI, nur org
      - `otherId` string: Othr/Id, z. B. Gläubiger-ID oder Kundennummer
      - `otherSchemeCode` string: Othr/SchmeNm/Cd, z. B. CUST, NIDN
      - `otherSchemeProprietary` string: Othr/SchmeNm/Prtry
      - `otherIssuer` string: Othr/Issr
      - `birthDate` string: nur private: PrvtId/DtAndPlcOfBirth/BirthDt
      - `birthProvince` string
      - `birthCity` string
      - `birthCountry` string
    - `creditorCountryOfResidence` string: Cdtr/CtryOfRes: Sitzland des Empfängers (ISO 3166 alpha-2); nur AXZ, in SEPA-Dateien nicht enthalten.
    - `uetr` string: PmtId/UETR: eindeutige Transaktionsreferenz, UUID Version 4 in Kleinbuchstaben; nur AXZ.
    - `transferCurrency` string: Amt/EqvtAmt/CcyOfTrf: Gegenwertzahlung, amount/currency in Kontowährung, Überweisung in dieser Währung; nur AXZ.
    - `intermediaryAgents` string[]: IntrmyAgt1/2: BICs der Korrespondenzbanken; nur AXZ.
    - `creditorClearingMember` object: CdtrAgt/FinInstnId/ClrSysMmbId, zum Beispiel USABA mit Routing-Nummer; nur AXZ.
      - `systemCode` string, required
      - `memberId` string, required
    - `instructionsForCreditorAgent` object[]: InstrForCdtrAgt: Weisungen an die Bank des Empfängers; nur AXZ.
      - `code` 'CHQB' | 'HOLD' | 'PHOB' | 'TELB'
      - `info` string
    - `instructionForDebtorAgent` string: InstrForDbtrAgt: Weisung an die eigene Bank; nur AXZ.
    - `batchBooking` false: BtchBookg false: Einzelbuchung statt Sammelbuchung.
  - `initiatingPartyId` object: GrpHdr/InitgPty/Id (T112): Kennung des Einreichers; als Name steht weiterhin der Auftraggeber.
    - `kind` 'org' | 'private', required: org = Organisation (OrgId), private = Privatperson (PrvtId)
    - `anyBic` string: OrgId/AnyBIC, nur org
    - `lei` string: OrgId/LEI, nur org
    - `otherId` string: Othr/Id, z. B. Gläubiger-ID oder Kundennummer
    - `otherSchemeCode` string: Othr/SchmeNm/Cd, z. B. CUST, NIDN
    - `otherSchemeProprietary` string: Othr/SchmeNm/Prtry
    - `otherIssuer` string: Othr/Issr
    - `birthDate` string: nur private: PrvtId/DtAndPlcOfBirth/BirthDt
    - `birthProvince` string
    - `birthCity` string
    - `birthCountry` string

## Response `200`

Die erzeugte Zahlungsdatei, standardmäßig als XML; die JSON-Hülle nur auf ausdrücklichen Accept-Wunsch.

- PaymentFileResult: JSON-Hülle der Zahlungsdatei-Endpoints. Kommt nur bei ausdrücklichem Accept: application/json (ohne */*-Platzhalter), sonst antwortet der Endpoint direkt mit dem XML.
  - `xml` string, required: Die pain.001-XML als Text.
  - `filename` string, required: Vorgeschlagener Dateiname, gleiches Schema wie der Content-Disposition-Name der XML-Antwort (sepa-inland-<Datum>.xml bzw. axz-ausland-<Datum>.xml).
  - `summary` object, required
    - `payments` integer, required: Anzahl der Zahlungen.
    - `controlSum` string, required: Kontrollsumme, identisch mit CtrlSum im XML.
    - `requestedExecutionDate` string, required: Ausführungsdatum (yyyy-mm-dd).
  - `warnings` PaymentIssue[], required: Nicht blockierende Meldungen (severity warning oder info).
    - `code` string, required: Maschinencode, z. B. "PAY_IBAN_INVALID".
    - `message` string, required: Deutsche Fehlermeldung.
    - `path` string: Punkt-Pfad in den Zahllauf, z. B. "payments.0.creditorIban".
    - `severity` 'error' | 'warning' | 'info', required
  - `verification` 'autoritativ' | 'eingeschränkt', required: autoritativ = die Datei hat das QA-Gate (DK-TVS bzw. AXZ-TVS) durchlaufen; eingeschränkt = kein Validator konfiguriert, geprüft wurden nur Schema und Geschäftsregeln.

## Other responses

- `400`: Ungültige Eingabe.
- `401`: Kein oder ungültiges Credential.
- `403`: Feature 'paymentsAbroad' fehlt (code subscription_required).
- `422`: Der Zahllauf verletzt Geschäftsregeln (code invalid_input); details enthält die vollständige Issue-Liste (code, message, path, severity). Es wurde keine Datei erzeugt.
- `429`: Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After).
- `502`: Das QA-Gate ist gescheitert (code upstream_error): die erzeugte Datei hat die autoritative Prüfung nicht bestanden (details enthält die Fehler-Befunde) oder der Validator-Service war nicht erreichbar. Es wurde keine Datei ausgeliefert.

---

[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)