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 1.00 Ersterstellung Stolz 11.02.2015 1.01 Überarbeitung in folgenden Kapiteln: 4, 4.1, 5.1, 5.2, 6 Brandt/Stolz 12.03.2015 1.02 Korrekturen in folgenden Kapiteln: 4.2, 5, 5.1, 5.1.2, 5.1.3, 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 Fachlicher Dienst 5 4.2 Einleitung des Bezahlvorganges 6 4.3 epaybl-paypage 7 4.4 Bezahlvorgang über den Payment-Provider 8 4.5 Papage: Bestätigung des Zahlvorganges 8 4.6 Rückkehr zum Fachdienst 9 5 Die Schnittstellen zwischen Fachdienst und epayb 10 5.1 Webservice-Schnittstelle 10 5.1.1 Verfügbarkeit prüfen isalive 10 5.1.2 Temporären Kunden anlegen anlegenkunde 11 5.1.3 Kassenzeichen anlegen - anlegenkassenzeichen 13 5.1.4 Temporären Kunden löschen 15 5.1.5 Bezahlergebnis verifizieren - lesenkassenzeicheninfo 15 5.2 HTTPS-Redirect zur PayPage 16 6 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.
1 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 Web- Service-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
3 Schematische Darstellung des Ablaufs Anbindung externer Web-Verfahren an epaybl V 1.01 Seite 4 von 18
4 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-Demo- Bü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
4.2 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
4.3 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 Payment- Providers weitergeleitet. Anbindung externer Web-Verfahren an epaybl V 1.01 Seite 7 von 18
4.4 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 epaybl- PayPage. 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
4.6 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
5 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 epaybl- Service 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
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
Resultierende Soap-Nachricht (Beispiel): Anbindung externer Web-Verfahren an epaybl V 1.01 Seite 12 von 18
5.1.3 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
Soap-Nachricht zum Aufruf: (hier mit ein-elementiger Buchungsliste) Anbindung externer Web-Verfahren an epaybl V 1.01 Seite 14 von 18
5.1.4 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
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
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
6 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 ernment, 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