Ablauf der Kommunikation
Jeder Endpunkt der XBezahldienste-konformen API wird über zwei Pfadparameter adressiert: originatorId identifiziert den auslösenden Online-Dienst (z. B. den fachlichen Kontext des Antrags), endPointId identifiziert die zuständige Behörde (z. B. den AGS). Die Basis-URL des Bezahldienstes wird dem Online-Dienst über ein Diensteverzeichnis (z. B. XZuFi) oder direkte Konfiguration bekannt gemacht.
Schnittstellen im Überblick
Zahlungsabwicklung
Endpunkte zum Initiieren und Verfolgen von Zahlungsvorgängen.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
POST | /paymenttransaction/{originatorId}/{endPointId} | Zahlung initiieren |
GET | /paymenttransaction/{originatorId}/{endPointId}/{transactionId} | Status abfragen |
GET | /payment-methods/{originatorId}/{endPointId} | Zahlarten abfragen |
Betrieb
Endpunkte zur Überwachung des Bezahldienstes und zur Abfrage von Wartungsinformationen.
| Methode | Endpunkt | Beschreibung |
|---|---|---|
GET | /status | Globaler Dienststatus |
GET | /status/{originatorId}/{endPointId} | Endpoint-Status |
GET | /maintenance/{originatorId}/{endPointId} | Wartungsfenster abfragen |
Ablauf einer Zahlung
Vor der Initiierung einer Zahlung kann der Online-Dienst optional prüfen, welche Zahlarten aktuell verfügbar sind (GET /payment-methods) und ob Wartungsfenster geplant sind (GET /maintenance).
Die Zahlung wird mit einem POST auf /paymenttransaction initiiert. Der Online-Dienst übermittelt dabei einen PaymentRequest mit den Zahlungspositionen und einer redirectUrl, zu der der Nutzer nach dem Bezahlvorgang zurückgeleitet wird. Der Bezahldienst legt eine PaymentTransaction an und gibt eine transactionId sowie eine transactionRedirectUrl zurück — die URL der Paypage, zu der der Online-Dienst den Nutzer weiterleiten muss.
Auf der Paypage wählt der Nutzer eine Zahlart, gibt seine Zahlungsdaten ein und autorisiert die Zahlung. Anschließend leitet der Bezahldienst den Nutzer auf die redirectUrl des Online-Dienstes zurück. Diese Weiterleitung enthält keinen Zahlungsstatus. Der Online-Dienst muss den Status anschließend aktiv per GET /paymenttransaction abfragen.
Der HTTP-Header X-XBezahldienste-Version kann mit jeder Anfrage gesendet werden und gibt die vom Client verwendete Schnittstellenversion an (z. B. 1.2.0). Der Header ist aktuell optional, ist ab Version 2.0 der Spezifikation jedoch als verpflichtend vorgesehen.