Dokumentation der Billpay XML-API. (Technische Dokumentation) (Version 1.9.9)

Transkript

1 Dokumentation der Billpay XML-API (Technische Dokumentation) (Version 1.9.9) 1

2 Inhaltsverzeichnis Änderungshistorie... 3 Was ist Billpay? Zielgruppe Wichtiger Hinweis Downloads In welchen Ländern ist Billpay verfügbar Anzeigen der Datenschutzbestimmungen von Billpay Prozessdiagramm XML-Schnittstelle Webservice-URL Das Billpay-Backoffice Übersicht über die XML-Service-Requests Generelle Parameter für jeden XML-Service-Request Generelle Parameter für jede XML-Service-Response Frontend Requests Modul Konfiguration (moduleconfig) Vorautorisierung (preauthorize) Finalisierung der Bestellung (capture) Backend Requests Aktivierung (invoicecreated) Abrufen der Kontodaten (getbillpaybankdata) Vollstornierung (cancel) Änderung des Warenkorbinhalts (editcartcontent) DEPRECATED - Teilstornierung/Teilretour (partialcancel) Geldeingang vom Kunden (reportcustomerpayment) Clientseitige API XML-Beispiele Kontakt für Rückfragen Anhang Erlaubte Werte für das Feld salutation der Vorauthorisierungsanfrage Erlaubte Werte für das Feld legalform der Vorauthorisierungsanfrage Wann sind die Felder registernumber und holdername Pflichtfelder? Mögliche Werte für das Feld error_field der Vorauthorisierungsantwort

3 Änderungshistorie Version Datum Bemerkungen Mai 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 Mai Erforderliche Parameter für Internationalisierung eingefügt: moduleconfig und partialcancel Requests erweitert Juni 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 Juli Neuen Text und neue Grafik für die Bestätigung der Datenschutzbestimmungen im Checkout eingefügt August September Januar April 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 editcart- Content 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 März Dokumentation von neuem getbillpaybankdata Request. - Tabelle mit angebotenen Zahlarten erweitert Sept Entfernen von Ratenkaufparametern aus Preauthorization Paragraph 3

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 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 4

5 3 Downloads Die aktuellste Version dieser technischen Dokumentation und den für die Integration benötigte Quellcode finden Sie unter der URL 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 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 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=' target='blank'> Billpay GmbH</a> bin ich einverstanden. Es gelten die <a href="[link auf Datenschutzbestimmungen]"> Datenschutzbestimmungen</a> von Billpay. 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): 5

6 Dokument Webseite Popup Datenschutz (Deutschland) Datenschutz (Schweiz) Datenschutz (Österreich) datenschutz datenschutz datenschutz datenschutz datenschutz 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): 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. 6

7 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 Bestellprozesses Bestellung akzeptiert Abschließende Übersicht über die Bestellung Erfassungsanfrage (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) 7

8 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. 8

9 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 & & " " ' &apos; < < > > 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: 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 39). 9

10 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 für das aktuelle Portal Zu Beginn des Bestellprozesses [Basis-Url]/ moduleconfig Ja Nein Flag für jede ZA ob diese für aktuelles Portal verfügbar ist. Oberes/unteres Limit pro ZA Vorautorisierung Prüfung des Kunden auf Identität bzw. Bonität Bestellprozess. Nach Auswahl der Zahlart [Basis-Url]/ preauthorize Ja Nein Status der Prüfung und ggf.korrigierte Adresse Erfassung Bestätigung, dass Bestellung abgeschlossen wird Bestellprozess. Beim Anlegen der Bestellung im Shop [Basis-Url]/ capture Ja Nein Rechnung: Billpay-Kontodaten für die Rechnung Lastschrift: - Aktualisierung Aktualisierung der Bestell-ID. Falls Erfassung vor Anlegen der Bestellung geschieht und die Bestell-ID zu diesem ZP noch nicht feststeht Bestellprozess. Nach Anlegen der Bestellung im Shop 3 [Basis-Url]/ updateorder Nein Nein - Aktivierung Rechnung: Starten des Zahlungsziels (20 bzw. 30 Tage) Lastschrift: Initiierung des Bankeinzugs Bei Erstellung der Rechnung. Wird i.d.r. im Backend durch eine spezielle Aktion ausgelöst [Basis-Url]/ invoicecreated Ja Ja Rechnung: Billpay-Kontodaten und Zahlungsziel als Zeitstempel Lastschrift: - 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! 10

11 Vollstornierung Stornierung der gesamten Bestellung Wird i.d.r. im Backend durch eine spezielle Aktion ausgelöst [Basis-Url]/ cancel Nein Ja - Warenkorb ändern Änderung des Warenkorbinhalts oder der Liefergebühren bzw. Rabatte der Bestellung Wird i.d.r. im Backend durch Gutschrift, Teilstornierung oder Änderung der Bestellung ausgelöst [Basis-Url]/ editcartcontent Nein Nein - Teilstornierung DEPRECATED! Stornierung einzelner Posten der Bestellung/ Stornierung von Teilbeträgen Wird i.d.r. im Backend durch eine spezielle Aktion ausgelöst [Basis-Url]/ partialcancel Nein Ja - Geldeingang vom Kunden Nur Rechnungskauf: Händler meldet Billpay, dass Kunde auf Konto des Händlers überwiesen hat Aus dem Backend, falls Kunde auf das Konto des Händlers überweist [Basis-Url]/ report- CustomerPayment Nein Ja - Billpay Bankdaten abholen Nur Rechnungskauf: Abholen der Bankverbindung von Billpay zur Anzeige auf der Rechnunf Wird aus dem Backend heraus gesendet, falls das Abgreifen der Bankdaten von der captureoder invoice- Created Response nicht möglich ist [Basis-Url]/ getbillpaybank- Data Nein Nein Bankverbindung von Billpay und Zahlungsziel für die Rechnung 11

12 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="0d48732f425b6df88c58244d e" /> <! - 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) heraus gesendet 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 ent- 12

13 sprechende 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 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 Kennzeichen der Sprache des Endkunden (z.b. de ) 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 kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) 13

14 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 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 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 14

15 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) carttotalpricegross + N 7 Bruttowert der Bestellung 15

16 currency + Vorgabe ISO 4217 reference + (falls capturerequestnecessary AN 40 = 0 ) (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) Währung der Bestellung (z.b. EUR ) 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 16 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 5 Postleitzahl city + AN 50 Ort country + Vorgabe Land (z.b. DEU ) ISO3166 alpha-3 + AN 50 phone + (falls paymenttype = AN 15 Telefonnummer 3) cellphone - AN 50 Handynummer birthday + (falls customergroup = p ) N8 Geburtsdatum (YYYYMMDD) language + Vorgabe ISO Sprachkennzeichen (z.b. de ) ip + Vorgabe IP-Adresse des Kunden IPv4 customergroup + Vorgabe p : Privatkunde (B2C) b : Geschäftskunde (B2B) Kundengruppe Wichtig! Das B2B Produkt muss separat freigeschaltet werden

17 Parameter (Lieferdaten) usebillingaddress + Vorgabe 0: Nein 1: Ja shipping - salutation Pflicht Format Kommentar + (falls usebillingaddress = 0 ) Vorgabe (siehe Abschnitt 11.1) Rechnungsadresse = Lieferadresse? (Falls Ja müssen sämtliche Parameter für die Lieferdaten leer bleiben.) 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 (Bankdaten) Pflicht Format Kommentar accountholder + (falls paymenttype in {2,3}) AN 100 Vor- und Zuname des Kontoinhabers accountnumber + (falls paymenttype in {2,3}) N 10 Kontonummer 17

18 sortcode + (falls paymenttype in {2,3}) N...8 Bankleitzahl 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. (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 ein Pflichtfeld. Bitte beachten Sie, dass das Fehlen dieses Wertes die Annah- holdername + (falls customergroup = b ) (siehe Abschnitt 11.3 für weitere Details) AN..100 taxnumber - gültige USt- IdNr. (DEXXXXXXXXX) mequote erheblich senkt. Name eines Inhabers der Firma Wichtig! Das Feld ist erst ab API-Version 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. 18

19 Optionale Liste 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 6: Rechnung 7: Billpay (Rechnung) 100: Other hstatus + Vorgabe 0: Bezahlt 1: Offen 2: Mahnwesen 3: Inkasso 4: Überbezahlt 5: Unterbezahlt 6: Geplatzt Zahlungsart: - Lastschrift - Kreditkarte - Vorkasse - Nachnahme - Paypal - 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 19

20 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 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 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 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 ). 20

21 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 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. 21

22 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 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 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 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 22

23 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 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 invoice- Created-Request muss für jede Bestellung immer unmittelbar vor der Rechnungserstellung 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 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. 23

24 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 (YYYYMMDD). activation_performed + Vorgabe 1: Ja 0: Nein 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 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 %% 24

25 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 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 REQUEST getbillpaybankdata Parameter Pflicht Format Kommentar reference + AN 40 Bestellnummer der Bestellung beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) 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 25

26 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 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 über die Stornierung informiert 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 ) 26

27 RESPONSE cancel Es werden gegenüber den generellen Parametern keine zusätzlichen Parameter übergeben Ä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. Durch den editcartcontent-request ist prinzipiell auch eine nachträgliche Erhöhung des Bestellwertes möglich. Hierfür gelten die folgenden Regeln: 1) Wenn der neue Warenkorbwert kleiner oder gleich dem alten Warenkorbwert ist, wird die Änderung des Warenkorbs in jedem Fall akzeptiert. 2) Wenn der neue Warenkorbwert größer als der alte Warenkorbwert ist, wird auf Seiten von Billpay versucht, den Kunden für den höheren Bestellwert zu autorisieren. Wenn die Autorisierung erfolgreich ist, wird der Warenkorb entsprechend der Anfrage angepasst. Schlägt die Autorisierung hingegen fehl, wird die Anfrage mit dem Fehlercode 105 abgelehnt und der alte Warenkorb bleibt für die Bestellung bestehen. Wenn ein editcartcontent-request über die XML-Schnittstelle für eine bereits aktivierte Bestellung eingeht und erfolgreich verarbeitet werden kann, informiert Billpay den Kunden umgehend über die Anpassung des Forderungsbetrags. Ist die Bestellung noch nicht aktiviert, wird der Kunde nicht informiert. Hinweis: Der editcartcontent Request kann sowohl vor als auch nach der Aktivierung gesendet werden. 27

28 REQUEST editcartcontent 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) carttotalpricegross + N 7 Bruttowert der Bestellung (In kleinster Währungseinheit! Z.B. 28

29 currency + Vorgabe ISO ,00 Euro = 10000) Währung der Bestellung (z.b. EUR ) Hinweis: Muss identisch mit dem bei der Vorauthorisierung übergebenen Wert sein. reference + AN 40 Bestellnummer beim Händler. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) Hinweis: Muss identisch mit dem bei der Vorauthorisierung übergebenen Wert sein. Hinweis: Die mit dem editcartcontent-request übergebenen Bestelldaten werden analog zur Vorauthorisierungsanfrage 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 Schlägt die Konsistenzprüfung fehl, wird Fehlercode 53 zurückgegeben RESPONSE editcartcontent Es werden gegenüber den generellen Parametern keine zusätzlichen Parameter übergeben DEPRECATED - Teilstornierung/Teilretour (partialcancel) Bitte beachten! Es wird empfohlen, für Teilstornos und Teilretouren nur noch den editcartcontent-request zu verwenden (siehe Abschnitt 7.7.4) und auf den partialcancel-request vollständig zu verzichten! Über den partialcancel Request kann eine Bestellung im Billpay-System nachträglich reduziert werden, beispielsweise wenn der Kunde von seinem Widerrufsrecht Gebrauch macht und einen Teil seiner Bestellung zurücksendet. Beim Entfernen einzelner Artikel aus der offenen Bestellung wird der Gesamtbetrag um den Betrag der einzelnen Artikel reduziert. Lieferkosten sowie etwaige Rabatte, die mit der Vorauthorisierung übergeben wurden, können ebenfalls teilstorniert werden. Wenn ein partialcancel Request über die XML-Schnittstelle für eine bereits aktivierte Bestellung eingeht, informiert Billpay den Kunden umgehend über die Anpassung des Forderungsbetrags. Ist die Bestellung noch nicht aktiviert, wird der Kunde nicht informiert. 29

30 REQUEST partialcancel Parameter Pflicht Format Kommentar reference + AN 40 Bestellnummer des Händlers. (Erlaubte Zeichen: 0-9, a-z, A-Z,.,-,_,/) rebatedecrease + (-) N 7 Änderung des Netto-Gesamtwertes der Bestellung. Positiver Wert bedeutet Verringerung des Gesamtwertes. (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) rebatedecreasegross + (-) N 7 Änderung des Brutto- Gesamtwertes der Bestellung. Positiver Wert bedeutet Verringerung des Gesamtwertes. (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) shippingdecrease - N...7 Reduzierung der Netto- Liefergebühren. (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) shippingdecreasegross - N...7 Reduzierung der Brutto- Liefergebühren (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000) currency + Vorgabe Währung (z.b. EUR ) ISO 4217 Hinweis: Der partialcancel-request kann vor und/oder nach der Aktivierung ausgeführt werden. Optionale Liste Parameter für 0..n Artikel Pflicht Format Kommentar (Bestelldaten Artikel) articleid + AN 20 Artikel-ID/Item-ID beim Händler articlequantity + N 7 Anzahl der Artikel, die storniert werden sollen Hinweis: Artikel die anhand des Wertes für articleid nicht (mehr) im Warenkorb gefunden werden können, werden bei der Reduzierung des Bestellwertes und des Warenkorbs ignoriert. Wichtig! Der Preis eines einzelnen Artikels kann durch den partialcancel-request nicht verändert werden! Änderungen von Artikelpreisen müssen aggregiert als wertemäßige Reduktion in den Feldern rebatedecrease und rebatedecreasegross übergeben werden. In diesem Fall darf der jeweilige Artikel nicht in der Artikelliste übergeben werden. 30