Parametrisierung

Die XBezahldienste-API wird nicht statisch konfiguriert, sondern zur Laufzeit parametrisiert: Der Online-Dienst bezieht alle nötigen Verbindungsparameter aus zentralen Infrastrukturen (PVOG und DVDV), bevor er den ersten API-Aufruf absetzt.

Parametrisierungsleitfaden

Vollständige und verbindliche Informationen zur EfA-Parametrisierung — inkl. XZuFi-Verortung, PVOG-API, DVDV-Lookup und Sicherheitshinweise — sind im Parametrisierungsleitfaden dokumentiert. Diese Seite gibt einen Überblick aus Sicht der XBezahldienste-Schnittstelle.

Aktuelle Information des BMI: https://www.digitale-verwaltung.de/Webs/DV/DE/onlinezugangsgesetz/rahmenarchitektur/efa-parametrisierung/efa-parametrisierung-node.html (öffnet in neuem Tab)

Parameter im Überblick

Parameter	Schlüssel / Feld	Quelle	XBezahldienste-Entsprechung
PaymentServiceBaseUrl	ServiceElementUri	DVDV	Basis-URL für alle API-Aufrufe
Unterstützte Versionen	ServiceElementText.Versionen	DVDV	URL-Versionspräfix (/v1/, /v2/)
Zertifikat des Bezahldienstes	cipherCertificate	DVDV	TLS-Truststore des Online-Dienstes
Requestor-Daten übermitteln	efa.payment.uebermittlungInkassoDaten (PVOG) + submitRequestorData (DVDV)	DVDV + PVOG	Entscheidet, ob requestor im PaymentRequest befüllt wird
Referenz auf Bezahldienst	efa.payment.paymentserviceid	PVOG	Startpunkt des DVDV-Lookups
OriginatorId	efa.payment.originatorid	PVOG	Pfadparameter {originatorId}
EndpointId	efa.payment.endpointid	PVOG	Pfadparameter {endPointId}
PaymentItem	efa.payment.paymentitem	PVOG	PaymentRequest.items[]

Aus Sicht des Online-Dienstes

Vor dem ersten POST /paymenttransaction sind folgende Schritte erforderlich:

1. Bezahldienst-Parameter ermitteln

Im Standardfall werden alle Verbindungsparameter aus PVOG und DVDV bezogen. Der Einstiegspunkt ist efa.payment.paymentserviceid aus PVOG — dieser enthält den OrganizationKey des Bezahldienstes im DVDV. Zusammen mit der ServiceSpecificationUri urn:dvdv:setup:example:bezahldienst:1 wird per DVDV-Lookup (findServiceDescription) das DienstElement "Bezahldienst-Server" ermittelt. Daraus werden bezogen:

• PaymentServiceBaseUrl (getServiceElementUri()) — Basis-URL für alle API-Aufrufe
• Unterstützte Versionen (getServiceElementText() → JSON-Feld Versionen) — bestimmt den URL-Versionspräfix
• Zertifikat (getCipherCertificate().getContent()) — muss vor dem TLS-Verbindungsaufbau in den Truststore eingefügt werden

Pragmatischer Fallback

In der Praxis sind DVDV und PVOG nicht immer vollständig befüllt. Online-Dienste können Parameter auch direkt als Anwendungskonfiguration einbauen — in Abstimmung mit dem jeweiligen Bezahldienst und der zuständigen Behörde. Wichtig ist dabei, die grundlegende Struktur der EfA-Parametrisierung (Schlüsselnamen, Parameter-Semantik) beizubehalten, um einen späteren Wechsel auf registry-basierte Quellen ohne Schnittstellenänderung zu ermöglichen.

2. API-URL aufbauen

{PaymentServiceBaseUrl}/v{Version}/paymenttransaction/{originatorId}/{endPointId}

Beispiel: https://payserver.example.com/payservice/v1/paymenttransaction/GEBURTSURKUNDE/11009009

Jede Anfrage kann zusätzlich den HTTP-Header X-XBezahldienste-Version: 1.2.0 tragen, der die verwendete Schnittstellenversion angibt. Er ist in Version 1.x optional, ist ab Version 2.0 der Spezifikation jedoch als verpflichtend vorgesehen.

3. OriginatorId und EndpointId aus PVOG

Beide Parameter werden per PVOG-API (/v2/onlineservices/detail) als efa.payment.originatorid und efa.payment.endpointid bezogen. Sie identifizieren gemeinsam den Mandanten beim Bezahldienst. Anfragen mit unbekannten Kombinationen werden mit 404 NO_VALID_ORIGINATOR_OR_ENDPOINT abgelehnt.

4. PaymentItems parametrisieren

Das PVOG-Feld efa.payment.paymentitem enthält ein JSON-Objekt, das direkt auf ein Element in PaymentRequest.items[] abgebildet wird:

EfA-Parameterwert	XBezahldienste-Feld
paymentItemReference (Pflicht)	items[].reference
bookingData (optional)	items[].bookingData
paymentItemID (optional)	items[].id (Best Practice)

Bei mehreren Leistungen (Gemischter Warenkorb) können mehrere efa.payment.paymentitem-Parameter mit unterschiedlichen paymentItemID-Werten eingetragen sein. Die paymentItemID erlaubt dem Online-Dienst, die PVOG-Werte seinen Geschäftsobjekten zuzuordnen.

Veraltete Parameter

Die Einzelparameter efa.payment.paymentitemreference und efa.payment.bookingdata sind seit V1.0.1 veraltet und werden durch efa.payment.paymentitem ersetzt. Bei der Migration auf XZuFi 2.3 wird eine Umstellung dringend empfohlen.

5. Requestor-Daten: wann requestor befüllen?

Das requestor-Feld im PaymentRequest darf nur befüllt werden, wenn beide Bedingungen erfüllt sind:

• DVDV: submitRequestorData = true (Bezahldienst bietet Mahn-/Inkassoverfahren an)
• PVOG: efa.payment.uebermittlungInkassoDaten ist nicht gesetzt oder hat den Wert "Ja"

Andernfalls gilt DSGVO-Datensparsamkeit: keine personenbezogenen Daten des Antragstellers übermitteln.

Aus Sicht des Bezahldienstes

Der Bezahldienst ist für die Mandantenkonfiguration und die Kommunikation seiner Anforderungen an den Online-Dienst verantwortlich. Die Pflege der DVDV- und PVOG-Einträge liegt in der Verantwortung der jeweiligen Behörde.

• Mandanten konfigurieren: Für jede zulässige originatorId/endPointId-Kombination muss ein Mandant eingerichtet sein. Unbekannte Kombinationen werden mit 404 NO_VALID_ORIGINATOR_OR_ENDPOINT abgelehnt.
• BookingData-Pflichtfelder kommunizieren: Welche Schlüssel in bookingData erwartet werden, ist bezahldienst- und ggf. mandantenspezifisch. Fehlende Pflichtfelder führen zu 400 BOOKING_DATA_MISSING. Diese Anforderungen müssen dem Online-Dienst im Rahmen der Integration mitgeteilt werden.
• DVDV-Eintrag: Das DienstElement "Bezahldienst-Server" enthält PaymentServiceBaseUrl, unterstützte Versionen (Versionen-Array) und das TLS-Zertifikat. Die Datenpflege im DVDV erfolgt durch die Behörde über speziell berechtigte Datenpfleger.
• submitRequestorData: Wenn der Bezahldienst Mahn-/Inkassoverfahren anbietet, ist submitRequestorData = true im DVDV-Eintrag zu setzen (durch die Behörde).