Konzepte & Anwendung
Dieser Abschnitt erklärt die zentralen Konzepte der XBezahldienste-Schnittstelle: wie Zahlungen initiiert und verfolgt werden, was die Statuswerte bedeuten, wie ein Online-Dienst die nötigen Verbindungsparameter bezieht und welche Zeichensätze in welchen Feldern zulässig sind.
Ablauf der Kommunikation
Beschreibt alle sechs Endpunkte der Schnittstelle und erläutert den typischen Ablauf einer Zahlung: optionale Vorabprüfung der Zahlarten und Wartungsfenster, Initiierung per POST /paymenttransaction, Weiterleitung auf die Paypage des Bezahldienstes und abschließende Statusabfrage per GET. Enthält ein Sequenzdiagramm des vollständigen Ablaufs.
API-Versionierung
Erklärt, wie Semantic Versioning (semver) auf die XBezahldienste-Schnittstelle angewendet wird: Nur Major-Versionen erhalten einen neuen URL-Pfad (/v1/, /v2/). Minor- und Patch-Versionen sind rückwärtskompatibel und müssen unter demselben Pfad ausgeliefert werden. Enthält konkrete Anforderungen an Bezahldienste und klärt, warum separate Endpunkte für Minor-Versionen nicht konform sind.
Statusmodell
Erklärt die vier Statuswerte (INITIAL, PAYED, CANCELED, FAILED) aus zwei Perspektiven: was der Online-Dienst nach dem Rücksprung von der Paypage tun soll, und wann der Bezahldienst welchen Endstatus setzen darf. Klärt insbesondere, warum INITIAL bestehen bleibt, wenn ein Nutzer eine Zahlart abbricht und eine andere wählt.
Parametrisierung
Beschreibt, wie ein Online-Dienst Verbindungsparameter (Basis-URL, OriginatorId, EndpointId, PaymentItems) zur Laufzeit aus PVOG und DVDV bezieht, bevor der erste API-Aufruf abgesetzt wird. Enthält auch die Sicht des Bezahldienstes: Mandantenkonfiguration, BookingData-Anforderungen und DVDV-Pflege.
DIN 91379 und Zeichenkodierung
Legt fest, welche DIN-Datentypen (A, B, C, D) in welchen Schnittstellen-Feldern gelten, und erklärt ab Version 1.2.0, warum die Validierungsverantwortung beim Bezahldienst liegt — nicht mehr in der OpenAPI-Spezifikation. Enthält eine vollständige Feldzuordnung inklusive der veralteten Schemas RequestorLegacy und Address.