Dokumentation der Billpay XML-API (Technische Dokumentation) (Version 2.0) 1
Inhaltsverzeichnis Änderungshistorie... 3 Was ist Billpay?... 5 1 Zielgruppe... 5 2 Wichtiger Hinweis... 5 3 Downloads... 6 4 In welchen Ländern ist Billpay verfügbar... 6 5 Anzeigen der Datenschutzbestimmungen von Billpay... 6 6 Prozessdiagramm...10 7 XML-Schnittstelle...11 7.1 Webservice-URL...12 7.2 Das Billpay-Backoffice...12 7.3 Übersicht über die XML-Service-Requests...13 7.4 Generelle Parameter für jeden XML-Service-Request...15 7.5 Generelle Parameter für jede XML-Service-Response...15 7.6 Frontend Requests...15 7.6.1 Modul Konfiguration (moduleconfig)...15 7.6.2 Vorautorisierung (preauthorize)...17 7.6.3 Finalisierung der Bestellung (capture)...25 7.7 Backend Requests...26 7.7.1 Aktivierung (invoicecreated)...26 7.7.2 Abrufen der Kontodaten (getbillpaybankdata)...29 7.7.3 Vollstornierung (cancel)...30 7.7.4 Änderung des Warenkorbinhalts (editcartcontent)...30 7.7.5 DEPRECATED - Teilstornierung/Teilretour (partialcancel)...33 7.7.6 Geldeingang vom Kunden (reportcustomerpayment)...34 8 Clientseitige API...36 9 XML-Beispiele...37 10 Kontakt für Rückfragen...43 11 Anhang...45 11.1 Erlaubte Werte für das Feld salutation der Vorauthorisierungsanfrage...45 11.2 Erlaubte Werte für das Feld legalform der Vorauthorisierungsanfrage...46 11.3 Wann sind die Felder registernumber und holdername Pflichtfelder?...47 11.4 Mögliche Werte für das Feld error_field der Vorauthorisierungsantwort...48 2
Änderungshistorie Version Datum Bemerkungen 1.8.6 13.Mai 2011 - Einige Beschreibungen konkretisiert - Unterteilung der Requests in Frontend und Backend - Falsche Beschreibung für Feld rebate in der Vorauth. Korrigiert - Anforderungen an die Endkunden-Rechnung konkretisiert 1.9.0 31.Mai 2011 - Erforderliche Parameter für Internationalisierung eingefügt: moduleconfig und partialcancel Requests erweitert 1.9.1 27.Juni 2011 - Erlaubte Werte für das Feld saluation für Internationalisierung angepaßt - Internationalisierte Vorlage für die Zahlungsinformationen eingefügt - Einbindung AGB und Datenschutz für Schweiz erweitert - Falsche Beschreibung für den Parameter carttotalgross im preauthorize-request korrigiert 1.9.2 18.Juli 2011 - Neuen Text und neue Grafik für die Bestätigung der Datenschutzbestimmungen im Checkout eingefügt 1.9.3 15.August 2011 1.9.4 21.September 2011 1.9.6 27.Januar 2012 1.9.7 12.April 2012 - Tabelle mit Verfügbarkeit von Billpay für einzelne Länder eingefügt - Parameter für die neue Version des B2B-Rechnungskaufs eingefügt - XML-Beispiel für B2B-Vorauthorisierung angepasst - Werte für das Feld legalform für B2B-Schweiz hinzugefügt - Verfügbarkeit des B2B-Rechnungskauf für die Schweiz markiert - Neuen (optionalen) Request reportcustomerpayment beschrieben - Rechnungskauf-B2C für Österreich verfügbar - Formatspezifikation und XML-Beispiel für den neuen API-Call editcartcontent für das nachträgliche Ändern des Warenkorbs eingefügt. API-Call partialcancel als DEPRECATED markiert. - Formatspezifikation für die Liste mit Validierungsfehlern in der Antwort des API-Calls preauthorize eingefügt. XML-Beispiel 9 entsprechend angepasst. 1.9.8 16. März 2013 - Dokumentation von neuem getbillpaybankdata Request. - Tabelle mit angebotenen Zahlarten erweitert 1.9.9 12.Sept. 2013 - Entfernen von Ratenkaufparametern aus Preauthorization Paragraph 3
2.0.0 12. Nov. 2013 - Rechnungskauf NL - SEPA Änderungen - UpdateOrder Request 4
Was ist Billpay? Mit Billpay können Online-Händler ihren Kunden die Zahlungsart Kauf auf Rechnung mit einem Zahlungsziel von 20 bzw. 30 Tagen (je nach Wunsch des Händlers) sowie die Zahlungsart Kauf per Lastschrift und auch den Ratenkauf (siehe Zusatzdokumentation für die Integration des Billpay- Ratenkauf (deutsch) für eine detailierte Beschreibung der Integration des Ratenkauf) anbieten. Die Zahlart Kauf auf Rechnung kann dabei sowohl für Privatkunden (B2C) als auch für Geschäftskunden (B2B) angeboten werden. Laut der E-Commerce-Studie 2008 von ibi Research ist der Rechnungskauf die beliebteste Bezahlart im deutschsprachigen Wirtschaftsraum. 65% der Konsumenten würden gern per Rechnung zahlen. Ohne die Eingabe von sensiblen Konto- oder Kreditkartendaten können Kunden die Ware erst zu Hause prüfen, bevor sie zahlen. Lastschrift ist die drittbeliebteste Bezahlart. Kunden kennen und schätzen die Zahlung per Lastschrift aus dem stationären Handel. Durch das Angebot von zwei der drei beliebtesten Bezahlarten sinkt die Kaufabbruchquote, die Warenkorbgröße steigt und Umsätze und Gewinne wachsen maßgeblich. Ergänzt durch die immer populärer werdende Zahlungsart Ratenkauf, können Online-Händler Ihren Kunden mit Billpay eine unvergleichbare Bandbreite an Zahlungsmöglichkeiten anbieten. Billpay übernimmt für den Online-Händler das gesamte Risiko- und Forderungsmanagement; der Händler hat mehr Zeit für sein Kerngeschäft. Der Online-Händler erhält sein Geld auch dann, wenn der Kunde die Rechnung nicht zahlt bzw. wenn die Lastschrift platzt dank Billpays Zahlungsgarantie. Billpay bietet den Online-Händlern eine schnelle und einfache Integration aller drei Zahlungsarten in ihr Online-Shop-System. Neben einer Vielzahl einsatzbereiter Plugins für die gängigen Shopsysteme 1 stellt Billpay eine clientseitige API bereit, die die Integration in Ihren Shop für den Fall vereinfacht, dass Sie ein selbst entwickeltes Shopsystem verwenden oder Billpay für Ihr Shopsystem keine Pluginlösung anbietet. 1 Zielgruppe Diese technische Dokumentation richtet sich an Softwareentwickler und -architekten, die eine Anbindung an die XML-Zahlungsschnittstelle von Billpay realisieren wollen. Für das Verständnis aller technischen Details ist eine fundierte Kenntnis von XML und vom HTTP-Protokoll erforderlich. 2 Wichtiger Hinweis Bitte beachten Sie, dass die Implementierung der Erweiterungen entsprechend des Dokuments Zusatzdokumentation für die Einbindung der Billpay-Betrugsprävention verpflichtend ist. Dieses Dokument steht aus sicherheitstechnischen Gründen nicht zum Download auf der Webseite von Billpay bereit. Stattdessen haben Sie dieses Dokument als Anhang der Email mit den Zugangsdaten zum Testsystem erhalten. Auf Anfrage senden wir Ihnen dieses Dokument gern erneut zu. 1 Bitte beachten Sie bei der Installation die technische Dokumentation für das jeweilige Plugin 5
3 Downloads Die aktuellste Version dieser technischen Dokumentation und den für die Integration benötigte Quellcode finden Sie unter der URL http://www.billpay.de/haendler/downloads. Bitte überprüfen Sie bevor Sie mit der Integration beginnen, ob Ihnen die aktuellste Version dieses Dokuments vorliegt. 4 In welchen Ländern ist Billpay verfügbar Maßgeblich für die Verfügbarkeit der Billpay-Zahlarten ist das Land, in dem die Rechnungsadresse des Endkunden liegt. Die folgende Tabelle gibt eine Übersicht, für die Endkunden aus welchen Ländern welche der Billpay-Zahlarten angeboten werden können. Rechnung B2C Rechnung B2B Lastschrift Ratenkauf Deutschland Ja Ja Ja Ja Schweiz Ja Ja Nein Ja Österreich Ja In Kürze In Kürze Ja Niederlande Ja Nein Nein Nein 5 Anzeigen der Datenschutzbestimmungen von Billpay Bevor eine Billpay-Zahlart im Bestellprozess des Shops durch den Kunden genutzt werden darf, muss der Kunde die Datenschutzbestimmungen von Billpay bestätigen. Dies geschieht in der Regel direkt nach Auswahl der Zahlart und vor Bestätigung durch Drücken eines Weiter -Buttons. Hierfür muss dem Kunden für den Rechnungskauf das folgende HTML-Fragment angezeigt werden: Mit der Übermittlung der für die Abwicklung des Rechnungskaufs und einer Identitäts und Bonitätsprüfung erforderlichen Daten an die <a href='https://billpay.de/endkunden' target='blank'> Billpay GmbH</a> bin ich einverstanden. Es gelten die <a href="[link auf Datenschutzbestimmungen]"> Datenschutzbestimmungen</a> von Billpay. 6
Für die Lastschrift Deutschland muss das folgende HTML-Fragment angezeigt werden: Mit der Übermittlung der für die Abwicklung der Zahlung und einer Identitäts- und Bonitätsprüfung erforderlichen Daten an die Billpay GmbH (LINK: https://www.billpay.de/endkunden/) bin ich einverstanden. Es gelten die Datenschutzbestimmungen (LINK: https://www.billpay.de/datenschutz-de/) von Billpay. Ich erteile Billpay ein SEPA-Lastschriftmandat (Einzelheiten) zur Einziehung fälliger Zahlungen und weise mein Geldinstitut an, die Lastschriften einzulösen. Einzelheiten: Die Gläubiger-Identifikationsnummer von Billpay ist DE19ZZZ00000237180. Die Mandatsreferenznummer wird mir zu einem späteren Zeitpunkt per Email zusammen mit einer Vorlage für ein schriftliches Mandat mitgeteilt. Ich werde zusätzlich dieses schriftliche Mandat unterschreiben und an Billpay senden. Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem Geldinstitut vereinbarten Bedingungen. Bitte beachten Sie, dass die fällige Forderung auch bei einer Rücklastschrift bestehen bleibt. Weitere Informationen finden Sie auf https://www.billpay.de/sepa. Für den Ratenkauf Deutschland muss das folgende HTML-Fragment angezeigt werden: Mit der Übermittlung der für die Abwicklung der Zahlung und einer Identitäts- und Bonitätsprüfung erforderlichen Daten an die Billpay GmbH (LINK: https://www.billpay.de/endkunden/) bin ich einverstanden. Es gelten die AGB (LINK: Generische AGB des jeweiligen Shops), Zahlungsbedingungen (LINK: https://www.billpay.de/api/ratenkauf/zahlungsbedingungen/) und Datenschutzbestimmungen (LINK: https://www.billpay.de/api/ratenkauf/datenschutz/) von Billpay. Ich erteile Billpay und der net-m privatbank 1891 AG (LINK: https://www.privatbank1891.com/) ein SEPA-Lastschriftmandat (Einzelheiten) zur Einziehung fälliger Zahlungen und weise mein Geldinstitut an, die Lastschriften einzulösen. Einzelheiten: Die Gläubiger-Identifikationsnummer von Billpay ist DE19ZZZ00000237180, die Gläubiger-Identifikationsnummer der net-m privatbank AG ist DE62ZZZ00000009232. Die Mandatsreferenznummer wird mir zu einem späteren Zeitpunkt per Email zusammen mit einer Vorlage für ein schriftliches Mandat mitgeteilt. Ich werde zusätzlich dieses schriftliche Mandat unterschreiben und an Billpay senden. 7
Für die Lastschrift Österreich muss das folgende HTML-Fragment angezeigt werden: Mit der Übermittlung der für die Abwicklung der Zahlung und einer Identitäts- und Bonitätsprüfung erforderlichen Daten an die Billpay GmbH (LINK: https://www.billpay.de/endkunden/) bin ich einverstanden. Es gelten die Datenschutzbestimmungen (LINK: https://www.billpay.de/at/datenschutz-at/) von Billpay. Ich erteile Billpay und der net-m privatbank 1891 AG (LINK: https://www.privatbank1891.com/) ein SEPA-Lastschriftmandat (Einzelheiten) zur Einziehung fälliger Zahlungen und weise mein Geldinstitut an, die Lastschriften einzulösen. Einzelheiten: Die Gläubiger-Identifikationsnummer von Billpay ist DE19ZZZ00000237180, die Gläubiger-Identifikationsnummer der net-m privatbank AG ist DE62ZZZ00000009232. Die Mandatsreferenznummer wird mir zu einem späteren Zeitpunkt per Email zusammen mit einer Vorlage für ein schriftliches Mandat mitgeteilt. Ich werde zusätzlich dieses schriftliche Mandat unterschreiben und an Billpay senden. Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem Geldinstitut vereinbarten Bedingungen. Bitte beachten Sie, dass die fällige Forderung auch bei einer Rücklastschrift bestehen bleibt. Weitere Informationen finden Sie auf https://www.billpay.de/sepa. Für den Ratenkauf Österreich muss das folgende HTML-Fragment angezeigt werden: Mit der Übermittlung der für die Abwicklung der Zahlung und einer Identitäts- und Bonitätsprüfung erforderlichen Daten an die Billpay GmbH (LINK: https://www.billpay.de/endkunden/) bin ich einverstanden. Es gelten die AGB (LINK: Generische AGB des jeweiligen Shops), Zahlungsbedingungen (LINK: https://www.billpay.de/api/ratenkauf/zahlungsbedingungen/) und Datenschutzbestimmungen (LINK: https://www.billpay.de/at/apiat/ratenkauf-at/datenschutz/) von Billpay. Ich erteile Billpay und der net-m privatbank 1891 AG (LINK: https://www.privatbank1891.com/) ein SEPA-Lastschriftmandat (Einzelheiten) zur Einziehung fälliger Zahlungen und weise mein Geldinstitut an, die Lastschriften einzulösen. Einzelheiten: Die Gläubiger-Identifikationsnummer von Billpay ist DE19ZZZ00000237180, die Gläubiger-Identifikationsnummer der net-m privatbank AG ist DE62ZZZ00000009232. Die Mandatsreferenznummer wird mir zu einem späteren Zeitpunkt per Email zusammen mit einer Vorlage für ein schriftliches Mandat mitgeteilt. Ich werde zusätzlich dieses schriftliche Mandat unterschreiben und an Billpay senden. Hinweis: Ich kann innerhalb von acht Wochen, beginnend mit dem Belastungsdatum, die Erstattung des belasteten Betrages verlangen. Es gelten dabei die mit meinem Geldinstitut vereinbarten Bedingungen. Bitte beachten Sie, dass die fällige Forderung auch bei einer Rücklastschrift bestehen bleibt. Weitere Informationen finden Sie auf https://www.billpay.de/sepa. 8
Der Platzhalter für den Verweis auf die Datenschutzbestimmungen von Billpay muss durch den entsprechenden Wert aus der folgenden Tabelle ersetzt werden (maßgeblich für die Auswahl des Verweises ist das Land, in dem die Rechnungsadresse des Kunden liegt): Dokument Webseite Popup Datenschutz (Deutschland) Datenschutz (Schweiz) Datenschutz (Österreich) https://www.billpay.de/kunden/agb# datenschutz https://www.billpay.de/kunden/agb-ch# datenschutz https://www.billpay.de/kunden/agb-at# datenschutz https://www.billpay.de/api/agb# datenschutz https://www.billpay.de/api/agb-ch# datenschutz https://www.billpay.de/api/agb-at# datenschutz Die Datenschutzbestimmungen sind in verschiedenen Sprachen abrufbar. Wenn Sie das Schweizer Dokument bspw. in französischer Sprache anzeigen wollen, nutzen Sie dafür den folgenden Link: Datenschutz (Webseite): https://www.billpay.de/kunden/agb-ch?lang=fr/#datenschutz Falls die Datenschutzbestimmungen nicht bestätigt worden sind (z.b. durch Aktivierung einer Checkbox), muss ein entsprechender Hinweis angezeigt und der Bestellvorgang darf nicht fortgesetzt werden. 9
6 Prozessdiagramm Technischer Ablauf eines Einkaufs über Billpay. Online-Händler Billpay Auswahl der Zahlart Kunde wählt Billpay-Zahlart Vorauthorisierungsanfrage (preauthorize) - Authentifizierungsparameter des Händlers - Rechnungs-/Lieferadresse - Warenkorb - Historische Bestelldaten bei Bestandskunden - Bankeinzugsdaten (nur für Lastschrift) Überprüfung der Anfrage Bezahlung über Billpay nicht möglich. Auswahl alternativer Zahlart. - sdf Fehler/Bestellung abgelehnt - Fehlercode - Fehlermeldung für Händler - Fehlermeldung für Kunden Ergebnis der Anfrage Fortsetzung des Bestel lprozesses Bestellung akzeptiert Erfassungsanfrage Abschließende Übersicht über die Bestellung (capture) - Transaktionsnummer - Warenkorbwert (Prüfsumme) Überprüfung der Anfrage Bezahlung über Billpay nicht möglich. Auswahl alternativer Zahlart. Fehler - Fehlercode - Fehlermeldung für Händler - Fehlermeldung für Kunden Ergebnis der Anfrage Erfolgreicher Abschluß der Bestellung Erfassung bestätigt Zahlungsdetails (für Rechnung) 10
Ein Großteil der gängigen Shopsysteme realisiert einen Bestellprozess, der die beiden folgenden Aktionen in chronologischer Reihenfolge beinhaltet: 1) Auswahl der Zahlart mit anschließender Bestätigung der Zahlart 2) Abschließende Übersicht der Bestellung mit Bestätigung und anschließendem Anlegen der Bestellung im Shop In der Regel sollte in Verbindung mit jeder dieser beiden Aktionen eine Anfrage an die Billpay- Schnittstelle gesendet werden (die Vorauthorisierungsanfrage für 1) und die Erfassungsanfrage für 2)). Erst mit dem erfolgreichen Absetzen der Erfassungsanfrage wird die Bestellung bei Billpay finalisiert. Das Senden der Vorauthorisierungsanfrage zu einem frühstmöglichen Zeitpunkt ermöglicht eine Minimierung der Kaufabbruchquote. Sollte Ihr Shopsystem einen einstufigen Bestellabschluss realisieren, kann die Vorauthorisierungsanfrage auch im so genannten Auto-Capture -Modus ausgeführt. In diesem Fall wird die Bestellung bereits mit erfolgreicher Vorauthorisierung bei Billpay finalisiert. Die Erfassungsanfrage darf dann nicht mehr gesendet werden. Es muss jedoch beachtet werden, dass das erfolgreiche Absetzen der Vorauthorisierungsanfrage im Auto-Capture Modus auch unmittelbar zum Anlegen der vollständigen Bestellung im Shop führt. Eine Bestellung, die erfolgreich bei Billpay finalisiert wurde, muss unmittelbar vor der Auslieferung aus dem Backend heraus aktiviert werden. Die Aktivierung einer Bestellung wird mithilfe des invoicecreated requests ausgeführt. Das automatische Aktivieren mit Finalisierung der Bestellung ist nicht zulässig. Bestellungen, die nicht ordnungsgemäß aktiviert wurden, werden von Billpay nicht erstattet! Darüber hinaus muss jede Bestellung, die nicht aktiviert wurde, bei Billpay storniert werden. 7 XML-Schnittstelle Die Kommunikation zwischen Shop und der Billpay-Zahlungsschnittstelle basiert auf einem leichtgewichtigen XML-Protokoll. Der serverseitige Endpunkt der XML-Schnittstelle besteht aus einer Reihe verschiedener XML-Services, die jeweils über einen XML-Service-Request angesprochen werden. Jeder XML-Service-Request besteht aus einem XML-Dokument, welches mittels HTTP POST- Request an eine für den jeweiligen Request eindeutige Service-URL gesendet werden muss. Als Antwort auf einen XML-Service-Request liefert die XML-Schnittstelle eine XML-Service-Response. Jede XML-Service-Response besteht wiederum aus einem XML-Dokument, welches immer mindestens einen Fehlercode und Fehlermeldungen für Händler und Kunden beinhaltet. Nur wenn eine XML-Service-Response mit dem Fehlercode 0 vorliegt, kann die Aktion als gültig betrachtet werden. Andernfalls liefert die XML-Schnittstelle detaillierte Fehlermeldungen zurück. Die übergebenen XML-Daten an die XML-Schnittstelle müssen als UTF-8 codiert sein. Ebenso werden die XML-Antworten als UTF-8 codiert zurückgegeben. 11
Das Schema der XML-Service-Requests beruht auf der extensiven Nutzung von XML-Attributen. Bitte vergewissern Sie sich, dass reservierte Zeichen in den Attributewerten entsprechend des XML- Standards durch ihre Escape-Sequenzen wie folgt ersetzt werden: Reserviertes Escape- Zeichen Sequenz & & " " ' ' < < > > 7.1 Webservice-URL Jede URL für einen der XML-Services wird durch eine Basis-URL gefolgt von einem Bezeichner für den jeweligen Service gebildet. Basis-URLs o Livesystem: o Testsystem: https://api.billpay.de/xml https://test-api.billpay.de/xml/offline Achtung: Die XML-Schnittstelle funktioniert nur über HTTPS und nicht über HTTP! 7.2 Das Billpay-Backoffice Das Billpay-Backoffice ist ein Webinterface, mit dessen Hilfe einige der XML-Service-Requests durch manuelle Aktionen ersetzt werden können. So wird es durch das Billpay-Backoffice beispielsweise ermöglicht, dass für Bestellungen Teilstornierungen durchgeführt werden können, auch wenn das verwendete Shopsystem des Händlers die Funktionalität zur Integration des entsprechenden XML- Service-Requests nicht anbietet oder gar die Teilstornierung nicht unterstützt. Das Backoffice-Testsystem wird Sie darüber hinaus während des Integrationsprozesses unterstützen, in dem Sie hier bei der Billpay-Schnittstelle eingegangene Bestellungen auf Richtigkeit überprüfen, aktivieren und (teil-)stornieren können. Die Zugangsdaten für das Backoffice-Testsystem erhalten Sie auf Anfrage bei Billpay (Kontaktdetails siehe Seite 43). 12
7.3 Übersicht über die XML-Service-Requests XML-Service Bedeutung Zeitpunkt des Aufrufs Service-URL Pflic ht Backoffice Rückgabe Modul Konfiguration Abholen wichtiger Systemparameter Zu Beginn des Bestellprozess [Basis-Url]/ moduleconfig Ja Nein Flag für jede ZA ob diese für für das aktuelle es aktuelles Portal Portal verfügbar ist. Oberes/unteres Limit pro ZA Vorautorisierung Prüfung des Kunden auf Identität bzw. Bestellprozess. Nach Auswahl der Zahlart [Basis-Url]/ preauthorize Ja Nein Status der Prüfung und ggf.korrigierte Bonität Adresse Erfassung Bestätigung, dass Bestellung Bestellprozess. Beim Anlegen [Basis-Url]/ capture Ja Nein Rechnung: Billpay- abgeschlossen wird der Bestellung im Shop Kontodaten für die Rechnung 2 Lastschrift: - Aktualisierung Aktualisierung der Bestellprozess. [Basis-Url]/ Nein Nein - Bestell-ID. Falls Nach Anlegen updateorder Erfassung vor Anlegen der der Bestellung im Shop 3 Bestellung geschieht und die Bestell-ID zu diesem ZP noch nicht feststeht Aktivierung Rechnung: Starten des Bei Erstellung der Rechnung. [Basis-Url]/ invoicecreated Ja Ja Rechnung: Billpay- Zahlungsziels (20 Wird i.d.r. im Kontodaten und bzw. 30 Tage) Backend durch Zahlungsziel als Lastschrift: Initiierung des eine spezielle Aktion Zeitstempel Lastschrift: - Bankeinzugs ausgelöst 2 Achtung! Die mit der Antwort auf die Erfassungsanfrage zurückgegebenen Kontodaten ändern sich für jede Transaktion und dürfen somit nicht statisch im Shop hinterlegt werden! 3 Achtung! Zwischen der Erfassungsanfrage und der Aktualisierungsanfrage darf keine Nutzeraktion stattfinden! 13
Vollstornierung Stornierung der gesamten Bestellung Wird i.d.r. im Backend durch eine spezielle Aktion [Basis-Url]/ cancel Nein Ja - ausgelöst Warenkorb ändern Änderung des Warenkorbinhalts oder der Wird i.d.r. im Backend durch Gutschrift, [Basis-Url]/ editcartcontent Nein Nein - Liefergebühren bzw. Rabatte der Teilstornierun g oder Bestellung Änderung der Bestellung ausgelöst Teilstornierung DEPRECATED! Stornierung einzelner Posten der Bestellung/ Stornierung von Wird i.d.r. im Backend durch eine spezielle Aktion [Basis-Url]/ partialcancel Nein Ja - Teilbeträgen ausgelöst Geldeingang vom Kunden Nur Rechnungskauf: Händler meldet Billpay, dass Kunde auf Aus dem Backend, falls Kunde auf das Konto des Händlers [Basis-Url]/ reportcustomer Payment Nein Ja - Konto des Händlers überweist überwiesen hat Billpay Bankdaten Nur Rechnungskauf: Wird aus dem Backend [Basis-Url]/ getbillpaybankd Nein Nein Bankverbindung von Billpay und abholen Abholen der Bankverbindung von Billpay zur heraus gesendet, falls das Abgreifen ata Zahlungsziel für die Rechnung Anzeige auf der der Bankdaten Rechnunf von der capture- oder invoicecreated Response nicht möglich ist 14
7.4 Generelle Parameter für jeden XML-Service-Request Mit jedem XML-Service-Request müssen folgende Parameter übergeben werden. Parameter Pflicht Format Kommentar mid + N 6 ID des Händlers pid + N 6 ID des Zahlungsportals bpsecure + N 40 Hinterlegter Sicherheitscode für das Zahlungsportal (muss als MD5-Hash übergeben werden) api_version + AN 10 Version der Schnittstelle (aktuelle Version: 1.5.1). Die grundlegende Struktur eines jeden XML-Service-Requests sieht wie folgt aus (Detaillierte Beispiele für jeden XML-Service-Request finden Sie am Ende dieses Dokuments): <?xml version="1.0" encoding="utf-8"?> <data api_version="1.5.1"> <default_params mid="2" pid="3" bpsecure="0d48732f425b6df88c58244d6882369e" /> <! - weitere, Request-spezifische Daten --> </data> 7.5 Generelle Parameter für jede XML-Service-Response Mit jeder XML-Service-Response werden die folgenden Parameter zurückgegeben. Parameter Pflicht Format Kommentar (error) error_code + N 6 Fehlernummer. Standardwert ist 0 (kein Fehler) merchant_message - AN 255 Detailierte Fehlernachricht für den Händler. customer_message - AN 255 Fehlernachricht für den Kunden Hinweis: Im Produktivmodus dürfen jeweils nur die Fehlermeldungen für den Kunden nach außen hin sichtbar angezeigt werden. Die Händlerfehlermeldung enthält in einigen Fällen detailiertere Ausgaben, die nicht für den Kunden bestimmt sind. Hinweis: Falls ein Fehlercode größer 0 zurückgeliefert wird, enthalten die Felder merchant_message und customer_message in jedem Fall Fehlermeldungen. 7.6 Frontend Requests Die folgenden Requests werden aus dem Frontend (genauer, aus dem Checkout) he raus gesendet. 7.6.1 Modul Konfiguration (moduleconfig) Der moduleconfig Request wird eingesetzt, um vor dem Anzeigen der Zahlarten wichtige Konfigurationsparameter für das aktuelle Portal von der Billpay-Schnittstelle abzufragen und ggf. die 15
entsprechende Zahlart von vornherein auszublenden. Dies macht beispielsweise für den Fall Sinn, dass der Warenkorbwert ein für den jeweiligen Shop von Billpay vergebenes oberes Limit überschreitet. Es ist zu beachten, dass die Werte für die Limitsteuerung nicht durch den Händler beeinflusst werden können. 7.6.1.1 REQUEST moduleconfig Parameter Pflicht Format Kommentar (Lokalisierung) country - Vorgabe Land des Endkunden (z.b. DEU ) ISO3166 alpha-3 currency + Vorgabe Währung des Warenkorbs (z.b. EUR ) ISO 4217 language + Vorgabe ISO 639-1 Kennzeichen der Sprache des Endkunden (z.b. de ) 7.6.1.2 RESPONSE moduleconfig Parameter Pflicht Format Kommentar (Statisches Limit) directdebitstatic + N..10 Statisches Limit für Kauf per Lastschrift (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) hirepurchasestatic + N..10 Statisches Limit für Ratenkauf (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) invoicestatic + N..10 Statisches Limit für Kauf auf Rechnung (B2C) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) invoicebusinessstatic + N..10 Statisches Limit für Kauf auf Rechnung (B2B) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) Hinweis: Wenn der Gesamtwert des aktuellen Warenkorbs das statische Limit überschreitet, dann darf die entsprechende Zahlart nicht angezeigt werden. Parameter Pflicht Format Kommentar (Minimalwerte) directdebit + N..10 Minimaler Bestellwert für Kauf per Lastschrift (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) hirepurchase + N..10 Minimaler Bestellwert für Ratenkauf (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) invoice + N..10 Minimaler Bestellwert für Kauf auf Rechnung (B2C) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) invoicebusiness + N..10 Minimaler Bestellwert für Kauf auf Rechnung (B2B) (In 16
kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) Hinweis: Wenn der Gesamtwert des aktuellen Warenkorbs den Minimalwert für eine Zahlungsart unterschreitet, dann darf die entsprechende Zahlart nicht angezeigt werden. Parameter (Berechtigungen) active + Vorgabe 0: Nein 1: Ja directdebitallowed + Vorgabe 0: Nein 1: Ja hirepurchaseallowed + Vorgabe 0: Nein 1: Ja invoiceallowed + Vorgabe 0: Nein 1: Ja invoicebusinessallowed + Vorgabe 0: Nein 1: Ja Pflicht Format Kommentar Sind Zahlungsarten für aktuelles Portal erlaubt? Ist Zahlungsart Kauf per Lastschrift erlaubt? Ist Zahlungsart Ratenkauf erlaubt? Ist Zahlungsart Kauf auf Rechnung (B2C) erlaubt? Ist Zahlungsart Kauf auf Rechnung (B2B) erlaubt? Hinweis: Falls entweder das active -Flag oder das Flag für eine Zahlart 0 ist, darf die jeweilige Zahlart nicht angeboten werden. 7.6.2 Vorautorisierung (preauthorize) Bei der Vorauthorisierungsanfrage wird überprüft, ob der Kunde mit einer der Billpay-Zahlarten bestellen darf. Bei diesem Request wird die Identität und Bonität des Kunden überprüft. 7.6.2.1 REQUEST preauthorize Parameter Pflicht Format Kommentar tcaccepted + Vorgabe 1: Ja 0: Nein paymenttype + Vorgabe 1: Rechnungskauf 2: Lastschrift 3: Ratenkauf capturerequestnecessary - Vorgabe 1:Ja (Default) 0:Nein Hat der Kunde die Billpay-AGB akzeptiert? ID der Zahlart Falls 0 übergeben wird, wird die Bestellung ohne den capture-request finalisiert. Der capture-request darf in diesem Fall nicht gesendet werden. Falls 1 übergeben wird, wird die Bestellung erst mit erfolgreichem capture-request finalisiert 17
Nicht-optionale Liste 1..n Artikel Pflicht Format Kommentar (Bestelldaten Artikel) articleid + AN 20 Eindeutige Artikel-ID/Item-ID für die Warenkorbposition Wichtig! IDs dürfen in einer Anfrage nicht mehrfach auftreten. articlequantity + N 7 Menge dieses Artikels im Warenkorb articlename + AN 50 Name des Artikels articledescription - AN 50 Beschreibung des Artikels articleprice + N 7 Nettopreis des Artikels (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) articlepricegross + N 7 Bruttopreis des Artikels (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) Parameter Pflicht Format Kommentar (Bestelldaten Total) shippingname + AN 50 Versandkosten-Name (z.b. Express- Versand ) shippingprice + N 7 Nettowert aller warenkorbspez. Kosten (z.b. Lieferkosten, Zuschläge,...). (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) shippingpricegross + N 7 Bruttowert aller warenkorbspez. Kosten (z.b. Lieferkosten, Zuschläge,...). (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) rebate + N..7 Positiver Nettowert aller Rabatte, Coupons und sonstiger betragsmindernder Posten (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) rebategross + N..7 Positiver Bruttowert aller Rabatte, Coupons und sonstiger betragsmindernder Posten (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) carttotalprice + N 7 Nettowert der Bestellung (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) 18
carttotalpricegross + N 7 Bruttowert der Bestellung (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) currency + Vorgabe Währung der Bestellung (z.b. EUR ) reference + (falls capturerequestnecessary = 0 ) ISO 4217 AN 40 Bestellnummer beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) Parameter Pflicht Format Kommentar (Persondendaten) customerid - AN 20 Kundennummer beim Händler (Erlaubte Zeichen: 0-9, a- customertype + Vorgabe g: Guest n: New e: Existing salutation + Vorgabe 19 z, A-Z,.,-,_,/) - Guest - New Customer - Existing Customer Anrede (siehe Abschnitt 11.1) title - AN 20 Titel (z.b. Dr. ) firstname + AN 50 Vorname lastname + AN 50 Nachnahme street + AN 50 Straße streetno - AN 15 Hausnummer (Falls nicht von der Straße trennbar, im Feld street mitübergeben) addressaddition - AN 50 Adresszusatz / c/o zip + AN 7 Postleitzahl city + AN 50 Ort country + Vorgabe Land (z.b. DEU ) ISO3166 alpha-3 email + AN 50 E-Mail phone + (falls paymenttype = 3 oder falls country = NLD) AN 15 Telefonnummer cellphone - AN 50 Handynummer birthday + (falls customergroup = p ) N8 Geburtsdatum (YYYYMMDD) language + Vorgabe ISO 639-1 Sprachkennzeichen (z.b. de ) ip + Vorgabe IP-Adresse des Kunden IPv4 customergroup + Vorgabe p : Privatkunde (B2C) Kundengruppe Wichtig! Das B2B
b : Geschäftskunde (B2B) Produkt muss separat freigeschaltet werden Parameter Pflicht Format Kommentar (Lieferdaten) usebillingaddress + Vorgabe 0: Nein 1: Ja Rechnungsadresse = Lieferadresse? (Falls Ja müssen sämtliche Parameter für die Lieferdaten leer bleiben.) shipping - salutation + (falls usebillingaddress = 0 ) Vorgabe (siehe Abschnitt 11.1) Wichtig! Sobald der Endkunde eine abweichende Lieferadresse eingibt MUSS diese an Billpay übergeben werden! Anrede Versandadresse shipping - title - AN 20 Titel Versandadresse (z.b. Dr. ) shipping - firstname + (falls usebillingaddress = 0 ) AN 50 Vorname Versandadresse shipping - lastname shipping - street + (falls usebillingaddress = 0 ) + (falls usebillingaddress = 0 ) AN 50 AN 50 Nachname Versandadresse Straße Versandadresse shipping - streetno - AN 15 Hausnummer Versandadresse (Falls nicht von der Straße trennbar, bitte alles im Feld shipping_street übergeben) shipping - addressaddition - AN 50 Adresszusatz / c/o Versandadresse shipping - zip shipping - city shipping - country + (falls usebillingaddress = 0 ) + (falls usebillingaddress = 0 ) + (falls usebillingaddress = 0 ) AN 5 AN 50 Vorgabe ISO3166 alpha-3 Postleitzahl Versandadresse Ort Versandadresse Land Versandadresse (z.b. DEU ) shipping - phone - AN 15 Telefonnummer Versandadresse shipping - cellphone - AN 50 Handynummer Versandadresse 20
(Bankdaten) Pflicht Format Kommentar accountholder + (falls paymenttype in {2,3}) AN 100 Vor- und Zuname des Kontoinhabers accountnumber + (falls paymenttype in {2,3}) AN 34 IBAN des Kundenkontos sortcode + (falls paymenttype in {2,3} AN...11 BIC des Kundenkontos && IBAN!= DE ) Hinweis: Die Bankdaten werden nur bei den Zahlungsarten Zahlung per Lastschrift und Ratenkauf ausgewertet. Der übergebene Wert für den Parameter paymenttype muss in diesem Fall also 2 oder 3 sein. Andernfalls werden die Daten ignoriert. 7.6.2.1.1 SEPA Umrechner Billpay bietet für Ihre Kunden einen Service für die Umrechnung der klassischen Kontonummer und Bankleitzahl in zur IBAN und BIC. Hierzu wird eine kleine Applikation auf den Billpay Servern gehostet, die Sie via iframe wie folgt in Ihren Checkout integrieren können: <iframe src="https://www.billpay.de/api/sepa-umrechner/ " width="290" height="290" name="sepa Umrechner"> <p>ihr Browser kann leider keine eingebetteten Frames anzeigen: Sie können die eingebettete Seite über den folgenden Verweis aufrufen: <a href="https://www.billpay.de/api/sepa-umrechner/">sepa Umrechner</a></p> </iframe> (Firmendaten) Pflicht Format Kommentar name + (falls customergroup = b ) AN 200 Name der Firma legalform + (falls customergroup = b ) Vorgabe Rechtsform der Firma (siehe Abschnitt 11.2) registernumber + (falls customergroup = b ) (siehe Abschnitt 11.3 für weitere Details) AN 20 Handelsregisternummer/ Firmenbuch Wichtig! Das Feld ist erst ab API-Version 1.5.0 ein Pflichtfeld. Bitte beachten Sie, dass das Fehlen dieses Wertes die Annahmequote erheblich senkt. 21
holdername + (falls customergroup = b ) (siehe Abschnitt 11.3 für weitere Details) AN..100 taxnumber - gültige USt- IdNr. (DEXXXXXXXXX) Name eines Inhabers der Firma Wichtig! Das Feld ist erst ab API-Version 1.5.0 ein Pflichtfeld. Bitte beachten Sie, dass das Fehlen dieses Wertes die Annahmequote erheblich senkt. Umsatzsteueridentifikationsnummer Hinweis: Das Vorhandensein der USt- IdNr. erhöht die Trefferwahrscheinlichkeit. Hinweis: Die Firmendaten werden nur für die Kundengruppe Firmenkunden (B2B) und die Zahlart Kauf auf Rechnung ausgewertet. Der übergebene Wert für den Parameter customergroup muss in diesem Fall also b und der übergebene Wert für den Parameter paymenttype muss gleich 1 sein. Andernfalls werden die Daten ignoriert. Das Produkt B2B muss separat bei Billpay aktiviert werden. Optionale Liste 0..20 Bestellungen Pflicht Format Kommentar (Bestellhistorie) horderid + AN 20 Historische Bestellnummer des Händlers hdate + (YYYYMMDD hh:mm:ss) Bestelldatum hamount + N 7 Gesamtpreis (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) hcurrency + Vorgabe Währung (z.b. EUR ) ISO 4217 hpaymenttype + Vorgabe 0: Lastschrift 1: Kreditkarte 2: Vorkasse 3: Nachnahme 4: Paypal 5: Sofortüberweisung/Giropay Zahlungsart: - Lastschrift - Kreditkarte - Vorkasse - Nachnahme - Paypal - 22
6: Rechnung 7: Billpay (Rechnung) 100: Other hstatus + Vorgabe 0: Bezahlt 1: Offen 2: Mahnwesen 3: Inkasso 4: Überbezahlt 5: Unterbezahlt 6: Geplatzt Sofortüberweisung/Giropay - Rechnung - Billpay (Rechnung) - Andere Status der Bestellung Hinweis: Bitte maximal die 20 letzten Bestellungen des Kunden im Shop für die Bestellhistorie übergeben. Ende preauthorize Request Hinweis: Die mit der Vorauthorisierung übergebenen Bestelldaten werden einer Konsistenzprüfung unterzogen. Dabei muss die Summe der Einzelpositionen mit den übergebenen aggregierten Gesamtwerten übereinstimmen. Folgende Bedingungen müssen gelten: 1) carttotalpricegross = Summe(articlequantity X articlepricegross) + shippingpricegross - rebategross 2) carttotalprice = Summe(articlequantity x articleprice) + shippingprice - rebate Falls einzelne Eingabefelder mit Pflichtwerten nicht standardmässig im Bestellprozess des Shops vorgesehen sind, bietet es sich an, die Eingabefelder für diese Werte nach Auswahl der Zahlart speziell für die jeweilige Zahlart anzuzeigen. Werte, für die dies häufig der Fall ist, sind das Geburtsdatum und die Anrede/das Geschlecht. 7.6.2.2 RESPONSE preauthorize Parameter Pflicht Format Kommentar status - Vorgabe APPROVED / DENIED /leer Status der Identitäts- und Bonitätsprüfung bptid +(falls status = APPROVED ) AN...50 BILLPAY-Transaktionsnummer Parameter Pflicht Format Kommentar (korrigierte Addressdaten) street +(falls status = APPROVED ) AN 50 Korrigierte Straße 23
streetno +(falls status = APPROVED ) AN 15 Korrigierte Hausnummer zip +(falls status = APPROVED ) AN 5 Korrigierte Postleitzahl city +(falls status = APPROVED ) AN 50 Korrigierter Ort country +(falls status = APPROVED ) Vorgabe ISO3166 alpha-3 Korrigiertes Land (z.b. DEU ) Hinweis: Im Falle des APPROVED Statusflags korrigiert Billpay ggf. die Rechnungs- bzw. Lieferadresse. Billpay übernimmt für die Richtigkeit dieser Korrektur keine Haftung. Der Händler kann selbst entscheiden, ob er die korrigierten Adressen verwendet. Hinweis: Im Falle des DENIED Statusflags besteht keine Möglichkeit, dass der Kauf über Billpay abgewickelt werden kann. Folglich dürfen dem Kunden anschließend die Billpay-Zahlarten für die aktuelle Nutzersitzung nicht mehr angeboten werden. Hinweis: Im Falle eines Fehlercodes größer 1 (error_code > 1) und dem Fehlen des Statusfeldes liegt ein einfacher Validierungsfehler vor (z.b. ungültige Email oder Fehlen des Wertes für ein Pflichtfeld). In diesem Fall muss die Kundenfehlermeldung (Feld customer_message) angezeigt werden, so dass der Kunde die fehlerhaften Eingaben korrigieren kann. Falls die Vorauthorisierung im Auto-Capture Modus ausgeführt wird, werden im Erfolgsfall die Bankdaten mit der XML-Response zurückgeliefert (nur für Zahlart Kauf auf Rechnung ). Parameter (approved) account_holder account_number bank_code bank_name invoice_reference Pflicht Format Kommentar + (falls capturerequestnecessary = 0 ) + (falls capturerequestnecessary = 0 ) + (falls capturerequestnecessary = 0 ) + (falls capturerequestnecessary = 0 ) + (falls capturerequestnecessary = 0 ) AN 255 AN 40 AN 16 AN 255 AN 255 Kontoinhaber für die Forderung Billpay Kontonummer für die Forderung Billpay BLZ für die Forderung Billpay Name der Bank für die Forderung Verwendungszweck Wenn der zurückgegebene Fehlercode > 1 ist und das Statusfeld fehlt (der Nutzer also die Möglichkeit bekommen muss, seine fehlerhafte Eingabe zu korrigieren), dann wird mit der preauthorize-response eine Liste aller Eingabefelder zurückgegeben, die fehlerhafte Daten enthalten und vom Nutzer korrigiert werden sollen. Für jede fehlerhafte Eingabe enthält die Liste einen Eintrag 24
mit dem Fehlercode, einen Bezeichner für das Fehlerfeld und eine Kunden- sowie eine Händlerfehlermeldung. Um die Nutzerführung im Falle von einfachen Validierungsfehlern zu optimieren, werden sämtliche Kundenfehlermeldungen auf einmal angezeigt. Mit Hilfe des Fehlerfeldes können die Kundenfehlermeldungen direkt den Eingabe-Formularfeldern im Checkout des Onlineshops zugeordnet werden. Üblicherweise wird eine Fehlermeldung für einen Validierungsfehler direkt neben dem jeweiligen Formularfeld angezeigt, in dem die fehlerhafte Eingabe getätigt wurde. So wird die Korrektur der Eingabedaten optimiert und die Kaufabbruchrate minimiert. Optionale Liste 0..n Einträge Pflicht Format Kommentar (Validierungsfehler) error_code + N 6 Fehlernummer. Wert ist immer > 1 error_field - Vorgabe Fehlerfeld (siehe Abschnitt 11.4) customer_message + AN 255 Fehlernachricht für den Kunden merchant_message + AN 255 Detailierte Fehlernachricht für den Händler. Hinweis: Der Fehlercode sowie Kunden- und Händlerfehlermeldung des ersten Eintrags der Liste entsprechen immer den generellen Parametern der preauthorize-response (siehe Abschnitt 7.5). Hinweis: Falls das Statusfeld den Wert APPROVED oder DENIED hat, wird keine Liste mit Validierungsfehlern zurückgegeben. Hinweis: In einigen Fällen kann das Fehlerfeld auch leer sein. Dies ist der Fall, wenn der Validierungsfehler nicht einem bestimmten Eingabewert zugeordnet werden kann. 7.6.3 Finalisierung der Bestellung (capture) Der Request capture schließt die zuvor mit dem preauthorize Request eröffnete Bestellung ab, vorausgesetzt die Vorauthorisierung wurde nicht im Auto-Capture Modus ausgeführt. Mit erfolgreicher Durchführung des capture Requests wird die Forderung, die sich aus der Bestellung gegenüber dem Kunden ergibt an Billpay abgetreten. Wichtig! Der Capture-Request muss aus dem Checkout gesendet werden. Es ist nicht zulässig, dass dieser XML-Request durch eine Aktion im Backend durch den Händler ausgelöst wird. Die Vorauthorisierungsanfrage ist dementsprechend nur so lange gültig, wie die shopseitige Nutzsitzung gültig ist. 25
7.6.3.1 REQUEST capture Parameter Pflicht Format Kommentar bptid + N 12 BILLPAY Transaktionsnummer carttotalgross + N 7 Bruttowert der Bestellung (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) currency + Vorgabe Währung (z.b. EUR ) ISO 4217 reference + AN 40 Bestellnummer beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) customerid - AN 20 Kundennummer beim Händler (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/). Nur bei Bestands- oder Neukunden 7.6.3.2 RESPONSE capture Mit der capture-response wird im Fall der Zahlart Kauf auf Rechnung die Bankverbindung übertragen, auf die die Zahlung durch den Kunden zu leisten ist. Die Bankverbindung sollte idealweise schon auf der Bestellbestätigung aufgeführt werden, um Verwechslungen und daraus resultierende Zahlungsausfälle zu vermeiden. Darüber hinaus muss die Bankverbindung auf der Rechnung angezeigt werden. Bitte beachten Sie jedoch, dass die Daten für die Rechnung erst nach Ausführung des invoicecreated -Requests vollständig sind, da erst zu diesem Zeitpunkt das Fälligkeitsdatum berechnet und in der Response zurückgeliefert wird. Im Fall von Kauf per Lastschrift spielen diese Felder keine Rolle und können ignoriert werden. Parameter Pflicht Format Kommentar (approved) account_holder + AN 255 Kontoinhaber für die Forderung account_number + AN 40 Billpay Kontonummer für die Forderung bank_code + AN 16 Billpay BLZ für die Forderung bank_name + AN 255 Billpay Name der Bank für die Forderung invoice_reference + AN 255 Verwendungszweck 7.7 Backend Requests Die folgenden Requests werden entweder aus dem Backend des Shops oder falls diese zum Einsatz kommt - aus der Warenwirtschaft gesendet. 7.7.1 Aktivierung (invoicecreated) Der invoicecreated-request wird bei Kauf auf Rechnung dazu verwendet, das Zahlungsziel (20 bzw. 30 Tage ab Rechnungsdatum) für den Kunden zu starten. Dieser Vorgang wird Aktivierung genannt. Bei Zahlung per Lastschrift und Ratenkauf wird durch diesen Request das Einzugsdatum der Lastschrift für den gesamten Bestellwert bzw. beim Ratenkauf für die erste Rate bestimmt. Der invoicecreated-request muss für jede Bestellung immer unmittelbar vor der Rechnungserstellung 26
und der Auslieferung der Ware gesendet werden. Erst nach Erhalt einer erfolgreichen Antwort für diesen Request stehen alle notwendigen Daten zur Verfügung, die auf der Kundenrechnung angezeigt werden müssen. Einzige Ausnahme ist, wenn die Bestellung nicht zu Stande kommt. In diesem Fall muss die Bestellung bei Billpay storniert werden (siehe cancel -Request). Wichtig! Vor Senden des invoicecreated-requests müssen Verfügbarkeit und Auslieferbarkeit der bestellten Artikel für die aktuelle Bestellung sichergestellt werden. 7.7.1.1 REQUEST invoicecreated Parameter Pflicht Format Kommentar carttotalgross + N 7 Aktueller Bruttowert der gesamten Bestellung (etwaige Teilstornierungen berücksichtigt) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) currency + Vorgabe Währung (z.b. EUR ) ISO 4217 reference + AN 40 Bestellnummer der Hauptbestellung beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) delayindays + N...3 Anzahl Tage, um die sich das Zahlungsziels zusätzlich zu den 20/30 Tagen verschiebt Hinweis: Standardmässig ist nur die Aktivierung der gesamten Bestellung möglich. Die teilweise Aktivierung von Bestellungen muss separat bei Billpay freigeschaltet werden. Hierfür wird von Billpay auf Anfrage eine entpsrechende technische Dokumentation zur Verfügung gestellt. Wenn carttotalgross vom aktuellen Bestellwert abweicht, ohne dass die Teilaktivierung für den Account freigeschaltet ist, wird der Fehlercode 62 zurückgeliefert. 7.7.1.2 RESPONSE invoicecreated Mit der invoicecreated-response wird für Kauf auf Rechnung die Bankverbindung, auf die die Zahlung zu leisten ist (hierbei handelt es sich um exakt dieselbe Kontoverbindung, die bereits mit der capture -Response erhalten wurde) und das Fälligkeitsdatum der Forderung und für Ratenkauf die Fälligkeitsdaten für jede einzelne Rate übertragen. Diese Daten müssen jeweils auf der Rechnung angezeigt werden. Für Zahlung per Lastschrift werden keine zusätzlichen Daten zurückgegeben. Für die Rechnung genügt hier das anzeigen eines statischen Textes (s.u.). Parameter Pflicht Format Kommentar account_holder + AN 255 Kontoinhaber account_number + AN 40 Kontonummer (variiert für jede Bestellung!) bank_code + AN 16 Billpay BLZ für die Forderung bank_name + AN 255 Billpay Name der Bank für die Forderung invoice_reference + AN 255 Verwendungszweck invoice_duedate + N 8 Zahlungsziel des Kunden 27
activation_performed + Vorgabe 1: Ja 0: Nein (YYYYMMDD). Gibt an, ob die Bestellung mit dieser Anfrage aktiviert wurde Wichtig! Für die Zahlart Kauf auf Rechnung variiert die Kontonummer für jede Bestellung! Die Zahlungsinformationen auf der Rechnung müssen wie folgt dargestellt werden. Zusätzlich muss auf der Rechnung das Billpay-Logo abgebildet werden. Das skalierte Logo in unterschiedlichen Größen kann unter https://www.billpay.de/billpay-logo heruntergeladen werden. Kauf auf Rechnung (Billpay) Bitte überweisen Sie den Gesamtbetrag unter Angabe der Billpay-Transaktionsnummer im Verwendungszweck (%% invoice_reference %%) innerhalb der Zahlungsfrist bis zum %% invoice_duedate %% auf das folgende Konto: Kontoinhaber: %% account_holder %% Geldinstitut: %% bank_name %% BLZ: %% bank_code %% Kontonummer: %% account_number %% Fälligkeitsdatum: %% invoice_duedate %% Verwendungszweck: %% invoice_reference %% Lastschrift (Billpay) Vielen Dank, dass Sie sich für die Zahlung per Lastschrift mit Billpay entschieden haben. Der fällige Betrag wird in den nächsten Tagen durch die Billpay GmbH von dem bei der Bestellung angegebenen Konto abgebucht. Gestaltung der Zahlungsinformationen auf der Rechnung Informationen zur Gestaltung der Rechnung im Fall einer Bestellung mit dem Ratenkauf können dem Dokument Zusatzdokumentation für die Integration des Billpay-Ratenkauf (deutsch) entnommen werden. Wichtig! Im Falle der Zahlart Kauf auf Rechnung darf ausschließlich die Bankverbindung von Billpay auf der Endkundenrechnung angezeigt werden. Die Bankverbindung des Händlers darf nicht angezeigt werden. 28
7.7.2 Abrufen der Kontodaten (getbillpaybankdata) Mit dem getbillpaybankdata-request können die Kontodaten für eine Bestellung angefordert werden. Die Response enthält alle Informationen, die zum Begleichen der Rechnung durch den Käufer nötig sind. Ist eine Bestellung bereits aktiviert, enthält diese auch das gesetzte Zahlungsziel. Hinweis: In aller Regel reicht es aus, die Kontodaten über die capture- oder die invoicecreated Response abzugreifen. Der Request getbillpaybankdata ist nur dann nötig, wenn das Abgreifen der Kontodaten über diese beiden Requests bspw. aus prozesstechnischen Gründen nicht möglich ist. Hinweis: Das Abholen der Kontodaten ist erst nach erfolgreichem capture Request möglich. 7.7.2.1 REQUEST getbillpaybankdata Parameter Pflicht Format Kommentar reference + AN 40 Bestellnummer der Bestellung beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) 7.7.2.2 RESPONSE getbillpaybankdata Parameter Pflicht Format Kommentar account_holder + AN 255 Kontoinhaber account_number + AN 40 Kontonummer (variiert für jede Bestellung!) bank_code + AN 16 Billpay BLZ für die Forderung bank_name + AN 255 Billpay Name der Bank für die Forderung invoice_reference + AN 255 Verwendungszweck first_duedate + N 8 Zahlungsziel der einzigen Forderung bei vollständiger Aktvierung oder der ersten Teilforderung bei Teilaktivierung für den Kunden. Entspricht dem ersten Element der Liste mit den Zahlungszielen. (YYYYMMDD) activation_performed + Vorgabe 1: Ja 0: Nein Gibt an, ob die Bestellung mit dieser Anfrage aktiviert wurde Liste mit Zahlungzielen Parameter Pflicht Format Kommentar Duedate + N..8 Zahlungsziel der n-ten Teilforderung für den Kunden (YYYYMMDD). invoice_number + AN 40 Händlerseitige Referenznummer für die n-te Teilforderung. 29
7.7.3 Vollstornierung (cancel) Über den cancel Request wird eine zuvor mit dem capture Request eröffnete Forderung vollständig storniert. Falls der Kunde bereits Zahlungen an Billpay geleistet hat ( Kauf auf Rechnung ) oder der fällige Betrag bereits von dem Konto des Kunden abgebucht wurde ( Kauf per Lastschrift ), wird individuell mit dem Händler abgestimmt, wie die Rückabwicklung der bereits geleisteten Zahlung umgesetzt wird. Hinweis: Ggf. entstehen bei der Vollstornierung einer Bestellung Kosten für den Händler. So bald eine Stornierung bei Billpay eingeht, wird der Kunde von Billpay per E-Mail über die Stornierung informiert. 7.7.3.1 REQUEST cancel Parameter Pflicht Format Kommentar reference + AN 40 Bestellnummer des Händlers. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) carttotalgross + N 7 Aktueller Bruttowert der Bestellung (Etwaige Teilstornierungen berücksichtigt) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) currency + Vorgabe ISO 4217 Währung (z.b. EUR ) 7.7.3.2 RESPONSE cancel Es werden gegenüber den generellen Parametern keine zusätzlichen Parameter übergeben. 7.7.4 Änderung des Warenkorbinhalts (editcartcontent) Mit dem editcartcontent -Request kann der Warenkorb einer Bestellung im Billpay-System nachträglich geändert werden. Es können bspw. im Falle einer Retoure einzelne Artikel oder ganze Warenkorbpositionen aus dem Warenkorb entfernt werden. Es können aber auch nachträglich Artikel in den Warenkorb eingefügt werden, die vorher noch nicht enthalten waren (Einschränkungen siehe unten). Mit dem editcartcontent-request meldet der Händler Billpay den neuen Warenkorbinhalt. Bei erfolgreichem Absetzen der Anfrage wird der alte Warenkorb vollständig verworfen. Sämtliche Artikelpositionen, die nicht mehr im Warenkorb enthalten sein sollen, werden nicht mehr übergeben. Rechnungs- und Lieferadresse des Kunden, Bestellreferenznummer, Währung und Zahlart können jedoch nicht geändert werden. 30