Vorwort & Zielrahmen

Dieses Dokument soll dabei helfen, Bezahlmöglichkeiten in Online-Angebote des öffentlichen Dienstes zu integrieren. Dazu wird das technische Vorgehen für die Anbindung von Online-Diensten an den Plattformdienst Payment beschrieben und Hinweise für Testmöglichkeiten gegeben. Zielgruppe sind von Dataport entwickelte bzw. betriebene Online Dienste.

Dieses Dokument ist ein Best-Practice-Leitfaden zur Anbindung und ergänzt die technische Dokumentation: Plattformdienst Payment Anbindung

Die hier beschriebene Umsetzung basiert auf den vom Produktmanagement entwickelten Standard-ePayment-Use-Cases. 

wichtige Begrifflichkeiten

Mandant / Zahlungsmandant

Im OSI Kontext wird der Begriff Mandant typischerweise als HH, SH, ST HB oder GO verstanden. Im Kontext des Payments ist ein Mandant ein Account der nutzenden Einheit (Kommune, Behörde) in der ePayBL. Im Plattformdienst Payment wird deshalb auch zur Verdeutlichung oftmals von Zahlungsmandanten gesprochen.

Bewirtschafter

Ein Bewirtschafter ist in der ePayBL eine organisatorische Einheit unterhalb der Mandanten. Jeder Online Dienst bekommt einen eigenen Bewirtschafter zur logischen Trennung.

Grundlagen

Die Kommunikation mit dem Plattformdienst Payment läuft über eine REST API. Es muss ein entsprechender HTTPS-Request gesendet und die Response verarbeitet werden. Es müssen die Statusinformationen aus den Aufrufen der returnURLs (Success, Error, Cancel, ggf. asyncSuccess) verarbeitet werden.

beteiligte Systeme & Akteure

Schaubild 1 - Von Dataport betriebener Online Dienst mit Zahlungsabwicklung über die ePayBL bei Dataport - vereinfachte Darstellung

Schaubild 2 -Von Dataport betriebener Online Dienst mit Zahlungsabwicklung über eine externe Bezahlplattform (EfA-Roll-Out) - vereinfachte Darstellung

Aufgaben beteiligter Systeme in Bezug auf die Bezahlabwicklung

Online Dienst

• Ermittlung der Gebühren für den Zahlungsvorgang
• Ermittlung von Payment Parametern wie Mandanten, Bewirtschafter, Buchungsdaten 
• Nimmt die Rückmeldung zum Status von PD Payment entgegen und steuert daraufhin Folgeaktionen (z.B Dokumentenerzeugung oder Kommunikation an Fachverfahren)

PD Payment (Plattformdienst Payment)

• Prüfung Berechtigungen (z.B. ob der Online Dienst für den Zahlungsmandanten berechtigt ist)
• Routing des Zahlungsvorgangs anhand von Mandant & Bewirtschafter
• Weitergabe der erhaltenen Buchungsdaten
• Verwaltung der Webservice-Zertifikate zur Kommunikation mit der ePayBL / externen Bezahlplattform

ePayBL

• Freischaltung/Administration von Zahlungsarten am jeweiligen Mandanten
• Bereitstellung einer ePayBL-Paypage für den Nutzer zur Auswahl der Zahlungsart
• Erzeugung von XFinanz Dateien (Soll Buchung)
• Erzeugung von camt.054 Dateien (Ist Buchung, Summenauflösung Kreditkarte) anhand Daten von Zahlungsverkehrsprovider
• bei EfA-Roll-Out muss diese Aufgaben nicht unbedingt eine ePayBL übernehmen. Es gibt deutschlandweit noch andere Bezahlplattformen, die ähnlich funktionieren

ZVP (Zahlungsverkehrsprovider)

• Abwicklung der Zahlung mit dem Nutzer, d.h. ZVP bietet eine Oberfläche zur Erfassung der Zahlungsdaten, zieht die Gelder ein und schüttet es auf das von der Verwaltungseinheit hinterlegte Konto aus
• Rückmeldung des Zahlungsstatus an die ePayBL
• Übermittlung der Daten zur Erzeugung der camt.054 (Summenauflösung Kreditkarte) an die ePayBL
• Die Verwaltungseinheit benötigt zur Inanspruchnahme der Dienstleistung einen Vertrag mit dem ZVP

Standard ePayment-Use-Case

Der Standard ePayment-Use-Case basiert auf folgenden Grundsätzen

1. Das Kassenzeichen wird in der Bezahlplattform (ePayBL) generiert und nicht im PD Payment. Es werden keine Kassenzeichen/Kassenzeichenbestandteile vom Online Dienst übergeben.
2. Es wird Mandanten- und Bewirtschafterparametrisierung genutzt.
3. Die für die Verbuchung relevanten Parameter werden durch den Online Dienst an den PD Payment übergeben.

Dieser Leitfaden basiert auf der Annahme, dass dieser Standard ePayment-Use-Case umgesetzt wird. Gleichzeitig ist durch den Standard ePayment-Use-Case sichergestellt, dass die aktuellen Standard Anforderungen hinsichtlich Payment abgedeckt sind.

Ablaufdiagramme

Ablauf Pre-Payment

Pre-Payment ist in der Regel der Standardprozess. Zum dem Zeitpunkt, wo der Online Dienst das Payment aufruft, steht der zu zahlende Betrag fest und wird an den PD Payment übermittelt.

Ablauf Pre-Payment mit asycSucessUrl 

Pre-Payment mit asycSucessUrl ist eine Erweiterung des Pre-Payment, Durch die zusätzliche asycSucessUrl können Zahlungen ohne Nutzeranwesenheit (z.B. weil der Nutzer zu früh den Browser schließt) erkannt und an den Online Dienst gemeldert werden.

Ablauf Post-Payment

Der zweistufige Post-Payment Prozess ist dadurch gekennzeichnet, dass zum dem Zeitpunkt, wo der Online Dienst das Payment aufruft, der zu zahlende Betrag noch nicht fest steht. Der Betrag wird typischerweise durch/nach einer Sachbearbeitung im Fachverfahren ermittelt und von dort ans Payment kommuniziert. Vorteil vom Post-Payment Prozess (zwei- und einstufig) ist, dass Dokumente im ServiceConnector hinterlegt werden können und automatisch nach erfolgreicher Bezahlung dem Nutzer ins Postfach übermittelt werden.

Anbindung an dem Plattformdienst Payment

Allgemeine Voraussetzungen

.NET: Es wird Framework Version 2.3 benötigt (UI-Designer und ODControls.Core Version 2.3.77 oder höher). Bei Framework-Version kleiner 2.3 bitte Kontakt zur Beratung mit dem Produktmanagement Payment aufnehmen

AFM: Infrastruktur erfüllt die allgemeinen Voraussetzungen

Vorgehen

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

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

 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 Informationen zur Schnittstelle

Für parametrisiertes Payment nach dem Standard ePayment-Use-Case notwendige Werte

Pflichtfelder aus fachlicher Sicht:

Länderspezifische Pflichtfelder aus fachlicher Sicht:

Für die Referenz-Online-Dienste des Landes Schleswig-Holstein sind kostenstelle und hkrmantencode im Abschnitt additionalBookingData als Key-Value Paare zu übergeben.

"additionalBookingData": { 
    "kostenstelle": "4711.001",
    "hkrmandantencode": "08"
}

zudem empfohlen:

Parameter PD Payment REST API	Beschreibung	Name des Feldes in AFM	Name des Feldes in .NET
summary	Buchungstext der Payment Transaction (wird an HKR System/SAP/Kasse übergeben)
description	Beschreibung des Vorgangs zur Verwendung auf der Paypage (wird dem Nutzer angezeigt)

Nicht benötigte Parameter:

Parameter PD Payment REST API	Beschreibung	Name des Feldes in AFM	Name des Feldes in .NET
accountNo			AccountNo
sapNo	Die sapNo wird Bestandteil des Kassenzeichen, sofern das Kassenzeichen im PD Payment generiert wird		(nicht vorhanden)
suffix	Die sapNo wird Bestandteil des Kassenzeichen, sofern das Kassenzeichen im PD Payment generiert wird		Suffix
(nicht implementiert)			Kassenzeichen
(nicht implementiert)			Gemeindekennziffer

Parametrisierung 

anhand der Werte des Dataport Testaccounts. Mit Hilfe der Parametrisierung können, aus dem Online Dienst gesteuert, verschiedene Zahlungsmandanten und unterschiedliche Kontierungen angesprochen werden. So arbeiten Dienste, die in mehreren Kommunen genutzt werden oder EfA-Dienste

Mandantenummern und Bewirtschafternummer

Die Mandanten bekommen für den tatsächlichen Betrieb die jeweiligen Mandantenummern und Bewirtschafternummer der Behörden, Kreise & Kommunen. Zum allgemeinen Test haben wir folgenden Mandanten in Code-010, Code-002 und Stage Umgebung:

paymentIdentifier (Mandant) und Bewirtschafter sind case-sensitiv.

Kontierungsinformationen

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

(leer/null)

Testdaten für Kreditkarte, Giropay und Lastschrift im Testaccount

Am Mandanten haben wir unseren Dataport Girocheckout Testaccount hinterlegt, so dass auch Zahlungen simuliert werden können.

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. Es werden Zahlungen simuliert, d.h. es fließt kein echtes Geld. Bitte auf keinen Fall  echte Bank- oder Kreditkartendaten in Testumgebungen eingeben.

Kassenzeichen

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

Testmöglichkeiten in den Code-Umgebungen

allgemeine Testmöglichkeiten / allgemeine Dienst- und Zahlungsmandantenkonfiguration

In der Code-010 und Code-002 gibt es bei SH, ST, HH und GO allgemeine Testmöglichkeiten. 

Online Dienst

Bei .NET wird im Standard der consumer über Framework-Funktionalität auf den Short Name des Dienstes gesetzt. In diesem Fall bitte mit dem Produktmanagement Payment Kontakt aufnehmen zwecks Einrichtung des konkreten Dienstes anhand des Short Name.

verknüpfte Zahlungsmandanten

Die XBezahldienste Schnittstelle ist Mindestanforderung für alle EfA Dienst und perspektivisch Standard für alle Dienste. Die native ePayBL Schnittstelle ist eine proprietäre Schnittstelle, die bei Bestandsdienst im Einsatz ist. Funktional sollte es keine Unterschiede geben. Im Zweifelsfall ist für Neuentwicklungen die XBezahldienste Schnittstelle zu wählen.

individueller Konfigurationen von Diensten und Zahlungsmandanten

InCode-010 und Code-002 werden normalerweise keine individuellen Dienste eingerichtet. Ebenso keine Zahlungsmandanten von Kommunen oder Behörden.

Testmöglichkeiten & Einrichtung des Online Dienstes in Stage

allgemeine Testmöglichkeiten / allgemeine Dienst- und Zahlungsmandantenkonfiguration

In der Stage Umgebung gibt es bei SH, ST, HH und GO ebenso allgemeine Testmöglichkeiten.

Online Dienst

verknüpfte Zahlungsmandanten

Die XBezahldienste Schnittstelle ist Mindestanforderung für alle EfA Dienst und perspektivisch Standard für alle Dienste. Die native ePayBL Schnittstelle ist eine proprietäre Schnittstelle, die bei Bestandsdienst im Einsatz ist. Funktional sollte es keine Unterschiede geben. Im Zweifelsfall ist für Neuentwicklungen die XBezahldienste Schnittstelle zu wählen.

individueller Konfigurationen von Diensten und Zahlungsmandanten

In Stage besteht zudem der Anspruch jeden Dienst individuell und möglichst produktionsnah einzurichten. Für die Freischaltung und Konfiguration eures Online Dienstes meldet euch bitte bei unserem Funktionspostfach "Dataport ePayment".

Im ersten Schritt wird für den Online Dienst immer die beiden o.g. 

Die Einrichtung von einem PD Payment Zahlungsmandanten (und ggf. einem ePayBL-Mandanten und -Bewirtschafter) für eine Kommune/Behörde erfolgt durch die jeweilige nutzende Verwaltungseinheit über das OSI Service Desk: ePayment - OSI Service Desk

Trusted Sytems für den Testdienst in Code-002, Code-010 und Stage

TrustedSystem

Trusted System Identifier und Trusted System Key werden zur Authentifizierung des Online Dienstes im PD Payment benötigt. I.d.R werden die Werte bei .NET im Octopus hinterlegt und zur Build-Zeit angezogen/eingebunden

Trusted System Identifier

urn:dataport:osi:dptestdienst:{umgebung}:{osi-mandant}

umgebung (mögliche werte)

• code010
• code002
• stage

osi-mandant (mögliche Werte)

• sh
• st
• hh
• go

Am Beispiel Code-002 + SH:

urn:dataport:osi:dptestdienst:code002:sh

Trusted System Key

• code010, alle OSI-Mandanten=3CD97D5D06FC42F89808B11DAEE709D5
• code002, alle OSI-Mandanten=A495BB7E8FA34B1DAF832ED1C2A455FB
• stage, alle OSI-Mandanten=0359830080C84646B5A8966711CF0D45

Sicherheitshinweis

Produktive TrustestSystemKey dürfen niemals unverschlüsselt gespeichert oder übertragen werden!

Einrichtung des Online Dienstes in Prod

Die Freigabe zur Einrichtung von einem PD Payment Zahlungsmandanten (und ggf. einem ePayBL-Mandanten und -Bewirtschafter) erfolgt durch die nutzende Verwaltungseinheit über das Ticket im OSI Service Desk.

Die Einrichtung von einem PD Payment Online Dienst erfolgt - nach erfolgreichem Stage-Test - beim Payment-Team über das FuPo "Dataport ePayment". 

Die Konfigurationen in Prod und Stage sind stets synchron zu halten.

typische Fragen und Fehlermeldungen

"additionalBookingData": 
{ 
   "kostenstelle": "4711.001",    
   "hkrmandantencode": "08" 
}

Backlog

Themen, die noch näher beschrieben werden müssen

• Besonderheiten EfA Rollout
• Umgang mit den Status (success, error, cancel)

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 "Dataport ePayment".