Zum Hauptinhalt springen
Version: 1.2.0

PaymentTransaction

paymentInformation objectrequired

Dieses Objekt enthält die Informationen vom Bezahldienst, die 1-zu-1 in den Antrag übernommen werden können. Die Antrags-API wird künftig angeglichen.

transactionUrlurirequired

Die Rest-URL der Payment Transaction für die Statusabfrage. Diese Information könnte aus den Informationen generiert werden. Eine explizite Ablage der URL dient der Robustheit der Schnittstelle.

Possible values: non-empty and <= 2082 characters

Example: https://payment.bundesland.zzzz/api/v1/paymenttransaction/12002312/MELD-ANT-FORM-4711/9xxd-432x-6543-xfd6-gfdx-fd27
transactionRedirectUrlurirequired

Die Redirect-URL an die der Online-Dienst den Benutzer weiterleiten soll. Diese URL öffnet die "Paypage" / "Bezahlseite" des Bezahldienstes. Diese URL muss nur im Status "INITIAL" (also bei der Post-Response oder Statusabfrage vor Abschluss / Abbruch der Transaktion) enthalten sein. Nach Abschluss der Transaktion sollte diese URL nicht enthalten sein.

Possible values: non-empty and <= 5000 characters

Example: https://portal.bundesland.zzzz/ui/doPayment/9xxd-432x-6543-xfd6-gfdx-fd27-CHECKSUM
transactionIdstringrequired

Eine vom Bezahldienst vergebene Transaktions-ID beim POST des Requests. Diese ID wird für die späteren Abfragen (GET) verwendet. Dies kann schon das Kassenzeichen sein. Sofern dies später vergeben wird, kann hier eine 'technische' ID des Bezahldienstes vergeben werden. Falls der Bezahldienst keine eigenen IDs hier verwendet, kann die Schnittstelle auch die Request-ID zurück geben.

Possible values: non-empty and <= 44 characters, Value must match regular expression ^[\w-]+$

Example: 9xxd-432x-6543-xfd6-gfdx-fd27
transactionReferencestring

Das "fachliche" Kennzeichen für eine Bezahlung. Dieses kann bei dem POST des Requests vom Bezahldienst vergeben werden oder erst nach der Autorisierung durch den Bezahler. Daher ist die relevante ID für diese Schnittstelle die transactionId, die durch den Bezahldienst bei der Anlage des Payment-Requests vergeben wird.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[\w-]+$

Example: KA-2020-1234
transactionTimestampdate-time

Zeitstempel der erfolgreichen Durchführung der Bezahlung.

Example: 2025-10-06T12:32:00.711Z
paymentMethodPaymentMethod (string)

Die vom Benutzer ausgewählte Zahlart. Das Feld ist nur bei einer erfolgreichen Zahlung vorhanden / befüllt.

Possible values: [GIROPAY, PAYDIRECT, CREDITCARD, PAYPAL, OTHER]

Example: CREDITCARD
paymentMethodDetailstring

Weitere Erläuterung zur gewählten Zahlart.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[\w-]+$

Example: Visa
statusstringrequired

Der Status der Transaktion soll dem EfA-Onlinedienst erkennbar machen, ob die Bezahlung erfolgreich durchgeführt wurde.

  • INITIAL - der Antrag hat einen Payment-Request ausgelöst und eine Payment-Transaction wurde angelegt. Der Nutzer hat aber im Bezahldienst noch keine Wirkung erzeugt. Der Benutzer kann mit dem Link zum Bezahldienst weitergeleitet werden. NEUE / Eränzende Info: Solange der Benutzer eine bestimmte Zahlart ausgewählt und abgebrochen hat - aber noch die Option hat, stattdessen eine andere Zahlart zu verwenden, so bleibt der Status auf INITIAL
  • PAYED - der Nutzer hat die Bezahlung im Bezahldienst erfolgreich durchgeführt.
  • FAILED - der Vorgang wurde vom Bezahldienst aufgrund der Nutzereingaben final abgebrochen.
  • CANCELED - der Nutzer hat die Bezahlung im Bezahldienst final abgebrochen.

Possible values: [INITIAL, PAYED, FAILED, CANCELED]

statusDetailstring

Optionale ergänzende Erläuterungen zum Status. Diese Informationen werden Teil des Antrags und bieten dem Bezahldienst die Möglichkeit Informationen an das Fachverfahren / Sachbearbeitung zu schicken. Grundsätzlich ist dieses Feld nicht notwendig - Inhalte sind zwischen Bezahldienst und Fachverfahren abzustimmen.

Possible values: non-empty and <= 99 characters, Value must match regular expression ^[\w-]+$

Example: Transaktion-XYZ_wurde_erfolgreich_gebucht_auf_Konto_ABC_in_Hoehe_von_36EUR
paymentRequest object
requestIdstringrequired

Die Request-ID wird vom Online-Dienst vergeben und vom Bezahldienst abgelegt.

Possible values: non-empty and <= 36 characters, Value must match regular expression ^[\w-]+$

Example: XYZ12345-2021
requestTimestampdate-timerequired

Zeitstempel des Online-Antrags / Payment-Requests.

Example: 2025-10-06T14:32:00.711+02:00
currencystringrequired

Im ersten Schritt ist hier nur 'EUR' vorgesehen. Perspektivisch sollte hier die entsprechende ISO-Norm referenziert werden.

Possible values: >= 3 characters and <= 3 characters, Value must match regular expression ^[\w]+$

Example: EUR
grossAmountdoublerequired

Der Gesamtbetrag dient dem Bezahldienst zur Validierung der einzelnen Positionen.

Possible values: > 0 and <= 999999

Example: 30
purposestring

Verwendungszweck / Buchungstext der Payment Transaction.

Possible values: non-empty and <= 27 characters, Value must match regular expression ^[\w\s-]+$

Example: Antrag fuer Antragsformular
descriptionDatatypeC (string)

N Die Beschreibung des Payment Requests. Kann auf der Paypage / PSP Seite angezeigt werden.

Possible values: non-empty and <= 250 characters

Example: Anträge für Antragsformulare
redirectUrlurirequired

Rücksprung-URL vom Bezahldienst zum Online-Dienst. Der Status (Erfolg / Abbruch) muss über die Statusabfrage (GET) abgefragt werden.

Possible values: non-empty and <= 2082 characters

Example: https://efa-od-xy.de/sdfsdfsdf/success?sid=DSYXD1234FSD
items object[]required

Possible values: >= 1, <= 99

  • Array [
    • idstringrequired

    ID der Position vom Online-Dienst vergeben

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[\w-]+$

    Example: 01
    referencestringrequired

    Eine fachliche Referenz auf den "Artikel" bzw. den Inhalt der Position.

    Possible values: non-empty and <= 36 characters, Value must match regular expression ^[\w-]+$

    Example: XYZ22113
    descriptionDatatypeC (string)

    Beschreibung der Position vom Online-Dienst zur Verwendung z. B. auf der Pay-Page.

    Possible values: non-empty and <= 250 characters

    Example: XYZ22113-01 - Antrag auf Erteilung eines Antragsformulars
    taxRatedoublerequired

    Steuersatz als Prozentbetrag

    Possible values: >= 0 and <= 100

    Example: 19
    quantityint32required

    Possible values: >= 1 and <= 999999

    Example: 3
    totalNetAmountdoublerequired

    Nettobetrag der Position

    Possible values: > 0 and <= 999999

    Example: 25.2
    totalTaxAmountdoublerequired

    Steuerbetrag der Position

    Possible values: >= 0 and <= 999999

    Example: 4.8
    singleNetAmountdoublerequired

    Nettobetrag der Position

    Possible values: > 0 and <= 999999

    Example: 8.4
    singleTaxAmountdoublerequired

    Steuerbetrag der Position

    Possible values: >= 0 and <= 999999

    Example: 1.6
    bookingData object

    Container für Key-Value-Paare für zusätzliche Informationen für die Verbuchung im Bezahldienst oder nachgelagerten Systemen

    property name*string
  • ]
    • requestor object
    anyOf
    requestorTyperequired

    Possible values: [INDIVIDUAL, ORGANIZATION]

    nameDatatypeA (string)required

    Familienname des Bezahlers

    Possible values: non-empty and <= 250 characters

    Example: Mustermann
    firstNameDatatypeA (string)required

    Vorname(n) des Bezahlers

    Possible values: non-empty and <= 250 characters, Value must match regular expression ^[\w\s\-,\.\u00C0-\u017F]+$

    Example: Max
    genderstring

    Geschlecht des Bezahlers: (M)ale=Männlich, (F)emale=Weiblich, (D)iverse=Divers

    Possible values: [M, F, D]

    address objectrequired
    addressType

    Possible values: [POSTAL_ADDRESS]

    addressLine1DatatypeB (string)required

    Die Hauptzeile einer Anschrift. Üblicherweise ist dies entweder Straße und Hausnummer oder der Text 'Postfach' gefolgt von der Postfachnummer.

    Possible values: non-empty and <= 250 characters

    Example: Wilhelmstraße 97
    addressLine2DatatypeB (string)

    Eine zusätzliche Adresszeile in einer Anschrift, die verwendet werden kann, um weitere Einzelheiten in Ergänzung zur Hauptzeile anzugeben.

    Possible values: non-empty and <= 250 characters

    addressLine3DatatypeB (string)

    Eine zusätzliche Adresszeile in einer Anschrift, die verwendet werden kann, um weitere Einzelheiten in Ergänzung zur Hauptzeile anzugeben.

    Possible values: non-empty and <= 250 characters

    cityDatatypeB (string)required

    Die Bezeichnung der Stadt oder Gemeinde, in der sich die Anschrift befindet.

    Possible values: non-empty and <= 250 characters

    Example: Berlin
    postalCodestringrequired

    Die Postleitzahl.

    Possible values: non-empty and <= 16 characters

    Example: 10117
    countrySubdivisionDatatypeB (string)

    Die Unterteilung eines Landes (wie Region, Bundesland, Provinz etc.).

    Possible values: non-empty and <= 250 characters

    countryCodestringrequired

    Ein Code, mit dem das Land bezeichnet wird. Anmerkung: Die Liste der zulässigen Länder ist bei der ISO 3166-1 'Codes for the representation of names of countries and their subdivisions' erhältlich. Nur die Alpha-2-Darstellung darf verwendet werden.

    Possible values: >= 2 characters and <= 2 characters, Value must match regular expression ^[A-Z]{2}$

    Example: DE
    PaymentTransaction
    {
      "paymentInformation": {
        "transactionUrl": "https://payment.bundesland.zzzz/api/v1/paymenttransaction/12002312/MELD-ANT-FORM-4711/9xxd-432x-6543-xfd6-gfdx-fd27",
        "transactionRedirectUrl": "https://portal.bundesland.zzzz/ui/doPayment/9xxd-432x-6543-xfd6-gfdx-fd27-CHECKSUM",
        "transactionId": "9xxd-432x-6543-xfd6-gfdx-fd27",
        "transactionReference": "KA-2020-1234",
        "transactionTimestamp": "2025-10-06T12:32:00.711Z",
        "paymentMethod": "CREDITCARD",
        "paymentMethodDetail": "Visa",
        "status": "INITIAL",
        "statusDetail": "Transaktion-XYZ_wurde_erfolgreich_gebucht_auf_Konto_ABC_in_Hoehe_von_36EUR"
      },
      "paymentRequest": {
        "requestId": "XYZ12345-2021",
        "requestTimestamp": "2025-10-06T14:32:00.711+02:00",
        "currency": "EUR",
        "grossAmount": 30,
        "purpose": "Antrag fuer Antragsformular",
        "description": "Anträge für Antragsformulare",
        "redirectUrl": "https://efa-od-xy.de/sdfsdfsdf/success?sid=DSYXD1234FSD",
        "items": [
          {
            "id": "01",
            "reference": "XYZ22113",
            "description": "XYZ22113-01 - Antrag auf Erteilung eines Antragsformulars",
            "taxRate": 19,
            "quantity": 3,
            "totalNetAmount": 25.2,
            "totalTaxAmount": 4.8,
            "singleNetAmount": 8.4,
            "singleTaxAmount": 1.6,
            "bookingData": {
              "haushaltstelle": "1234",
              "objektnummer": "0815",
              "href": "AlphaBetaGamma"
            }
          }
        ],
        "requestor": {
          "requestorType": "INDIVIDUAL",
          "name": "Mustermann",
          "firstName": "Max",
          "gender": "M",
          "address": {
            "addressType": "POSTAL_ADDRESS",
            "addressLine1": "Wilhelmstraße 97",
            "addressLine2": "string",
            "addressLine3": "string",
            "city": "Berlin",
            "postalCode": "10117",
            "countrySubdivision": "string",
            "countryCode": "DE"
          }
        }
      }
    }