Zum Hauptinhalt springen
Version: 1.0.0

Abfrage einer Payment Transaction. Insb. um den Status zu prüfen

GET 
/paymenttransaction/:originatorId/:endPointId/:transactionId

Abfrage einer Payment Transaction. Insb. um den Status zu prüfen

Request​

Path Parameters

    originatorId stringrequired

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

    Enthält die Kennung des auslösenden Online-Dienstes, z. B. den fachlichen Kontext.

    Example: MELD-ANT-FORM-4711
    endPointId stringrequired

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

    Enthält ein weiteres Ordnungskriterium für die Identifikation der zuständigen Behörde, z. B. den AGS

    Example: BERLIN
    transactionId stringrequired

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

    Vom Bezahldienst vergebene Transaktions-ID - kann auch das Kassenzeichen sein

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

Responses​

OK

Schema

    paymentInformation

    object

    required

    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\d-]+$

    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\d-]+$

    Example: KA-2020-1234
    transactionTimestampdate-time

    Zeitstempel der erfolgreichen Durchführung der Bezahlung.

    paymentMethodstring

    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\d-]+$

    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: <= 99 characters, Value must match regular expression ^[\w\d-]+$

    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\d-]+$

    Example: XYZ12345-2021
    requestTimestampdate-timerequired

    Zeitstempel des Online-Antrags / Payment-Requests.

    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
    grosAmountdoublerequired

    Der Gesamtbetrag dient dem Bezahldienst zur Validierung der einzelnen Positionen.

    Possible values: <= 999999

    Example: 30
    purposestring

    Verwendungszweck / Buchungstext der Payment Transaction.

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

    Example: Antrag fuer Antragsformular
    descriptionstring

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

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

    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\d-]+$

    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\d-]+$

    Example: XYZ22113
    descriptionstring

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

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

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

    Steuersatz als Prozentbetrag

    Possible values: <= 100

    Example: 19
    quantityint64required

    Possible values: >= 1 and <= 999999

    Example: 3
    totalNetAmountdoublerequired

    Nettobetrag der Position

    Possible values: <= 999999

    Example: 25.2
    totalTaxAmountdoublerequired

    Steuerbetrag der Position

    Possible values: <= 999999

    Example: 4.8
    singleNetAmountdoublerequired

    Nettobetrag der Position

    Possible values: <= 999999

    Example: 8.4
    singleTaxAmountdoublerequired

    Steuerbetrag der Position

    Possible values: <= 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

    namestringrequired

    Familienname des Bezahlers

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

    Example: Mustermann
    firstNamestringrequired

    Vorname(n) des Bezahlers

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

    Example: Max
    genderstring

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

    Possible values: [M, F, D]

    isOrganizationboolean

    Wahr für Organisationen / juristische Personen, Falsch für 'natürliche' Antragsteller

    Example: true
    organizationNamestring

    Soll nur existieren, wenn isOrganization == true

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

    Example: Bundesministerium der Finanzen

    address

    object

    required

    streetstring

    Strasse

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

    Example: Wilhelmstraße
    houseNumberstring

    Hausnummer

    Possible values: <= 20 characters, Value must match regular expression ^[\w\d-]+$

    Example: 97
    addressLinestring[]

    Zum Abbilden von Internationalen Adressen werden generische "Adresszeilen" verwendet und nicht "Straße / Hausnummer".

    Possible values: <= 9

    Example: ["Dienstsitz Berlin","Postanschrift: 11016 Berlin"]
    postalCodestring

    Postleitzahl

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

    Example: 10117
    citystring

    Stadt

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

    Example: Berlin
    countrystring

    ISO 3166-1, Alpha-2 code, zwei Großbuchstaben

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

    Example: DE