BillSAFE Payment Layer Integration Guide letzte Aktualisierung: 10.06.2013
Inhaltsverzeichnis 1 Vorwort...2 1.1 Inhalt...2 1.2 Zielgruppe...2 1.3 Voraussetzungen...2 1.4 Feedback...2 1.5 Versionshistorie...3 2 Einbindung des Payment Layers...4 2.1 Zahlart Kauf auf Rechnung mit BillSAFE einfügen...4 2.2 JavaScript einbinden...4 2.3 Client-Objekt des Payment Layers erzeugen...4 2.4 Token erzeugen...6 2.5 Payment Layer schließen...7 BillSAFE Payment Layer Integration Guide 1
1 Vorwort 1.1 Inhalt In diesem Dokument erfahren Sie, wie sich Ihre bestehende BillSAFE Integration um den Payment Layer erweitern lässt. Bei der Standard-Integration wird der Käufer während des Checkout-Prozesses vorübergehend auf das Payment Gateway von BillSAFE umgeleitet. In Abgrenzung dazu ermöglicht der Payment Layer, dass der Käufer den Shop nicht verlassen muss. Stattdessen öffnet sich der Payment Layer über dem Shop. 1.2 Zielgruppe Dieses Dokument richtet sich an Web-Entwickler mit Kenntnissen in HTML und JavaScript. 1.3 Voraussetzungen Die Integration des Payment Layers setzt eine vorhandene BillSAFE-Integration (Payment Gateway) in Ihrem Onlineshop voraus. Sie haben die BillSAFE API erfolgreich angebunden. Sie benötigen Zugriff auf den Quelltext der Shop-Software. 1.4 Feedback Haben Sie Anregungen, wie wir diese Anleitung noch verbessern können? Bitte senden Sie uns Ihr Feedback an documentationfeedback@billsafe.de BillSAFE Payment Layer Integration Guide 2
1.5 Versionshistorie Datum Anmerkung 2011-08-16 Erste Beta-Veröffentlichung 2012-09-03 Änderung der Einstellungen für die client.js BillSAFE Payment Layer Integration Guide 3
2 Einbindung des Payment Layers Diese Dokumentation setzt voraus, dass es in Ihrem Shop eine HTML-Seite gibt, auf welcher der Käufer eine Zahlart auswählen kann (Zahlartenauswahlseite). Die Auswahl einer Zahlart erfolgt entweder innerhalb eines HTML-Formulars (Formular-Variante) oder mittels HTML-Link (Link-Variante). 2.1 Zahlart Kauf auf Rechnung mit BillSAFE einfügen Ergänzen Sie Ihre Zahlartenauswahlseite um die Zahlart Kauf auf Rechnung mit BillSAFE. Formular-Variante <form method= post action= http://www.shop.de/checkout.php id= paymentform > <input type= radio name= paymentmethod value= invoice />BillSAFE Kauf auf Rechnung <input type= radio name= paymentmethod value= installment />BillSAFE Ratenkauf <input type= radio name= paymentmethod value= vorkasse /> Vorkasse <input type= submit name= continue value= weiter /> </form> Link-Variante <a href= http://www.shop.de/checkout.php id= invoicelink >BillSAFE - Kauf auf Rechnung</a> <a href= http://www.shop.de/checkout.php id= installmentlink >BillSAFE - Ratenkauf</a> <a href= http://www.shop.de/checkout.php id= prepaymentlink >Vorkasse</a> 2.2 JavaScript einbinden Binden Sie das von BillSAFE bereitgestellte JavaScript in Ihre Zahlartenauswahlseite ein. <script type="text/javascript" src="https://content.billsafe.de/lpg/js/client.js"> 2.3 Client-Objekt des Payment Layers erzeugen Erstellen Sie mit JavaScript ein Client-Objekt des Payment Layers. Formular-Variante Der Konstruktor des Client-Objekts erwartet ein Array, das folgende Elemente enthält: form conditions sandbox Eine Referenz auf das HTML-Formular, in dem die Zahlart eingefügt wurde. Ein Array mit Bedingungen (i.d.r. nur eine), die bei Auswahl der Zahlart BillSAFE erfüllt sein müssen. Jede Bedingung wird durch ein Objekt mit den Attributen element und value spezifiziert. In dem unten stehenden Beispiel wird durch die Bedingung festgelegt, dass die Zahlart BillSAFE ausgewählt wurde, wenn das HTML-Element paymentmethod den Wert billsafe enthält. Mit Einführung des Ratenkauf-Produktes kann entweder wie bisher ein eindimensionales Array oder neuerdings ein zweidimensionales Array definiert werden. Ein weiteres Beispiel veranschaulicht diese neue Variante. Ein Boolean-Wert, der angibt, ob die Transaktion im Sandbox (TRUE) oder BillSAFE Payment Layer Integration Guide 4
im Live-Betrieb (FALSE) ausgeführt werden soll. Beispiel für die bisherige Struktur var formelement = document.getelementbyid('paymentform'); var lpg = new BillSAFE.LPG.client({ form: formelement, conditions: [{element: 'paymentmethod', value: 'invoice'}], sandbox: true }); Beispiel für die neue Struktur var formelement = document.getelementbyid('paymentform'); var lpg = new BillSAFE.LPG.client({ form: formelement, conditions: { invoice: [{element: 'paymentmethod', value: 'invoice'}], installment: [{element: 'paymentmethod', value: 'installment'}] }, sandbox: true }); Link-Variante Der Konstruktor des Client-Objekts erwartet ein Array, das folgende Elemente enthält: link sandbox Eine Referenz auf den HTML-Link, über den die Zahlart BillSAFE ausgewählt werden kann. Mit Einführung des Ratenkauf-Produktes kann auch ein Array definiert werden. Ein weiteres Beispiel veranschaulicht diese neue Variante. Ein Boolean-Wert, der angibt, ob die Transaktion im Sandbox (TRUE) oder im Live-Betrieb (FALSE) ausgeführt werden soll. Beispiel für die bisherige Struktur var lpg = new BillSAFE.LPG.client({ link: document.getelementbyid('invoicelink'), sandbox: true }); BillSAFE Payment Layer Integration Guide 5
Beispiel für die neue Struktur var lpg = new BillSAFE.LPG.client({ link: { invoice: document.getelementbyid('invoicelink'), installment: document.getelementbyid('installmentlink'), }, sandbox: true }); 2.4 Token erzeugen Hat der Käufer die Zahlart BillSAFE ausgewählt, wird der Payment Layer angezeigt. Das ursprüngliche Formular- bzw. Link-Ziel (hier: http://shop.de/checkout.php) wird in einen Iframe umgeleitet, der dynamisch durch den JavaScript Client erzeugt wurde. Auf dieser Ziel-Seite muss nun unter Verwendung der BillSAFE API-Funktion prepareorder ein Token erzeugt und wie folgt ausgegeben werden: <html> <div id= BillSAFE_Token >4e032aadd18564e032aacd1c47</div>... </html> Der JavaScript-Client übergibt den GET-Parameter layeredpaymentgateway mit dem Wert 1 an die Ziel-Seite. Anhand dieses Parameters können Sie somit erkennen, ob der Payment Layer genutzt wird. Fehlt der Parameter, ist der Payment Layer nicht aktiv (z.b. bei deaktiviertem JavaScript) und Sie müssen den Käufer auf das Payment Gateway umleiten. Folgendes PHP-Skript demonstriert den Umgang mit ein- bzw. ausgeschaltetem JavaScript: <?php //$token wurde zuvor über die API-Funktion prepareorder bezogen (hier nicht dargestellt) if (!empty($_get['layeredpaymentgateway'])) { //Payment Layer wird verwendet! JavaScript ist aktiv! echo '<html><div id="billsafe_token">'. $token. '</div></html>'; exit; } else { //JavaScript ist NICHT aktiv! //Umleitung auf Fullsize Payment Gateway (Sandbox): header('location: https://sandbox-payment.billsafe.de/v200?token='. $token); exit; } //Im Produktiv-Betrieb stattdessen Umleitung auf Fullsize Payment Gateway (Live): //header('location: https://payment.billsafe.de/v200?token='. $token); //exit; BillSAFE Payment Layer Integration Guide 6
2.5 Payment Layer schließen Der Käufer schließt den Kauf innerhalb des Payment Layers ab und wird daraufhin auf die URL umgeleitet, die Sie mit der API-Funktion prepareorder im Parameter url_return übergeben haben. Fügen Sie auf dieser Seite folgendes JavaScript ein, um den Payment Layer wieder zu schließen und den Käufer auf eine andere Seite des Shops umzuleiten. if (top.lpg) { top.lpg.close('http://www.shop.de/checkbillsaferesult.php'); } Auf dieser Seite (hier: http://www.shop.de/checkbillsaferesult.php) sollten Sie mit der API- Funktion gettransactionresult abfragen, ob der Kauf erfolgreich abgeschlossen werden konnte. Sofern BillSAFE die Transaktion angenommen hat, bestätigen Sie Ihrem Kunden den erfolgreichen Abschluss der Bestellung. Andernfalls bieten Sie ihm alternative Zahlarten an. Falls der Käufer den Kauf-Prozess im Payment Layer abbricht, wird er auf die URL umgeleitet, die Sie mit der API-Funktion prepareorder im Parameter url_cancel übergeben haben. Fügen Sie auf dieser Seite folgendes JavaScript ein, um den Payment Layer wieder zu schließen. if (top.lpg) { top.lpg.close(); } BillSAFE Payment Layer Integration Guide 7