Berlin.de-Payment. Anbindung eines Fachverfahrens an das Berlin.de-Payment

Transkript

1 Berlin.de-Payment Anbindung eines Fachverfahrens an das Berlin.de-Payment Autor: Steffen Schüssler Datum: Version: BerlinOnline Stadtportal GmbH & Co. KG Karl-Liebknecht-Str Berlin

2 Inhaltsverzeichnis 1.Technische Vorbedingungen Abfrage der Berlin.de-Payment-Schnittstelle Allgemein...4 a)allgemeine Parameter (immer mit zuschicken)...4 b)antworten GetBasketId PayInit PayConfirm PayComplete Benachrichtigung / Bestätigung an den Shop GetStatus Anhang Formatbeschreibung der Parameter Ergebnismeldungen / Antworten...11 Änderungshistorie: 2013/06/ (StS): neuer API-Call GetStatus(), Antwort von PayInit präzisiert 2012/01/ (StS): Klarstellung des Workflow 2010/05/ (StS): neue Version unterstützt "trans_prefix" Parameter (2 Zeichen), dadurch Verkürzung des Grund-Prefix auf zwei Zeichen. 2010/04/ (StS): Transaktions-Id Anfangskürzel auf 3 Zeichen erweitert (ges. 13 Zeichen); anzusprechender Payment-Server soll sein 2010/02/ (StS): Umstellung intern auf Java-Connector 2009/10/ (StS): Rückgabe-Werte verbessert für externe REST-API-Frameworks; 2009/09/ (StS) Erweiterung der PayInit Methode um zusätzliche Parameter; 2009/08/ (StS): Dokumentation angepasst auf die programmierte Test-Umgebung, derzeit nur implementiert: REST-API; 2008/09/ (StS): Spezifikation der Basisparameter Begriffe (Übersetzung von Berlin.de-Vokabular in Landes-Verwaltungsbegriffe): Shop == Dienstleistung Basket-Id == Transaktions-Id Begriffe (Übersetzung von Berlin.de-Vokabular in EU-DLR-Begriffe): Shop = DLR-Anwendung Behörde = Träger Merchant kann pro Behörde oder auch pro Standort separat sein. Trans_prefix = Zusatzparameter in der Kreuztabelle von Standort<->Dienstleistung

3 1. Technische Vorbedingungen Technische Beschreibung der Punkte 2) und 7) aus dem allgemeinen Workflow. Beim Berlin.DE-Payment wird für jeden SHOP hinterlegt: http-authentifizierung interne auth-authentifizierung interne Shop-Daten für Zahlungsabwicklung und Reporting (Festlegung der erlaubten Zahlungsarten usw.) OK-Url : welche URL vom Shop soll aufgerufen werden, um dem Shop das OK einer Zahlung mitzuteilen (kann auch pro request übermittelt werden). FAIL-Url: welche URL vom Shop soll aufgerufen werden, um dem Shop einen Fehler mitzuteilen (kann auch pro request übermittelt werden). BACK-Url: welche URL vom Shop soll aufgerufen werden, um den Shop einen User-Abbruch mitzuteilen (kann auch pro request übermittelt werden).

4 2. Abfrage der Berlin.de-Payment-Schnittstelle 2.1. Allgemein Die in der folgenden Tabellen aufgeführten Parameter werden über den Browser des Kunden durch ein Redirect an den Berlin.DE-Payment-Server übermittelt. Der Shop reagiert also auf eine Aktion des Browsers mit einer Antwort, die den Kunden auf den Berlin.DE-Payment-Server weiterleitet. Dies kann durch einen HTTP-Redirect-Header, eine HTML-Seite mit einem entsprechenden Meta-Tag oder per Javascript-Formular erfolgen. Für alle Aufrufe wird empfohlen POST zu benutzen, um Caching einzuschränken, alte Bookmarks zu verhindern, und um nicht an der üblichen 1024 Zeichen GET-Url Grenze zu scheitern (Rückruf-Urls und Warenkorb-Beschreibungen können ziemlich lang werden). Aufgerufen werden die Funktionen einzeln, gesichert durch eine SSL-Verbindung, gesichert durch die http-authentifizierung und zusätzlich durch die auth-authentifizierung in den Parametern. Die Anmeldedaten (http und auth) werden separat pro Shop vergeben. Allgemein hat der Aufruf einer Funktion folgendes Aussehen (Bsp. für Version v1.3.x) a) Allgemeine Parameter (immer mit zuschicken) auth_id AN-10 an49kz12n dem Shop fest zugeordnete ID zur Authentifizierung auth_pw ANS-10 Krepel/12%3 Kennwort b) Antworten Eine erfolgreiche Antwort besteht aus: OK Weiterer_Text_oder_URL Beispiel: OK FS Eine Fehler-Antwort hat die Form: ERROR NNN: ErrorText NNN ist ein dreistelliger Code. ErrorText ist standardisiert, kann sich in Zukunft aber ändern. Beispiel: ERROR 223: missing or wrong validation date Generell, können ab Zeile zwei zusätzliche Informationen beschreibender Natur mitgeliefert werden, die aber für eine Auswertung der Nachricht nicht erforderlich sind. Achtung: bei OK Parametern bitte nicht ein eventuell vorhandenes Zeilenende-Zeichen weiterverarbeiten.

5 2.2. GetBasketId Erster Schritt generiert eine gültige Warenkorb-ID im Backend. Neben den obligatorischen "auth_id" und "auth_pw" optionaler Parameter "trans_prefix". trans_prefix A-2 GA (optional) 2-stelliger Prefix, der mit zur Bildung der Warenkorb-ID benutzt wird Rückgabe: OK id=warenkorbid Die Warenkorb-ID hat den Aufbau: - 2 Zeichen Kürzel für den Merchant (hinterlegte Kontoverbindung) - 2 Zeichen Trans-Prefix (soweit vorhanden) - die restlichen Zeichen (gesamt 13 Zeichen) werden mit einer Zufallszahl aus Ziffern aufgefüllt PayInit Übergabe aller gewünschten Parameter des Warenkorbs. basketid AN-13 ZZZ stellige Warenkorb-ID, aus dem Schritt GetBasketId amount N[.]N ganzzahlige Zahl-Beträge, oder mit genau 2 Nachkommastellen, die mit nur genau einem Punkt getrennt sind. Keine Tausenderzeichen, oder Kommas erlaubt. Maximalbetrag pro Shop einstellbar. currency AN-3 EUR Pflichtfeld: Währung, derzeit nur EUR möglich (ISO 4217) description ANL-120 (*) Plakette B-FS1234 weitere Plaketten fuer B-FS2345, B-FS3456, usw. Beschreibender Text des Warenkorbs. Die erste Zeile wird an einigen Stellen hervorgehoben dargestellt und sollte auch auf dem Kontoauszug sofort zu erkennen geben, wofür Geld abgezogen wurde. Umlaute und Sonderzeichen Sind als html-entities zu schicken, um unabhängig vom Zeichensatz zu sein. (*) kunde ANL-120 Hannelore Muster Name des Kunden für einen evtl. notwendigen Compliance-Check (je

6 nach Shop-Einstellung Pflichtfeld) paymethod A[,] Kreditkarte,Lastschrift (optional) Zulässige Zahlungsarten, komma-getrennt, derzeit verfügbar: Kreditkarte, Lastschrift, Giropay und Vorkasse; Wenn Vorkasse gewählt ist, wird keine andere Zahlungsart gleichzeitig erlaubt. Es wird generell empfohlen, die Entscheidung bereits im Vorfeld abzufragen, damit der Nutzer im Zahlungsfenster möglichst kurz verweilt ohne lästige Zusatz-Fragen. langid AN-2 en Sprache des angezeigten Backends voreinstellen, derzeit unterstützt (de,en,fr,it,...) andere nachfragen oder ausprobieren. (default: de) successlink URI? php?orderid=1234 faillink URI? php?orderid=1234 backlink URI? php?orderid=1234 Rück-Link der im Erfolgsfall ausgeführt werden soll. Es können bereits eigene Query-Parameter dranhängen; es werden bei der Rückgabe weitere Parameter angehangen, die dann ausgewertet werden sollten. optional! er nimmt ansonsten den successlink, Aufruf im Falle eines Backend-System-Fehlers. Rückg abe erfolgt mit zusätzlichem Parameter status=fail optional! er nimmt ansonsten den successlink Abbruch durch den User. Rückgabe erfolgt mit zusätzlichem Parameter status=back customerid AN-32 CUST Optional bestimmte API-Calls können in der Zukunft anstatt auf die Warenkrob-ID (basketid) auch auf die Customer-Id reagieren. Rückgabe: OK payurl=url_zur_zahlungsseite (*) (description) Der Wertebereich für die Ausgabe auf dem Kontoauszug entspricht den im Datenträgeraustausch-Format (DTAUS-Format) festgelegten Zeichen: Buchstaben (mit den Umlauten Ä, Ö, Ü, ä, ö, ü sowie ß), Ziffern, Leerzeichen, ".", ",", "&", "-", "+", "*", "%", "/", "$".

7 Zwischenschritt Die PayInit-URL müssen Sie Ihrem Nutzer an dieser Stelle auf einer Webseite oder in einer präsentieren (nur 1 Tag gültig), damit dieser nun mittels dieser URL durch den eigentlichen Bezahl-Vorgang surfen kann. Wenn der Nutzer mit der Bezahlung fertig ist (oder abbricht) kommt er zuerst beim BDE-Payment-Backend vorbei, von wo er nun seinerseits an die von Ihnen zur Verfügung gestellten URLs weitergeleitet wird. Im OK-Fall Aufruf der SUCCESSLINK Url, im Fehlerfall Aufruf des FAILLINK und bei einem Abbruch Aufruf des BACKLINK. Alle weiteren Schritte passieren nun wieder hinten herum zwischen Ihrem Server und dem BDE-Payment-Backend PayConfirm Nach dem User im Zahlfenster alles erfolgreich absolviert hat, wird erst jetzt die Zahlungantwort überprüft, die über den Nutzer-Browser zum Shop zurückgekommen ist. Die Zahlung ist nur vorbereitet, aber noch nicht ausgeführt (außer im Fall Giropay, da dort ja des Nutzers Hausbank involviert ist. PayConfirm und PayComplete müssen trotzdem aufgerufen werden, um auch die interne Abrechnung korrekt zu gewährleisten.) Die hier erforderlichen Parameter sind mittels der OK-URL übermittelt worden (DATA und SIGNATURE), die nun ohne Nutzereinwirkung direkt mit dem Berlin.de-Payment-Server überprüft werden können (um Manipulationen zu verhindern). Ihre OK-URL darf selber bereits GET Parameter enthalten (zu beachten gesamt-url-länge). Beispiel: %3D102%252C104%252C352%252C680%26ACCOUNTID %3D %26CURRENCY%3DEUR%26DESCRIP TION%3DTEST-Buchung%26ORDERID%3DTS %26BACKLINK%3Dhttp%253A %252F%252Fsecure.berlin.de%252Fpayment%252Ftest%252Fv11%252Fretsf_back.php %26FAILLIN K%3Dhttp%253A%252F%252Fsecure.berlin.de%252Fpayment%252Ftest %252Fv11%252Fretsf_fail.php%26SUCCESSLINK%3Dhttp%253A%252F%252Fsecure.berlin.de %252Fpayment %252Ftest%252Fv11%252Fretsf_success.php%26DELIVERY%3Dno%26AMOUNT %3D1312&signature=d6e8fd9b036bf745ca3f8d14ad51664c ihrparameter kann zum Beispiel benutzt werden, um selber die basketid durchzuschleifen. basketid AN-13 ZZZ stellige Warenkorb-ID, aus dem Schritt GetBasketId data ANS-680 siehe oben Zahlungsdaten die vom Berlin.de-Backend Server benutzt werden. signature ANS-128 siehe oben Checksumme Antwort (Bsp): OK id=jk jliosiijwijiw &token=(none)

8 2.5. PayComplete Mittels der ID aus PayConfirm, wird nun die Zahlung abgeschlossen (processed). basketid AN-13 ZZZ stellige Warenkorb-ID, aus dem Schritt GetBasketId id ANS-64 JK JLIOSIIJW IJIW ID der vorbereiteten Zahlung token ANS-64 (none) security-token, wird derzeit noch nicht benutzt, sollte aber bereits so mit übermittelt werden, wie es vom PayConfirm-Aufruf zurückkommt. Rückgabe von PayComplete: OK Meldung_falls_notwendig (Meldung kann ignoriert werden OK ist OK) Antwort (Bsp.): OK status=ok 2.6. Benachrichtigung / Bestätigung an den Shop Hinweis Wenn Sie die SSL-verschlüsselte Übertragung der Shopbenachrichtigung wünschen, benötigen Sie ein SSL-Zertifikat, das von einer anerkannten Zertifizierungsstelle auf den Server ausgestellt wurde, den Sie im URL für die Shopbenachrichtigung angeben. Selbst generierte Zertifikate werden nicht akzeptiert. Sie erhalten in diesem Fall keine Shopbenachrichtigung. Sie erhalten ebenfalls keine Shopbenachrichtigung, wenn der Servername im URL für die Shopbenachrichtigung nicht mit dem Server übereinstimmt, für den das Zertifikat ausgestellt wurde. Das gilt z.b. auch, wenn Sie im URL für die Shopbenachrichtigung die IP-Adresse statt des Servernamens angeben. Nach Abwicklung der Zahlung wird der Shop über das Ergebnis informiert. Dazu wird die vom Shopbetreiber eingestellte URL für die Shopbenachrichtigung aufgerufen und die in der folgenden Tabelle enthaltenen Parameter übertragen. Die Benachrichtigung des Shops erfolgt auch bei Auftreten eines Fehlers, Timeouts oder nach Abbruch der Zahlung durch den Kunden. Wichtig Wenn Ihre Shopbenachrichtigung SSL-verschlüsselt übertragen wird, testen Sie bitte nach einem Wechsel des SSL-Zertifikats, ob die Benachrichtigung nach wie vor funktioniert. An die im SUCCESSLINK hinterlegte Adresse werden nach dem Bezahlen durch den Nutzer folgende Daten übermittelt. Alle Felder sind dabei prinzipiell optional und sind auch nicht bei jeder Art der Bezahlung verfügbar.

9 id AN-80 Transaktionskennung beim nachgelagerten Zahlungsdienstleister ip IP ' IP-Adresse des Bezahlers ipcountry A-2 DE 2-stellige Landeskennung, bei unbekannt "XX" amount N.N bezahlter Betrag currency AN-3 EUR Währung siehe oben providername ANL-32 Visa Test Card Name des Verarbeiters (Kreditkartengesellschaft etc.) basketid AN-13 ZZZ die ursprünglich vom Shop übermittelte Transaktions-ID eci N = SSL-Transaktion (keine Haftungsumkehr) 1 = 3-D Secure-Transaktion, voll authentifiziert (Haftungsumkehr) 2 = 3-D Secure-Transaktion, nicht authentifiziert (Haftungsumkehr) cccountry A-2 XX 2-stellige Landeskennung der benutzten Karte, bei unbekannt "XX" status A SUCCESS Status im OK-Fall "SUCCESS"

10 2.7. GetStatus Mittels der Warenkorb-Id kann jederzeit der aktuelle Status erfragt werden. Er stellt sich so dar wie man es auch im Administrationsinterface (separat anfragen) sieht. basketid AN-13 ZZZ stellige Warenkorb-ID, aus dem Schritt GetBasketId Rückgabe ist der aktuelle Status der Transaktion. Rückgabewerte für das Feld Status können sein: OK PENDING FAIL Antwort Abfrage war korekt und Status ist OK: OK status=ok auch mögliche korrekte Antworten: OK status=pending OK status=fail in nachfolgenden Zeilen können evtl zusätzliche Informationen stehen, die allerdings nicht für die maschinelle Auswertung gedacht sind. Im Fehlerfall (Abfrage irgendwie inkorrekt), wird die übliche Fehlermeldung ausgegeben, mit dem entsprechenden Fehlercode (Bsp.): ERROR 123 Fehlermeldung

11 3. Anhang 3.1. Formatbeschreibung der Parameter In der folgenden Tabelle sind alle Zeichen aufgeführt und erklärt, die das Format eines Parameters definieren. Zeichen A N S L Xn X-n FIX Bedeutung Buchstaben Ziffern Sonderzeichen Leerzeichen genau n Zeichen maximal n Zeichen feste Zeichenkette [] Eine Anzahl erlaubter Zeichen wird zwischen eckigen Klammern aufgelistet. (*) Beispiele N5 ANS-10 Ziffer mit genau 5 Zeichen Zeichenkette mit bis zu 10 Zeichen. Diese Zeichenkette kann Buchstaben, Ziffern und Sonderzeichen enthalten, aber keine Leerzeichen AN[_]-10 Zeichenkette mit bis zu 10 Zeichen. Diese Zeichenkette kann Buchstaben, Ziffern und das Zeichen '_' enthalten, aber keine Leerzeichen URI URI? Gültige URL nach dem Muster Gültige URL mit erlaubtem Query-String nach dem Muster * Ist auch die eckige Klammer erlaubt, wird diese doppelt aufgeführt z.b. [[] Ergebnismeldungen / Antworten API Error-Codes siehe API_Errorcodes.pdf