Anbindung externer Web-Verfahren an ePayBL

Anbindung externer Web-Verfahren
an ePayBL
Version 1.02
Stand: März 2015
©opyright
Diese Unterlage der Anstalt für Kommunale Datenverarbeitung in Bayern ist urheberrechtlich geschützt. Nachdruck bzw.
Vervielfältigung, auch in Auszügen, sind nur mit schriftlicher Einwilligung bzw. im Rahmen der Verträge mit der AKDB gestattet.
Die AKDB haftet nicht für irrtümliche Angaben oder Druckfehler. Änderungen bleiben vorbehalten.
Änderungsprotokoll
Datum
Version
Änderungsgrund
Autor
21.07.2014
11.02.2015
1.00
1.01
Stolz
12.03.2015
1.02
Ersterstellung
Überarbeitung in folgenden Kapiteln:
4, 4.1, 5.1, 5.2, 6
Korrekturen in folgenden Kapiteln:
4.2, 5, 5.1, 5.1.2, 5.1.3,
Brandt/Stolz
Brandt/Stolz
Inhaltsverzeichnis:
1
Einleitung
3
2
Prinzipieller Ablauf
3
3
Schematische Darstellung des Ablaufs
4
4
Der Ablauf aus Sicht des Bürgers
5
4.1
4.2
4.3
4.4
4.5
4.6
5
6
7
8
8
9
5
6
Fachlicher Dienst
Einleitung des Bezahlvorganges
ePayBL-PayPage
Bezahlvorgang über den Payment-Provider
Papage: Bestätigung des Zahlvorganges
Rückkehr zum Fachdienst
Die Schnittstellen zwischen Fachdienst und ePayB
10
5.1
Webservice-Schnittstelle
10
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
Verfügbarkeit prüfen – isAlive
Temporären Kunden anlegen – anlegenKunde
Kassenzeichen anlegen - anlegenKassenzeichen
Temporären Kunden löschen
Bezahlergebnis verifizieren - lesenKassenzeichenInfo
10
11
13
15
15
5.2
HTTPS-Redirect zur PayPage
16
Referenzen
18
©opyright
Diese Unterlage der Anstalt für Kommunale Datenverarbeitung in Bayern ist urheberrechtlich geschützt. Nachdruck bzw.
Vervielfältigung, auch in Auszügen, sind nur mit schriftlicher Einwilligung bzw. im Rahmen der Verträge mit der AKDB gestattet.
Die AKDB haftet nicht für irrtümliche Angaben oder Druckfehler. Änderungen bleiben vorbehalten.
Projekt Testumgebung Bayernportal
1
eGov
Einleitung
Das vorliegende Dokument gibt einen Überblick über den prinzipiellen Ablauf und über die
Konventionen bei der Anbindung eines externen Web-Dienstes an das epayment-System
ePayBL der AKDB.
Die notwendigen Schnittstellen dazu werden informativ erläutert; die exakten Details sind
den jeweiligen ePayBL-Dokumentationen zu entnehmen. (siehe Abschnitt 6, Referenzen)
2
Prinzipieller Ablauf
Der Ablauf eines Bezahlvorgangs über ePayBL besteht aus einer Sequenz von WebService-aufrufen und http-Redirects zwischen Bürger, Fachdienst, ePayBL-PayPage und
Payment-Provider.
Der Bezahlvorgang setzt sich aus folgenden funktionalen Blöcken zusammen:

Einleitung Bezahlvorgang
Der Fachdienst teilt ePayBL mit, dass ein Zahlungsvorgang veranlasst werden soll.
ePayBL legt dafür ein sog. Kassenzeichen an und teilt dies dem Fachdienst mit.
Das Kassenzeichen ist im ePayBL der Schlüssel für einen Bezahlvorgang.

PayPage: Auswahl der Zahlungsart
Der Fachdienst gibt die Kontrolle an ePayBL ab. ePayBL präsentiert dem Bürger eine
Seite (die sog. PayPage), auf der dieser die gewünschte Zahlungsart auswählt und
die wichtigsten Daten des Bezahlvorganges bestätigt.
.
Bezahlvorgang über den Payment-Provider
Im Fall einer Zahlung per Kreditkarte, Giropay oder PayPal leitet ePayBL den Bürger
auf die Web-Seite des jeweiligen Payment-Providers weiter. Über diese Seiten wird
der Zahlungsvorgang je nach Zahlungsart abgewickelt.
Im Fall einer Bezahlung per Lastschrift oder Rechnung entfällt dieser Schritt.


PayPage: Bestätigung des Zahlvorganges
Nach der erfolgreichen Durchführung des eigentlichen Zahlungsvorgangs gelangt der
Bürger zurück zur PayPage des ePayBL, wobei nun der Zahlungsvorgang mit den
zugehörigen Daten bestätigt wird.

Abschluss/Verifikation
ePayBL gibt die Kontrolle an das Fachverfahren zurück.
Bevor dem Bürger die kostenpflichtige Dienstleistung gewährt wird, muss das
Fachverfahren bei ePayBL anhand des Kassenzeichens verifizieren lassen, dass der
Bezahlvorgang wirklich korrekt abgewickelt worden ist.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 3 von 18
Projekt Testumgebung Bayernportal
3
eGov
Schematische Darstellung des Ablaufs
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 4 von 18
Projekt Testumgebung Bayernportal
4
eGov
Der Ablauf aus Sicht des Bürgers
Im Folgenden werden die einzelnen Schritte einer Bezahlung aus der Sicht der Bürgers
dargestellt.
Als Beispiel wird hierbei der Bürgerservice-Portal-Dienst „Anforderung einer
Meldebestätigung“
(https://www.egovkommune.de/akdb/egovkommune/bsp_ewo_meldebestaetigung)
herangezogen:
Hinweis:
Die URLs in den nachfolgenden Beispielen wurden im Kontext des AKDB-DemoBürgerserviceportals mit der fiktiven Gemeinde egovstadt erstellt. Im Zusammenhang mit
anderen Portalen (z.B. Bayernportal) kommen selbstverständlich andere URLs für Portal und
Payment-Server zum Einsatz. (z.B. https://infra-pre.buergerserviceportal.de/paypage anstelle
von https://epay-demo.akdb.de/paypage)
4.1
Fachlicher Dienst
Der fachliche Dienst „Meldebestätigung“ erfragt vom Bürger in mehreren Schritten alle
notwendigen persönlichen Daten für die Anforderung einer Meldebestätigung:
Wenn dem Fachdienst alle erforderlichen Informationen für den Vorgang zur Verfügung
stehen, werden sie dem Bürger nochmals auf einer zusammenfassenden Seite präsentiert.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 5 von 18
Projekt Testumgebung Bayernportal
4.2
eGov
Einleitung des Bezahlvorganges
Bis zu diesem Zeitpunkt hat noch keinerlei Aktivität im Zusammenspiel mit ePayBL
stattgefunden. Erst wenn der Bürger den Button „Kostenpflichtige Anforderung“ betätigt, wird
der Bezahlvorgang bei ePayBL eingeleitet.
Zwischen Fachdienst und ePayBL werden div. vorbereitende Soap-Aufrufe ausgeführt;
anschließend erfolgt ein HTTPS-Redirect auf die PayPage von ePayBL.
Im Kontext dieses Redirect werden u.a. zwei Rückkehr-URLs als HTTP-codierter Parameter
mitgeliefert. Über diese beiden URLs erfolgt die Rückkehr von ePayBL zum Fachdienst, je
nachdem ob der Bezahlvorgang erfolgreich war oder abgebrochen wurde.
(siehe dazu Abschnitt 5.2, HTTPS-Redirect zur PayPage)
(
https://infra-pre.buergerserviceportal.de/paypage/login.do
?backlinkSuccess=https%3A%2F%2Fwww.egovkommune.de....usw.
?backlinkAbort=https%3A%2F%2Fwww.egovkommune.de....usw.
&kassenzeichen=9990000000000000000000620 …usw )
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 6 von 18
Projekt Testumgebung Bayernportal
4.3
eGov
ePayBL-PayPage
Die PayPage des ePayBL erfragt vom Bürger die gewünschte Zahlungsart.
Die PayPage bestätigt nochmal die Zahlungsdaten:
Durch Betätigen des „Weiter“-Buttons wird der Bürger zu den Webseiten des PaymentProviders weitergeleitet.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 7 von 18
Projekt Testumgebung Bayernportal
4.4
eGov
Bezahlvorgang über den Payment-Provider
Bezahlseite der Testseite des Kreditkarten-Payment-Providers (www.saferpay.com)
Der Bürger gibt seine Kreditkarten-Daten bzw. seine Kontodaten (Giropay) ein.
Er wird von den Seiten des Payment-Providers durch den Bezahlvorgang geleitet.
4.5
Papage: Bestätigung des Zahlvorganges
Nach erfolgreicher Abwicklung der Bezahlung gelangt der Bürger wieder zurück zur ePayBLPayPage. Sie zeigt jetzt eine Zusammenfassung des Bezahlvorganges und erlaubt einen
Ausdruck dieser Daten.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 8 von 18
Projekt Testumgebung Bayernportal
4.6
eGov
Rückkehr zum Fachdienst
Über die bei der Einleitung des Bezahlvorganges (Abschnitt 4.2) mitgelieferte
backlinkSuccess-URL
(https://www.egovkommune.de/akdb/egovkommune/bsp_ewo_meldebestaetigun
g?kassenzeichen=9990000000000000000000620&bezahlt=true)
leitet ePayBL schließlich wieder zum Fachdienst zurück.
Da diese URL über den Browser auch direkt und manuell eingegeben werden könnte, ohne
den Bezahlvorgang selbst wirklich abgewickelt zu haben, ist es unerlässlich dass der
Fachdienst an dieser Stelle nochmal per Soap-Aufruf von ePayBL bestätigen lässt, dass für
dieses Kassenzeichen die Bezahlung wirklich stattgefunden hat.
Anschließend erscheint eine Abschlussseite und der Antrag auf die Meldebestätigung kann
bearbeitet werden.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 9 von 18
Projekt Testumgebung Bayernportal
5
eGov
Die Schnittstellen zwischen Fachdienst und ePayB
Die Mandanten am ePayment werden für den jeweiligen Drittanbieter auf Anforderung
konfiguriert.
Dabei werden die aktuellen Einträge für MandantNr, Bewirtschafternummer, Haushaltsstelle,
Objektnummer und KennzeichenMahnverfahren dem Drittanbieter mitgeteilt.
5.1
Webservice-Schnittstelle
Aus der umfangreichen Liste der Aufrufe der ePayBL-SOAP-Schnittstelle
(https://epay-demo.akdb.de/soap/servlet/rpcrouter?wsdl)
werden für die Abwicklung des Zahlungsvorganges genau fünf Methoden benötigt:
Vor der Bezahlung:




isAlive – Verfügbarkeit prüfen
anlegenKunde – Temporären Kunden anlegen
anlegenKassenzeichen – Kassenzeichen und Bezahlvorgang an ePayBL anlegen
loeschenKunde – Temporären Kunden löschen
Nach der Bezahlung

lesenKassenzeichenInfo – Bezahlvorgang verifizieren
Anmerkung:
Die in den folgenden Java-Code-Beispielen verwendeten Java-Klassen
(z.B. de.bund.bff.www.ePament.Ergebnis) entsprechen den Schema-Typen der
ePayBL-SOAP-WSDL und können z.B. mit Java-JAXB aus dem Schema generiert werden.
5.1.1
Verfügbarkeit prüfen – isAlive
Prüft, ob das ePayBL –System erreichbar ist und ob der angegebene Mandant gültig ist.
public de.bund.bff.www.ePayment.Ergebnis isAlive
(java.lang.String mandantNr) throws java.rmi.RemoteException;
Dieser Aufruf sollte vor jedem Bezahlvorgang stattfinden, um die Verfügbarkeit des ePayBLService zu garantieren.
Der Mandant mit der zugehörigen Mandantennummer muss am ePayBL angelegt und
bekannt sein.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 10 von 18
Projekt Testumgebung Bayernportal
eGov
Resultierende Soap-Nachricht (Beispiel):
5.1.2
Temporären Kunden anlegen – anlegenKunde
Legt einen Kunden im ePayBL an. Der nachfolgende Bezahlvorgang wird dann diesem
Kunden zugeordnet; alle Bezahlvorgänge sind an einen Kunden gekoppelt.
public de.bund.bff.www.ePayment.KundenErgebnis anlegenKunde
(java.lang.String mandantNr,
java.lang.String bewirtschafterNr,
de.bund.bff.www.ePayment.Kunde kunde)
throws java.rmi.RemoteException;
Für jeden Bezahlvorgang sollte ein eigener, neuer Kunde am ePayBL angelegt werden.
Mandant und Bewirtschafter müssen am ePayBL administriert sein.
Im Parameter kunde müssen die beiden Felder EShopKundenNr und Sprache (= „de“)
gesetzt sein. Diese EShopKundenNr wird vom Fachverfahren vergeben und muss für jeden
Bezahlvorgang neu generiert werden.
Eine bereits existierende EShopKundenNr zu einem Mandanten kann nicht nochmal
angelegt werden.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 11 von 18
Projekt Testumgebung Bayernportal
eGov
Resultierende Soap-Nachricht (Beispiel):
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 12 von 18
Projekt Testumgebung Bayernportal
5.1.3
eGov
Kassenzeichen anlegen - anlegenKassenzeichen
Jeder Bezahlvorgang ist mit einem Kassenzeichen assoziiert. Das Kassenzeichen ist aus
ePayBL-Sicht gemeinsam mit der Mandantennummer der Schlüssel zu einer Buchung.
Beim Aufruf von anlegenKassenzeichen werden – bis auf die letztendlich vom Bürger
ausgewählte Zahlungsart – alle Daten für die Bezahlung bereitgestellt.
In einem Aufruf können mehrere Einzelposten zum Bezahlvorgang übergeben werden
(Buchungsliste).
Zu jedem Element der Buchungsliste sind neben dem Betrag eine Haushaltsstelle und eine
Objektnummer für die spätere Verbuchung des Postens abzugeben.
Die Parameter mandantNr, eShopKundenNr und buchungsListe sind Pflichtfelder.
public de.bund.bff.www.ePayment.BuchungsListeErgebnis anlegenKassenzeichen
(java.lang.String mandantNr, java.lang.String eShopKundenNr,
de.bund.bff.www.ePayment.BuchungsListe buchungsListe,
de.bund.bff.www.ePayment.LieferAdresse lieferAdresse,
java.lang.String buchungsText,
java.lang.String zahlverfahren)
throws java.rmi.RemoteException;
In der Buchungsliste müssen die Felder betrag, waehrungskennzeichen (=“EUR“),
faelligkeitsdatum, bewirtschafterNummer und kennzeichenMahnverfahren
(=“11“) gesetzt sein.
In der Buchungsliste können mehrere Einzelbuchungen zum Bezahlvorgang übergeben
werden .
Zu jedem Element der Buchungsliste sind neben dem Betrag eine Haushaltsstelle und eine
Objektnummer für die spätere Verbuchung des Postens abzugeben.
Der Gesamtbetrag der Buchungsliste muss der Summe der Einzelbuchungen entsprechen.
Der Aufruf liefert im Erfolgsfall ein Kassenzeichen zurück. Alle weiteren Aktivitäten des
Bezahlvorganges beziehen sich dann auf dieses Kassenzeichen.
Für Details siehe „Technische Schnittstellendokumentantion“, Abschnitt 14.5, 14.6 ff.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 13 von 18
Projekt Testumgebung Bayernportal
eGov
Soap-Nachricht zum Aufruf: (hier mit ein-elementiger Buchungsliste)
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 14 von 18
Projekt Testumgebung Bayernportal
5.1.4
eGov
Temporären Kunden löschen
public de.bund.bff.www.ePayment.KundenErgebnis loeschenKunde
(java.lang.String mandantNr,
java.lang.String bewirtschafterNr,
java.lang.String eShopKundenNr)
throws java.rmi.RemoteException;
Neben mandantNr und bewirtschafterNr ist auch die eindeutige eShopKundenNr
anzugeben.
Soap-Nachricht zum Aufruf:
5.1.5
Bezahlergebnis verifizieren - lesenKassenzeichenInfo
public de.bund.bff.www.ePayment.KassenzeichenInfoErgebnis lesenKassenzeichenInfo
(java.lang.String mandantNr,
java.lang.String kassenzeichen)
throws java.rmi.RemoteException;
Für den Aufruf sind mandantNr und kassenzeichen anzugeben.
Aus dem gelieferten KassenzeichenInfoErgebnis sind Kassenzeichen und Betrag zu
validieren. Außerdem muss geprüft werden, dass die Komponente paypageStatus den
Wert „INAKTIV“ besitzt. Nur dann ist der Bezahlvorgang wirklich positiv abgeschlossen
worden.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 15 von 18
Projekt Testumgebung Bayernportal
eGov
Soap-Nachricht zum Aufruf:
5.2
HTTPS-Redirect zur PayPage
Nach dem Aufruf der Soap-Methoden isAlive, anlegenKunde,
anlegenKassenzeichen, loeschenKunde muss der Fachdienst per HTTPS-Redirect zu
PayPage wechseln.
Der Fachdienst muss dabei die PayPage-URL des zuständigen ePayBL-Systems aufrufen.
In die URL müssen fünf URL-Parameter integriert werden:





RückkehrURL im Erfolgsfall
RückkehrURL bei Abbruch/Fehler
Mandantennummer
Kassenzeichen
eShopKundennummer
Beispiel für eine Redirect-URL (informativ)
https://epay-demo.akdb.de/paypage
?backlinkSuccess=<URL im Fachverfahren>
&backlinkAbort=<URL im Fachverfahren>
&mandant=B888888
&kassenzeichen9990000000000000000000620
&EShopKundenNr=1954958305
Alle Parameter - insbesondere die beiden Rückkehr-Links - müssen HTTP-Codiert sein, d.h.
alle „/“-, „?“- „&“-Zeichen etc. müssen jeweils durch die entsprechenden http-Codierungen
(%2F, %3F, %26) ersetzt werden.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 16 von 18
Projekt Testumgebung Bayernportal
eGov
Beispiel für eine fertige Redirect-URL (real)
https://epay-demo.akdb.de/paypage?backlinkSuccess=https%3A%2
F%2Fwww.egovkommune.de%2Fakdb%2Fegovkommune%2Fbsp_ewo_meldebestaetig
ung%3Fkassenzeichen%3D9990000000000000000000620%26bezahlt%3Dtrue&bac
klinkAbort=https%3A%2F%2Fwww.egovkommune.de%2Fakdb%2Fegovkommune%2Fb
sp_ewo_meldebestaetigung%3Fkassenzeichen%3D9990000000000000000000620
%26bezahlt%3Dfalse&mandant=B888888&kassenzeichen=9990000000000000000
000620&EShopKundenNr=1954958305
Der Aufbau der beiden URLs backlinkSuccess und backlinkFail bleibt ganz allein
dem Fachverfahren überlassen. Es kann auch für beide Fälle dieselbe URL verwendet
werden.
Wichtig: Der <host>-Teil (im Beispiel epay-demo.akdb.de) muss identisch mit dem <host>Teil der URL des Fachverfahren sein, damit die Session des Bürgers wieder gefunden wird.
Ein Wechsel z.B. zwischen host-name und IP-Adresse hat zur Folge, dass der Fachdienst
nach der Rückkehr vom der PayPage nicht wie erwartet weiterarbeitet.
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 17 von 18
Projekt Testumgebung Bayernportal
6
eGov
Referenzen
Eine umfassende Beschreibung des Ablaufs und der Schnittstellen findet sich in den
folgenden Dokumenten welche über http://basisdienste.buergerserviceportal.de erreichbar
sind.
[1] ePayBL Integrationshandbuch
eGovernment, Sachsen interaktiv, vom 8.6.2010
http://basisdienste.buergerserviceportal.de
[2] Handbuch zur Paypage der ePayBL,
www.DReseach.de, Klaus Peters, 17. 02.2012
http://basisdienste.buergerserviceportal.de
[3] Zahlverkehrsplattform Epayment, Technische Schnittstellendokumentation,
DResearch, 21.05.2013
http://basisdienste.buergerserviceportal.de
[4] WSDL zur ePayBL- SOAP-Schnittstelle
https://epay-demo.akdb.de/soap/servlet/rpcrouter?wsdl bzw.
https://infra-pre.buergerserviceportal.de/soap/servlet/rpcrouter?wsdl
Anbindung externer Web-Verfahren an ePayBL
V 1.01
Seite 18 von 18