XML-Schnittstelle für die Billpay

Transcrição

XML-Schnittstelle für die
Billpay-Zahlungsarten
Technische Dokumentation
(Version 1.9.1)
1
Inhaltsverzeichnis
1
Änderungshistorie ........................................................................................................................... 3
2
Was ist Billpay? ................................................................................................................................ 4
3
Zielgruppe ........................................................................................................................................ 4
4
Downloads ....................................................................................................................................... 4
5
Allgemeine Geschäftsbedingungen und Datenschutzbestimmungen ............................................ 5
6
Prozessdiagramm ............................................................................................................................ 6
7
XML-Schnittstelle............................................................................................................................. 7
7.1
Webservice-URL ...................................................................................................................... 8
7.2
Das Billpay-Backoffice ............................................................................................................. 8
7.3
Übersicht über die XML-Service-Requests .............................................................................. 9
7.4
Generelle Parameter für jeden XML-Service-Request .......................................................... 10
7.5
Generelle Parameter für jede XML-Service-Response .......................................................... 10
7.6
Frontend Requests ................................................................................................................ 11
7.6.1
Modul Konfiguration ..................................................................................................... 11
7.6.2
Vorautorisierung............................................................................................................ 12
7.6.3
Finalisierung der Bestellung (capture) .......................................................................... 18
7.7
Backend Requests ................................................................................................................. 20
7.7.1
Aktivierung / Layout der Endkundenrechnung ............................................................. 20
7.7.2
Vollstornierung .............................................................................................................. 22
7.7.3
Teilstornierung/Teilretour ............................................................................................. 22
8
Clientseitige API ............................................................................................................................. 24
9
XML-Beispiele ................................................................................................................................ 25
10 Kontakt für Rückfragen.................................................................................................................. 31
11 Anhang........................................................................................................................................... 32
11.1
Erlaubte Werte für das Feld „salutation“ .............................................................................. 32
2
1
Ä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
3
2 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 BillpayRatenkauf (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 Shopsysteme1
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.
3 Zielgruppe
Diese technische Dokumentation richtet sich an Softwareentwickler, die eine Anbindung an die XMLZahlungsschnittestelle von Billpay realisieren wollen.
4 Downloads
Das 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.
1
Bitte beachten Sie bei der Installation die technische Dokumentation für das jeweilige Plugin
4
5 Allgemeine Geschäftsbedingungen und Datenschutzbestimmungen
Bevor eine Billpay-Zahlart im Bestellprozess des Shops durch den Kunden genutzt werden darf, muss
der Kunde die AGB und 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:
Hiermit bestätige ich die <strong><a href="[Link auf AGB]"
target="_blank">AGB</a></strong> und <strong><a href="[Link auf
Datenschutzbestimmungen]" target="_blank">Datenschutzbestimmungen
</a></strong> der Billpay GmbH.
Die Platzhalter für die Verweise müssen durch die entsprechenden Werte aus der folgenden Tabelle
ersetzt werden (maßgeblich für die Auswahl der Verweise ist das Land, in dem die Rechnungsadresse
des Kunden liegt):
Dokument
Webseite
Popup
AGB
(Deutschland)
Datenschutz
(Deutschland)
AGB
(Schweiz)
Datenschutz
(Schweiz)
https://www.billpay.de/kunden/agb
https://www.billpay.de/api/agb
https://www.billpay.de/kunden/agb#
datenschutz
https://www.billpay.de/kunden/agb-ch
https://www.billpay.de/api/agb#
datenschutz
https://www.billpay.de/api/agb-ch
https://www.billpay.de/kunden/agb-ch#
datenschutz
https://www.billpay.de/api/agb-ch#
datenschutz
Die AGB und Datenschutzbestimmungen sind in verschiedenen Sprachen abrufbar. Wenn Sie die
Schweizer Dokumente bspw. In französischer Sprache anzeigen wollen, nutzen Sie dafür die folgenden Links:
AGB (Webseite):
Datenschutz (Webseite):
https://www.billpay.de/kunden/agb-ch?lang=fr
https://www.billpay.de/kunden/agb-ch?lang=fr/#datenschutz
Falls die AGB nicht bestätigt worden sind (z.B. durch Aktivierung einer Checkbox), muss ein entsprechender Hinweis angezeigt und der Bestellvorgang darf nicht fortgesetzt werden.
5
6
Prozessdiagramm
Technischer Ablauf eines Einkaufs über Billpay.
Online-Händler
Billpay
Auswahl der Zahlart
Kunde wählt
Billpay-Zahlart
Vorauthorisierungsanfrage
(preauthorize)
Überprüfung der Anfrage
- Authentifizierungsparameter des Händlers
- Rechnungs-/Lieferadresse
- Warenkorb
- Historische Bestelldaten bei Bestandskunden
- Bankeinzugsdaten (nur für Lastschrift)
Bezahlung über Billpay
nicht möglich. Auswahl
alternativer Zahlart.
Fehler/Bestellung abgelehnt
- Fehlercode
- Fehlermeldung für Händler
- Fehlermeldung für Kunden
Fortsetzung des Bestellprozesses
Abschließende Übersicht
über die Bestellung
Ergebnis
der Anfrage
Bestellung akzeptiert
Erfassungsanfrage
(capture)
Überprüfung der Anfrage
- Transaktionsnummer
- Warenkorbwert (Prüfsumme)
Bezahlung über Billpay
nicht möglich. Auswahl
alternativer Zahlart.
Erfolgreicher
Abschluß der
Bestellung
Fehler
- Fehlercode
- Fehlermeldung für Händler
- Fehlermeldung für Kunden
Erfassung bestätigt
Zahlungsdetails (für Rechnung)
6
Ergebnis
der Anfrage
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 BillpaySchnittstelle 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ühst mö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 mit der Erfassungsanfrage bei Billpay finalisiert wurde, muss unmittelbar vor der
Auslieferung aus dem Backend heraus aktiviert (siehe invoiceCreated-Request) werden. 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
die XML-Schnittstelle 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.
7
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 XMLStandards durch ihre Escape-Sequenzen wie folgt ersetzt werden:
Reserviertes
Zeichen
&
EscapeSequenz
&
"
"
'
'
<
<
>
>
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 XMLService-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 31).
8
7.3 Übersicht über die XML-Service-Requests
Zeitpunkt
XML-Service
Semantik
des Aufrufs
Service-URL
Pflicht
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:
BillpayKontodaten für
2
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
3
im Shop
[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
Adminbereich
des Shops
durch eine
spezielle Aktion ausgelöst
[Basis-Url]/
invoiceCreated
Ja
Ja
Rechnung:
BillpayKontodaten 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!
9
Vollstornierung
Stornierung der
gesamten Bestellung
Wird i.d.R. im
Adminbereich
des Shops
durch eine
[Basis-Url]/
cancel
Nein
Ja
-
Teilstornierung
Stornierung einzelner Posten der
Bestellung/
Stornierung von
Teilbeträgen
Wird i.d.R. im
Adminbereich
des Shops
durch eine
[Basis-Url]/
partialcancel
Nein
Ja
-
7.4 Generelle Parameter für jeden XML-Service-Request
Mit jedem XML-Service-Request müssen folgende Parameter übergeben werden.
Parameter
mid
pid
bpsecure
Pflicht
+
+
+
Format
N…6
N…6
N…40
api_version
+
AN…10
Kommentar
ID des Händlers
ID des Zahlungsportals
Hinterlegter Sicherheitscode für das Zahlungsportal
(muss als MD5-Hash übergeben werden)
Version der Schnittstelle (aktuelle Version: 1.4.0).
7.5 Generelle Parameter für jede XML-Service-Response
Mit jeder XML-Service-Response werden die folgenden Parameter zurückgegeben.
Parameter
(error)
error_code
Pflicht
Format
Kommentar
+
N…6
merchant_message
-
AN…255
customer_message
-
AN…255
Fehlernummer. Standardwert ist „0“
(kein Fehler)
Detailierte Fehlernachricht für den Händler.
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 ist.
Hinweis: Falls ein Fehlercode größer 0 zurückgeliefert wird, enthalten die Felder merchant_message
und customer_message in jedem Fall Fehlermeldungen.
10
7.6 Frontend Requests
Die folgenden Requests werden aus dem Frontend (genauer, aus dem Checkout) heraus gesendet.
7.6.1 Modul Konfiguration
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 entsprechende Zahlart von vornherein auszublenden. Dies macht beispielsweise für den Fall Sinn, dass
der Warenkorbwert ein für den jeweiligen Shop von Billpay vergebendes 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
(Lokalisierung)
country
Pflicht
Format
Kommentar
-
Land des Endkunden (z.B. „DEU“)
currency
+
language
+
Vorgabe
ISO3166
alpha-3
Vorgabe
ISO 4217
Vorgabe
ISO 639-1
Währung des Warenkorbs (z.B. „EUR“)
Kennzeichen der Sprache des Endkunden
(z.B. „de“)
7.6.1.2 RESPONSE “moduleConfig”
Parameter
(Statisches Limit)
directdebitstatic
Pflicht
Format
Kommentar
+
N..10
hirepurchasestatic
+
N..10
invoicestatic
+
N..10
invoicebusinessstatic
+
N..10
Statisches Limit für “Kauf per Lastschrift”
(In kleinster Währungseinheit! Z.B. 100,00 Euro =
10000)
Statisches Limit für “Ratenkauf” (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000)
Statisches Limit für “Kauf auf Rechnung (B2C)” (In
kleinster Währungseinheit! Z.B. 100,00 Euro =
10000)
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 warden.
Parameter
(Minimalwerte)
directdebit
Pflicht
Format
Kommentar
+
N..10
Minimaler Bestellwert für „Kauf per Lastschrift“
(In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000)
11
hirepurchase
+
N..10
invoice
+
N..10
invoicebusiness
+
N..10
Minimaler Bestellwert für „Ratenkauf“ (In kleinster Währungseinheit! Z.B. 100,00 Euro = 10000)
Minimaler Bestellwert für „Kauf auf Rechnung (B2C)“ (In
kleinster Währungseinheit! Z.B. 100,00 Euro = 10000)
Minimaler Bestellwert für „Kauf auf Rechnung (B2B)“ (In
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 warden.
Parameter
(Berechtigungen)
active
Pflicht
Format
Kommentar
+
Sind Zahlungsarten für aktuelles Portal erlaubt?
directdebitallowed
+
hirepurchaseallowed
+
invoiceallowed
+
invoicebusinessallowed
+
Vorgabe
0: Nein
1: Ja
Vorgabe
0: Nein
1: Ja
Vorgabe
0: Nein
1: Ja
Vorgabe
0: Nein
1: Ja
Vorgabe
0: Nein
1: Ja
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 engeboten werden
7.6.2 Vorautorisierung
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
tcaccepted
Pflicht
+
paymenttype
+
capturerequestnecessary
-
Format
Vorgabe
1: Ja
0: Nein
Vorgabe
1: Rechnungskauf
2: Lastschrift
3: Ratenkauf
Vorgabe
1:Ja (Default)
12
Kommentar
Hat der Kunde die Billpay-AGB akzeptiert?
Typ der Zahlart
Falls „0“ übergeben wird, wird die Bestellung ohne den capture-Request finali-
0:Nein
siert. Der capture-Request darf in diesem
Fall nicht gesendet werden. Falls „1“
übergeben wird, wird die Bestellung erst
mit erfolgreichem capture-Request finalisiert
Nicht-optionale Liste
1..n Artikel
(Bestelldaten Artikel)
articleid
Pflicht
Format
Kommentar
+
AN…20
articlequantity
articlename
articledescription
articleprice
+
+
+
N…7
AN…50
AN…50
N…7
articlepricegross
+
N…7
Eindeutige Artikel-ID/Item-ID für die Warenkorbposition (IDs dürfen sich in einer Anfrage nicht
wiederholen!)
Menge dieses Artikels im Warenkorb
Name des Artikels
Beschreibung des Artikels
Artikelpreis Netto
10000)
Artikelpreis Brutto
10000)
Parameter
(Bestelldaten Total)
shippingname
Pflicht
Format
Kommentar
+
AN…50
shippingprice
+
N…7
shippingpricegross
+
N…7
rebate
+
N..7
rebategross
+
N..7
Versandkosten-Name (z.B. „ExpressVersand“)
Nettowert aller warenkorbspez. Kosten (z.B. Lieferkosten, Zuschläge, ...).
(In kleinster Währungseinheit! Z.B.
100,00 Euro = 10000)
Bruttowert aller warenkorbspez.
Kosten (z.B. Lieferkosten, Zuschläge,
...).
100,00 Euro = 10000)
Positiver Nettowert aller Rabatte,
Coupons und sonstiger betragsmindernder Posten
100,00 Euro = 10000)
Positiver Bruttowert aller Rabatte,
Coupons und sonstiger betragsmin-
13
carttotalprice
+
N…7
carttotalpricegross
+
N…7
currency
+
reference
+ (falls capturerequestnecessary
= „0“)
Vorgabe
ISO 4217
AN…40
dernder Posten
100,00 Euro = 10000)
Nettowert der Bestellung
100,00 Euro = 10000)
Bruttowert der Bestellung
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
(Persondendaten)
customerid
-
Format
Kommentar
AN…20
customertype
+
salutation
+
title
firstname
lastname
street
streetno
+
+
+
-
Vorgabe
g: Guest
n: New
e: Existing
Vorgabe
(siehe Abschnitt 11.1)
AN…20
AN…50
AN…50
AN…50
AN…15
Kundennummer beim
Händler
(Erlaubte Zeichen: 0-9, az, A-Z, .,-,_,/)
- Guest
- New Customer
- Existing Customer
addressAddition
zip
city
country
+
+
+
email
phone
+
+ (falls paymenttype =
3)
+ (falls
customerGroup = „p“)
+
cellphone
birthday
language
AN…50
AN…5
AN…50
Vorgabe
ISO3166 alpha-3
AN…50
AN…15
AN…50
N8
Vorgabe
14
Anrede
Titel (z.b. „Dr.“)
Vorname
Nachnahme
Straße
Hausnummer (Falls nicht
von der Straße trennbar,
im Feld street mitübergeben)
Adresszusatz / c/o
Postleitzahl
Ort
Land (z.B. „DEU“)
E-Mail
Telefonnummer
Handynummer
Geburtsdatum
(YYYYMMDD)
Sprachkennzeichen (z.B.
ip
+
customerGroup
+
ISO 639-1
Vorgabe
IPv4
Vorgabe
„p“: Privatkunde (B2C)
„b“: Geschäftskunde (B2B)
„de“)
IP-Adresse des Kunden
Kundengruppe
Wichtig! Das B2B Produkt muss separat freigeschaltet werden
Parameter
(Lieferdaten)
usebillingaddress
Pflicht
Format
Kommentar
+
shipping_salutation
+
Rechnungsadresse = Lieferadresse?
(Falls „Ja“ müssen sämtliche Parameter für die Lieferdaten leer bleiben.)
Anrede Versandadresse
shipping_title
shipping_firstname
shipping_lastname
shipping_street
shipping_streetno
+
+
+
-
Vorgabe
0: Nein
1: Ja
Vorgabe
(siehe Abschnitt
11.1)
AN…20
AN…50
AN…50
AN…50
AN…15
shipping_addressAddition
shipping_zip
shipping_city
shipping_country
+
+
+
shipping_phone
shipping_cellphone
-
AN…50
AN…5
AN…50
Vorgabe
ISO3166 alpha-3
AN…15
AN…50
Telefonnummer Versandadresse
Handynummer Versandadresse
Kommentar
Vor- und Zuname des
Kontoinhabers
accountnumber
+ (falls paymentType in {2,3}) N…10
Kontonummer
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.
(Bankdaten)
accountholder
Pflicht
+ (falls paymentType in {2,3})
Titel Versandadresse (z.b. „Dr.“)
Vorname Versandadresse
Nachname Versandadresse
Straße Versandadresse
Hausnummer Versandadresse (Falls
nicht von der Straße trennbar, bitte
alles im Feld ‚shipping_street‘ übergeben)
Adresszusatz / c/o Versandadresse
Postleitzahl Versandadresse
Ort Versandadresse
Land Versandadresse (z.B. „DEU“)
15
Format
AN…100
(Zusätzliche Parameter
für den Ratenkauf)
ratecount
totalamount
Pflicht
Format
+ (falls paymentType = 3)
+ (falls paymentType = 3)
N…2
N…10
Kommentar
Gewählte Anzahl Raten
+ Zinsaufschlag
+ Transaktionsgebühr
Hinweis: Diese zusätzlichen Parameter werden nur für die Zahlart „Ratenkauf“ ausgewertet. Der
übergebene Wert für den Parameter „paymentType“ muss in diesem Fall also „3“ sein. Andernfalls
werden die Daten ignoriert.4
Format
Kommentar
AN…200
Name der Firma
Vorgabe
Rechtsform der Firma
„gmbh“: GmbH
„ag“: AG
„misc“: Sonstige
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.
(Firmendaten)
name
legalForm
Pflicht
+ (falls customerGroup = „b“)
+ (falls customerGroup = „b“)
Optionale Liste
0..20 Bestellungen
(Bestellhistorie)
horderid
Pflicht
Format
Kommentar
+
AN…20
hdate
hamount
+
+
(YYYYMMDD hh:mm:ss)
N…7
hcurrency
+
hpaymenttype
+
Vorgabe
ISO 4217
Vorgabe
0: Lastschrift
1: Kreditkarte
2: Vorkasse
3: Nachnahme
4: Paypal
5: Sofortüberweisung/Giropay
Historische Bestellnummer
des Händlers
Bestelldatum
Gesamtpreis
10000)
Währung (z.B. „EUR“)
4
Zahlungsart:
- Lastschrift
- Kreditkarte
- Vorkasse
- Nachnahme
- Paypal
- Sofortüberwei-
Bitte beachten Sie für die Implementierung des Ratenkaufs auch das Dokument „Zusatzdokument zur Integration des Billpay-Ratenkaufs“
16
6: Rechnung
7: Billpay (Rechnung)
100: Other
hstatus
+
Vorgabe
0: Bezahlt
1: Offen
2: Mahnwesen
3: Inkasso
4: Überbezahlt
5: Unterbezahlt
6: Geplatzt
sung/Giropay
- Rechnung
- Billpay (Rechnung)
- Other
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 Einzelpostitionen mit den übergebenen aggregierten Gesamtwerten übereinstimmen. Folgende Bedingungen müssen gelten:
1) carttotalpricegross = Summe(articlequantity
- rebategross
X
articlepricegross) + shippingpricegross
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
status
Pflicht
-
bptid
+(falls status = „APPROVED“)
Parameter
(korrigierte
Addressdaten)
Pflicht
Format
Vorgabe
„APPROVED“/“DENIED“
AN...50
Format
Kommentar
Status der Identitäts- und
Bonitätsprüfung
BILLPAY-Transaktionsnummer
Kommentar
17
street
streetno
zip
city
country
AN…50
AN…15
AN…5
AN…50
Vorgabe
ISO3166
alpha-3
Korrigierte Straße
Korrigierte Hausnummer
Korrigierte Postleitzahl
Korrigierter Ort
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
= „0“)
= „0“)
= „0“)
= „0“)
= „0“)
AN…255
Kontoinhaber für die Forderung (i.d.R. „Billpay GmbH)
Billpay Kontonummer für die
Forderung
Billpay BLZ für die Forderung
AN…40
AN…16
AN…255
AN…255
Billpay Name der Bank für die
Forderung
Verwendungszweck
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.
18
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.
7.6.3.1 REQUEST „capture“
Parameter
bptid
carttotalgross
Pflicht
+
+
Format
N…12
N…7
currency
+
reference
+
Vorgabe
ISO 4217
AN…40
customerid
-
AN…20
Kommentar
BILLPAY Transaktionsnummer
100,00 Euro = 10000)
Bestellnummer beim Händler.
(Erlaubte Zeichen: 0-9, a-z, A-Z, .,-,_,/)
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
(approved)
account_holder
Pflicht
Format
Kommentar
+
AN…255
account_number
+
AN…40
bank_code
bank_name
+
+
AN…16
AN…255
invoice_reference
+
AN…255
Kontoinhaber für die Forderung
(i.d.R. „Billpay GmbH)
Billpay Kontonummer für die Forderung
Billpay Name der Bank für die Forderung
Verwendungszweck
19
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 / Layout der Endkundenrechnung
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 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
carttotalgross
Pflicht
+
Format
N…7
currency
+
reference
+
Vorgabe
ISO 4217
AN…40
delayindays
+
N...3
Kommentar
Aktueller Bruttowert der gesamten Bestellung (etwaige Teilstornierungen berücksichtigt)
10000)
Bestellnummer der Hauptbestellung beim Händler.
Anzahl Tage, um die sich das Zahlungsziels zusätzlich zu den 20/30 Tagen verschiebt
Es ist aktuell nur die Aktivierung der gesamten Bestellung möglich.
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.).
20
Parameter
account_holder
Pflicht
+
Format
AN…255
account_number
+
AN…40
bank_code
bank_name
+
+
AN…16
AN…255
invoice_reference
invoice_duedate
+
+
AN…255
N…8
activation_performed
+
Vorgabe
1: Ja
0: Nein
Kommentar
Kontoinhaber (i.d.R. „Billpay
GmbH“)
Kontonummer (variiert für jede Bestellung!)
Billpay Name der Bank für die Forderung
Verwendungszweck
Zahlungsziel des Kunden
(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!
Für die Gestaltung der Zahlungsinformationen dürfen ausschließlich die Texte der folgenden Abbildungen verwendet werden. Zusätzlich zu den Zahlungsinformationen muss auf der Rechnung das
Billpay-Logo abgebildet werden. Das skalierte Logo in unterschiedlichen Größen kann unter
http://www.billpay.de/billpay-logo herunterladen 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
21
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.
7.7.2 Vollstornierung
Ü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.2.1 REQUEST „cancel“
Parameter
reference
Pflicht
+
Format
AN…40
carttotalgross
+
N…7
currency
+
Vorgabe
ISO 4217
Kommentar
Bestellnummer des Händlers.
Aktueller Bruttowert der Bestellung (Etwaige Teilstornierungen berücksichtigt)
10000)
7.7.2.2 RESPONSE „cancel“
Es werden gegenüber den generellen Parametern keine zusätzlichen Parameter übergeben.
7.7.3 Teilstornierung/Teilretour
Über den „partialcancel“ Request kann eine Bestellung im Billpay-System nachträglich redziert 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. So bald ein
22
„partialcancel“ Request über die XML-Schnittstelle eingeht, informiert Billpay den Kunden umgehend
über die Anpassung des Forderungsbetrags.
7.7.3.1 REQUEST „partialcancel“
Parameter
reference
Pflicht
+
Format
AN…40
Kommentar
Bestellnummer des Händlers.
(Erlaubte Zeichen: 0-9, a-z, A-Z, .,,_,/)
Änderung des NettoRabattbetrages der Bestellung.
Positiver Wert bedeutet Verringerung des Rabattwertes.
100,00 Euro = 10000)
Änderung des BruttoRabattbetrages der Bestellung.
Positiver Wert bedeutet Verringerung des Rabattwertes.
100,00 Euro = 10000)
Reduzierung der NettoLiefergebühren.
100,00 Euro = 10000)
Reduzierung der BruttoLiefergebühren
100,00 Euro = 10000)
rebatedecrease
+
(-) N…7
rebatedecreasegross
+
(-) N…7
shippingdecrease
-
N...7
shippingdecreasegross
-
N...7
currency
+
Vorgabe
ISO 4217
Pflicht
Format
Kommentar
+
+
AN…20
N…7
Artikel-ID/Item-ID beim Händler
Anzahl der Artikel, die storniert
werden sollen
Optionale Liste
Parameter für 0..n Artikel
(Bestelldaten Artikel)
articleid
articlequantity
7.7.3.2 RESPONSE „partialcancel“
Es werden gegenüber den generellen Parametern keine zusätzlichen Parameter übergeben.
23
8 Clientseitige API
Billpay stellt für die in Abschnitt 7 beschriebene XML-Schnittstelle eine clientseitige API in verschiedenen Programmiersprachen zur Verfügung. Diese API vereinfacht die Integration der BillpayZahlungsarten in Ihren Online-Shop erheblich. Zu diesem Zweck realisiert die API eine Abstraktionsebene oberhalb der auf HTTP und XML basierenden Kommunikation zwischen dem Shop und der XMLSchnittstelle, so dass sich der Entwickler nicht um die Details der Kommunikation kümmern braucht.
Die nötigen Bibliotheken sowie ausführliche Programmbeispiele für die Verwendung der clientseitigen API können unter der folgenden URL heruntergeladen werden:
•
http://www.billpay.de/haendler/downloads
24
9
XML-Beispiele
<?xml version="1.0" encoding="UTF-8" ?>
<data api_version="1.4.0">
<default_params mid="2" pid="3"
bpsecure="0d48732f425b6df88c58244d6882369e" />
<locale country="DEU" currency="EUR" language="de" />
</data>
XML-Beispiel 1: moduleConfig-Request
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<data customer_message="" error_code="0" merchant_message="">
<minvalue directdebit="0" hirepurchase="10000" invoice="0"
invoicebusiness="0" />
<limit directdebitstatic="10000000" hirepurchasestatic="100000"
invoicebusinessstatic="10000000" invoicestatic="10000000"
static="10000000" />
<permissions active="1" directdebitallowed="1"
hirepurchaseallowed="1" invoiceallowed="1"
invoicebusinessallowed="1" />
</data>
XML-Beispiel 2: moduleConfig-Response
<data api_version="1.4.0" tcaccepted="1" paymenttype="1">
<customer_details customerid="123456" customertype="e"
salutation="Herr" title="Dr." firstName="Max"
lastName="Mustermann" street="Musterstraße" streetNo="23"
addressAddition="" zip="12345" city="Musterstadt"
country="DEU" email="[email protected]" phone="0302333459"
cellPhone="01775112389" birthday="19850911"
language="de" ip="85.214.7.22" customerGroup="p" />
<shipping_details useBillingAddress="1" salutation=""
title="" firstName="" lastName="" street="" streetNo=""
addressAddition="" zip="" city="" country="" phone=""
cellPhone="" />
<total shippingname="Express-Versand" shippingprice="500"
shippingpricegross="650" rebate="500" rebategross="595"
carttotalprice="1780" carttotalpricegross="2795" currency="EUR" />
<article_data>
<article articleid="article001" articlequantity="12"
articlename="Kaffetasse 08/15" articledescription="Eine
Kaffetasse aus Porzelan" articleprice="120"
articlepricegross="195" />
articlename="Kuchenteller 07-11"
articledescription="Kuchenteller - weiss" articleprice="85"
</article_data>
<order_history_data>
<order_history horderid="1233343321" hdate="20080101 10:23:30"
hamount="12300" hcurrency="EUR" hpaymenttype="4" hstatus="0" />
</order_history_data>
</data>
XML-Beispiel 3: preauthorize-Request für die Zahlart „Kauf auf Rechnung (B2C)“
25
language="de" ip="85.214.7.22" customerGroup="b" />
<shipping_details useBillingAddress="1" />
<company_details name="Billpay GmbH" legalForm="gmbh" />
<article_data>
</article_data>
</data>
XML-Beispiel 4: preauthorize-Request für die Zahlart „Kauf auf Rechnung (B2B)“
26
<bank_account accountholder="Max Mustermann" accountnumber="4973024088"
sortcode="10050000" />
<article_data>
</article_data>
</data>
XML-Beispiel 5: preauthorize-Request für die Zahlart „Kauf per Lastschrift“
<data api_version="1.4.0" tcaccepted="1" paymenttype="1"
capturerequestnecessary="0">
carttotalprice="1780" carttotalpricegross="2795" currency="EUR"
reference="ref1234567890" />
<article_data>
</article_data>
</data>
XML-Beispiel 6: preauthorize-Request für die Zahlart „Kauf auf Rechnung (B2C)“ (im Auto-Capture Modus)
27
<?xml version="1.0" encoding="UTF-8"?>
<data bptid="66ffe4d2-dc04-436d-8def-d057eb024154" customer_message=""
error_code="0" merchant_message="" status="APPROVED">
<corrected_address street="Musterstraße" streetNo="23" zip="12345"
city=" Musterstadt" country="DEU" />
</data>
XML-Beispiel 7: preauthorize-Response im Erfolgsfall ("Kauf auf Rechnung", kein Auto-Capture)
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<data bptid="53594569-b325-4a3f-8790-b6eddd09c4c2" customer_message=""
error_code="0" merchant_message="" status="APPROVED">
<corrected_address city="Teststadt" country="DEU" street="Musterstraße"
streetNo="23" zip="12345"></corrected_address>
<invoice_bank_account account_holder="Billpay GmbH"
account_number="4973034580" activation_performed=""
bank_code="10050000" bank_name="Berliner Sparkasse"
invoice_reference=" RG: Bestellnummer ">
</invoice_bank_account>
</data>
XML-Beispiel 8: preauthorize-Response im Erfolgsfall ("Kauf auf Rechnung", Auto-Capture)
<data customer_message="Fehler: Der Pflicht-Parameter [Rechnungsaddresse-Straße] wurde nicht übergeben." error_code="7"
merchant_message="Fehler: Der Pflicht-Parameter [Rechnungsaddresse-Straße] wurde nicht übergeben." />
XML-Beispiel 9: preauthorize-Response im Fehlerfall (die Straße wurde nicht übergeben)
<data customer_message="Bitte wählen Sie eine andere Zahlart. Leider
können wir Ihnen für diese Transaktion die ausgewählte Zahlart von Billpay nicht anbieten." error_code="32"
merchant_message="Bitte wählen Sie eine andere Zahlart. Der Kunde
wurde aufgrund fehlgeschlagener Identitäts- bzw. Bonitätsprüfung abgelehnt." status="DENIED" />
XML-Beispiel 10: preauthorize-Response im Fehlerfall (Kunde wird wg. fehlgeschlagener Identitätsoder Bonitätsprüfung abgelehnt)
28
<capture_params bptid="b0fa7ec2-ae19-49c1-8984-70001518e416"
carttotalgross="3390" currency="EUR"
reference="TA345345JK" customerid="123456" />
</data>
XML-Beispiel 11: capture-Request
account_number="4973024061" bank_code="10050000"
bank_name="Berliner Sparkasse" invoice_duedate=""
invoice_reference="RG: Bestellnummer" />
</data>
XML-Beispiel 12: capture-Response ("Kauf auf Rechnung B2C/B2B")
<invoice_params carttotalgross="3390" currency="EUR"
reference="TA345345JK" delayindays="0" />
</data>
XML-Beispiel 13: „invoiceCreated“-Request (Alle Zahlarten, Vollständige Aktivierung der Bestellung
mit einem Gesamtwert von 33,90€, die weiter oben mit dem preauthorize-Request initiiert wurde)
29
account_number="4973004818" bank_code="10050000"
bank_name="Berliner Sparkasse"
invoice_duedate="20100628" invoice_reference="TA345345JK"
activation_performed="1" />
</data>
XML-Beispiel 14: invoiceCreated-Response („Kauf auf Rechnung B2C/B2B“)
<cancel_params reference="TA345345JK" carttotalgross="3390"
currency="EUR" />
</data>
XML-Beispiel 15: cancel-Request (alle Zahlarten)
<cancel_params reference="TA345345JK" rebatedecrease="0"
rebatedecreasegross="0" shippingdecrease="0"
shippingdecreasegross="0" currency="EUR" />
<canceled_articles>
<article articleid="article001" articlequantity="1" />
<article articleid="article002" articlequantity="1" />
</canceled_articles>
</data>
XML-Beispiel 16: partialCancel-Request (alle Zahlarten)
30
10 Kontakt für Rückfragen
Bei technischen Fragen zur Schnittstelle wenden Sie sich bitte an:
Billpay GmbH
Saarbrücker Straße 21/22
D-10405 Berlin
Telefon:
+49 (0) 30 609893550
E-Mail:
[email protected]
31
11 Anhang
11.1 Erlaubte Werte für das Feld „salutation“
Das Feld „salutation“ bzw. „shipping_salutation“ wird von Billpay genutzt, um auf das Geschlecht des
anfragten Kunden zu schließen. Folgende Werte dürfen übergeben werden (Groß- und Kleinschreibung unerheblich):
Geschlecht „weiblich“:
-
frau
fräulein
fr
fr.
miss
ms
ms.
mrs
mrs.
signora
sig.ra
donna
la signora
madame
mme
mademoiselle
mlle
mle
Geschlecht „männlich“:
-
herr
hr
hr.
mister
mr
mr.
sir
signor
sig
sig.
gentleman
gentiluomo
padrone
monsieur
m.
m
32

XML-Schnittstelle für die Billpay

Transcrição

Documentos relacionados

+ Zahlungsgarantie + hohe Reichweite + einfache

mitglieds ntr g - FC Pommern Stralsund

Inhaltsverzeichnis

Einzugsermächtigung

Correct Invoice Sample

1. FC Grevenbroich Süd 1912/77 e.V. Abteilung 007 Kickboxen

Änderungsmeldung - Förderverein des Spielmannszuges

Ihre Berufsgenossenschaft Nahrungsmittel und Gastgewerbe

Förderverein TG Neureut, Tannenweg 7, 76149 Karlsruhe

sap invoice management by opentext vermessung