Vorwort

Dieser Leitfaden soll dabei helfen, Bezahlmöglichkeiten in Online-Angebote des öffentlichen Dienstes zu integrieren. Dazu wird das Vorgehen für die Anbindung von Online-Diensten an die ePayBL beschrieben und Hinweise für Testmöglichkeiten gegeben. 

Letztlich maßgeblich für die Anbindung an die ePayBL und für Detailinformationen sind das Integrationshandbuch ePayBL-Konnektor des Softwareherstellers in der jeweils neusten Version sowie die Spezifikation der XBezahldienste der FITKO (https://docs.fitko.de/xbezahldienste).  

Schnittstellen und Software Development Kit (SDK)

Die Kommunikation mit der ePayBL läuft ausschließlich über eine REST API. In der Softwaredokumentation des Herstellers der ePayBL wird dies auch Konnektor genannt. Es muss ein entsprechender HTTPS-Request gesendet und die Response verarbeitet werden.

Es gibt grundsätzlich zwei Schnittstellen an der ePayBL:

1. die native ePayBL Schnittstelle
2. XBezahldienste Schnittstelle (Standard des IT-Planungsrates).

Die Nutzung der nativen ePayBL Schnittstelle empfiehlt sich lediglich für bestehende Anbindungen. Neue Anbindungen nutzen grundsätzlich die XBezahldienste Schnittstelle. Diese ist für EfA Dienste deutschlandweit verpflichtend und wird es für alle Dienste / Anbindungen ebenso werden. 

Weiterhin gibt es verschiedene  Software Development Kits, genannt Konnektor-Client-Bibliothek (z.B. für PHP oder Java). U.a. aufgrund unklarer Supportprozesse werden diese nicht unterstützt. 

  Vorgehen und Parameter in diesem Leitfaden beziehen sich stehts auf die Anbindung mittels XBezahldienste Schnittstelle. 

Vorgehen

Das Vorgehen wird nachfolgend Schritt für Schritt erläutert. Für Testzwecke stellt Dataport einen eigenen Mandanten in der Stage-Umgebung zur Verfügung. Dieser kann gerne genutzt werden. 

Für eine reibungslose Integration wird die Integration in drei Schritten empfohlen:

Begriffe

In diesem und in verlinkten Dokumenten werden die Begriffe "Stage", "Stage-Umgebung", "Stage-System" und "Test-Umgebung" bedeutungsgleich genutzt. D.h. die Begriffe meinen dasselbe. Dies ist historisch entstanden, weil Dokumentationen teils für verschiedene Zielgruppen oder von verschiedenen Abteilungen erstellt wurden. 

Dasselbe gilt für die Begriffe "Live", "Live-Umgebung", "Produktion" und "Produktionsumgebung", die untereinander austauschbar sind.

Allgemeine Voraussetzungen

Vor dem Start der erstmaligen Integration mit dem Testmandanten sollten folgende Punkte geklärt sein:

• Die ePayBL-Schnittstelle (s. unten) ist technisch aus Ihrem Netzwerk erreichbar.

Vor dem Start der Integration eines kundenspezifischen Mandanten (Kommune/Behörde/Land) sollten zudem folgende Punkte geklärt sein:

• Mandantennummer und Bewirtschafternummer für den anzubindenden Mandanten sind Ihnen bekannt. Bitte erfragen Sie diese anderenfalls bei Ihrem Kunden oder Auftraggeber. (Zum Verständnis: Ein "Mandant" ist eine Organisationseinheit in der ePayBL (Kommune, Behörde, Verwaltungseinheit - z.B. "Amt Kellinghusen"), die Mandantennummer ist das interne Kürzel für diesen Mandanten (z.B. "SHAMTKHN" für das Amt Kellinghusen). Ein Bewirtschafter ist ein Online-Dienst (z.B. "Gewerbeanmeldung") des jeweiligen Mandanten. Die Bewirtschafternummer ist entsprechend das interne Kürzel für diesen Bewirtschafter (z.B. "GAN") für die Gewerbeanmeldung.

Zertifikat

Für den Zugriff auf die ePayBL wird ein mandatenspezifisches Webservice-Zertifikat benötigt. Dieses stellt sicher, dass eine geschützte Verbindung aufgebaut werden kann. Falls noch nicht vorhanden, wird das Zertifikat so beantragt und eingesetzt:

1. Rufen Sie die Seite zur Beantragung eines neuen Zertifikats auf. Abhängig davon, ob es um einen Mandanten auf der Produktiv- oder Stage/Test-Plattform geht, müssen Sie eine der beiden Varianten wählen:
   1. Für Mandanten auf der Stage/Test-Plattform: https://epayment-stage.dataport.de/paycert/
   2. Für Mandanten auf der Produktiv-Plattform: https://epayment.dataport.de/paycert/ 
2. Tragen Sie die Mandantennummer für Ihren Mandanten ein und Klicken Sie auf „Weiter zum Antrag“
3. Folgen Sie bei Fragen dieser Anleitung: Beantragung eines Webservice-Zertifikats in der ePayBL (dataport.de)

• Geben Sie Ihren echten Vor- und Nachnamen als Antragsteller und in den Feldern "Vorname (Besitzer)" und "Nachname (Besitzer)" Ihre Firma an. Bitte verwenden Sie im Folgenden vor allem Ihre echte E-Mailadresse. Dies dient dazu, dass das Produktmanagement Payment Ihre Anfrage zuordnen und Sie bei Bedarf erreichen kann.
• Geben Sie das Bundesland als Länderkürzel ein, z.B. "SH" (Liste Länderkürzel beim BMBF)
• Geben Sie als Land "DE" ein - und nicht z.B. "Deutschland"

Für die Einrichtung mit dem Test-Mandanten gehen Sie entsprechend wie folgt vor:

1. Rufen Sie https://epayment-stage.dataport.de/paycert/ auf
2. Tragen Sie "DPEFA1" als Mandantennummer ein
3. Füllen Sie das Formular nach diesem Beispiel - mit Ihren echten Daten und unter Berücksichtigung der o.g. Hinweise - aus:

4. Folgen Sie weiter der o.a. Anleitung: Beantragung eines Webserver-Zertifikats in der ePayBL (dataport.de)

Die Freischaltung passiert i.d.R. innerhalb von 1 bis 2 Arbeitstagen.

Allgemeine Informationen zur Schnittstelle

Die Anbindung an die ePayBL erfolgt grundsätzlich an die XBezahldienste-Schnittstelle. XBezahldienste ist eine standardisierte Programmierschnittstelle, welche Onlinedienste mit dezentralen Bezahldiensten verbindet. Die Standardschnittstelle ist unabhängig von der beteiligten Behörde und deren technischen Voraussetzungen. Für alle Dienste nach dem EfA Prinzip (Einer für Alle) ist die Schnittstelle schon heute verpflichtend. Da diese Schnittstelle perspektivisch für alle Dienste verpflichtend wird, werden Neuanbindungen schon jetzt nur hierüber realisiert.

Basis-URL

Für den unten genutzten Parameter "Basis-URL" sind die folgenden Angaben zu nutzen

https://epayment-stage.dataport.de/konnektor/epayment

https://epayment.dataport.de/konnektor/epayment

Schnittstelle XBezahldienste  

Es gilt der Standard XBezahldienste der FITKO. Die aktuelle Spezifikation ist unter https://docs.fitko.de/xbezahldienste/spec zu finden. Zu beachten sind insbesondere Pflichtparameter, Längenbeschränkungen (Constraints) und erlaubte Zeichen (Pattern).

Als originatorId gemäß XBezahldienste ist stets die ePayBL-Mandantennummer zu verwenden. Als endPointId gemäß XBezahldienste ist stets die ePayBL-Bewirtschafternummer zu verwenden.

Endpunkt: Anlegen eines Bezahlvorgangs

POST {Basis-URL}/paymenttransaction/{mandantennummer}/{bewirtschafternummer}

Endpunkt: Statusabfrage zu einem Bezahlvorgang

GET {Basis-URL}/paymenttransaction/{mandantennummer}/{bewirtschafternummer}/{transactionId}

Ablaufdiagramm

Quelle und weitere Informationen: https://docs.fitko.de/xbezahldienste/APIDoku/41_1_AblaufKommunikation

Parametrisierung & Testaccount

Mandantennummer und Bewirtschafternummer

Die Mandanten bekommen für den tatsächlichen Betrieb die jeweiligen Mandantennummer und Bewirtschafternummer der Kreise & Kommunen. Zum allgemeinen Test (Phase 1 des Vorgehens) haben wir folgenden Mandanten in der Stage Umgebung:

Mandantennummer und Bewirtschafternummer sind case-sensitiv.

Kontierungsinformationen (bookingData)

Als Haushaltsstelle und Objektnummer (Produkt- und Sachkonto) sind mehrere Kombinationen zum Test eingerichtet. Verwendbar sind:

(leer/null)

Damit lassen sich bei Bedarf auch unterschiedliche Kombinationen aus Haushaltsstellen/Objektnummern testen bzw. auch die Aufteilung eines Vorgangs auf mehrere Haushaltsstellen/Objektnummern.

Weiterhin ist ein Parameter für den HKR Mandantencode in den bookingData zu übergeben, sofern dies eine fachliche Anforderung an den Online Dienst ist:

"bookingData": {
   "haushaltstelle": "1000",
   "objektnummer": "2000",
   "hkrmandantencode": "01"
}

Der zweistellige Mandantencode ist dabei als String zu übergeben

Kassenzeichen

Das Kassenzeichen wird grundsätzlich in der ePayBL generiert und startet im Testmandanten DPEFA1 mit einem Präfix „DPEFA“ und einer fortlaufenden Nummer. Es ist 22 Zeichen lang.

Testdaten für Kreditkarte, Giropay und Lastschrift im Testaccount

Am Mandanten haben wir unseren Dataport Girocheckout Testaccount hinterlegt.

Testdaten vom Girocheckout:

• Kreditkarte https://api.girocheckout.de/girocheckout:testdata#kreditkarte 
• Giropay  https://api.girocheckout.de/girocheckout:testdata#giropay
• Lastschrift: https://api.girocheckout.de/girocheckout:testdata#lastschrift

Weitere Zahlungsarten sind nicht konfiguriert. 

Verwendungszweck / Buchungstext / Beschreibung für den Nutzer

Es gibt mehrere Parameter, die es ermöglichen Informationen dem Nutzer anzuzeigen bzw. Informationen zur Verbuchung an das HKR-System durchzureichen.

	purpose (Zahlvorgang)	description (Zahlvorgang)	description (Buchungsposition)
Parameter XBezahldienste fachlich	purpose des Zahlvorgangs	description des Zahlvorgangs	description der Buchungsposition
Parameter XBezahldienste technisch	paymentRequest.purpose	paymentRequest.description	paymentRequest.items[n].description
fachliche Verwendung	ein Buchungstext für das HKR-System	eine Beschreibung für den Nutzer / den Zahler zur Anzeige auf der ePayBL Paypage	Buchungstexte für die einzelnen Buchungspositionen
Anzeige auf Paypage
Anzeige in XFinanz	in <xfn:buchungstext> und <xfn:verwendungszweck> vollständiger Pfad: <xfn:aODoppisch> <xfn:aOPosDoppisch> <xfn:gemeinsameBuchungsdaten>

typische Fragen und Fehlermeldungen

Feedback erwünscht

Im Falle von Fehler und auch zur allgemeinen Nutzung dieser Dokumentation freuen wir uns ausdrücklich über Feedback an das Dataport Produktmanagement Payment. Bitte nutzen Sie dazu unser Funktionspostfach - die Adresse erhalten Sie ggf. von Ihrem Berater.