Version 2.1/ Stand 5/2009 ANBINDUNGSHANDBUCH
1 EINLEITUNG... 5 2 VARIANTEN DER VR-PAY VIRTUELL - ANBINDUNG... 8 ABLAUF EINER DIALOG- TRANSAKTION...9 ABLAUF EINER DIALOG- TRANSAKTION...9 2.1 ABLAUF EINER DIREKT- TRANSAKTION...10 3 SCHNITTSTELLEN-/EINGANGSPARAMETER IM VR-PAY VIRTUELL...11 3.1 SCHNITTSTELLE ZUM VR-PAY VIRTUELL...11 4 TRANSAKTIONSABLAUF AUF HTTP- BASIS (BEISPIELE)...13 4.1 HTTP - PROTOKOLL...13 4.2 TRANSAKTION ÜBER DEN SERVICE DIALOG...14 4.2.1 Dialog - Zahlung über Auswahlseite...14 4.2.2 Dialog - Zahlung über vorbestimmten Brand und Spracheinstellung...15 4.3 TRANSAKTION ÜBER SERVICE DIREKT...16 4.3.1 Direkt - Zahlung / EC-Karte Reservieren / weitere Verwendungszweckzeilen auf Kundenauszug...16 4.3.2 Direkt - Zahlung Kreditkarte Buchen...17 4.3.3 Direkt - Zahlung / Kreditkarte Kaufen / mit Warenkorb / mit ANTWGEHEIMNIS...17 4.3.4 Direkt - Zahlung Kreditkarte Gutschreiben...18 5 SCHNITTSTELLENPARAMETER...19 5.1 ALLE SCHNITTSTELLENPARAMETER FÜR DIALOG- UND DIREKT-TRANSAKTIONEN...19 5.2 SERVICE DIALOG...24 5.3 SERVICE DIREKT TRANSAKTIONEN...26 5.4 SERVICE DIREKT TRANSAKTION STORNOS...28 6 BENACHRICHTIGUNG AN DAS HÄNDLERSYSTEM...30 6.1 MÖGLICHE PARAMETER ZU EINER BENACHRICHTIGUNGSANTWORT...30 6.2 BEISPIEL ZU EINER BENACHRICHTIGUNGSANTWORT...32 7 FEHLERMELDUNGEN IM VR-PAY VIRTUELL...33 7.1 SYSTEMFEHLER...33 7.2 AUFLISTUNG DER SYSTEMFEHLER...33 7.3 TRANSAKTIONSFEHLER...35 7.4 AUFLISTUNG DER TRANSAKTIONSFEHLER...35 8 STATUSMODELL IN VR-PAY VIRTUELL...39 8.1 ZAHLUNGSZUSTÄNDE UND ZAHLUNGSÜBERGÄNGE...39 8.2 GUTSCHRIFTSZUSTÄNDE UND GUTSCHRIFTSÜBERGÄNGE...41 9 MÖGLICHE LAYOUT-ANPASSUNGEN DER BEZAHLSEITE...42 9.1 ORIGINALSICHTEN ZUM BEZAHLDIALOG...42 9.1.1 Dialog Auswahl- und Bezahlseite...42 9.1.2 Transaktionsstatus...43 9.1.3 Warenkorbdaten...44 9.1.4 Hilfe zu CVC2...44 9.2 BEZAHLDIALOG MIT DARSTELLUNG DER CSS-KLASSEN...45 9.2.1 Dialog Auswahl- und Bezahlseite...45 9.2.2 Transaktionsstatus...46 9.2.3 Warenkorbdaten...47 9.2.4 Hilfe zu CVC2...47 10 PROGRAMMIERBEISPIELE...48 10.1 PROGRAMMIERSPRACHE PERL...48 VR-Pay virtuell Anbindungshandbuch - 2 - Version 2.1
10.2 PROGRAMMIERSPRACHE PHP DIALOG-TRANSAKTION...50 10.3 PROGRAMMIERSPRACHE PHP DIREKT-TRANSAKTION KREDITKARTE...52 11 GLOSSAR...54 GELTUNGSBEREICH DES DOKUMENTES ÄNDERUNGSDIENST Die Ausführung der Änderungen erfolgt durch Austausch des gesamten Dokuments. Ältere Versionen verlieren mit dem Austausch ihre Gültigkeit und sind zu vernichten. ABLAGE Das Dokument ist unter folgendem Namen zu finden: B:\eco_pbr\doc\hb\benutzer\Anbindungshandbuch VR-Pay virtuell V2.1.doc. VERSIONSHISTORIE AKTUELL Das Dokument wird fortlaufend aktualisiert. Größere Änderungen an Inhalt und Umfang führen zu neuen Releasenummern, während sich textliche Überarbeitungen in neuen Levelnummern ausdrücken. Die folgende Liste gibt die Historie dieses Dokumentes wieder. Version Erstellt von: Datum: Geprüft von: Datum: Grund der Änderung 0.1 15.09.04 xgadgir Erstellung 0.2 16.09.04 xgadgir Allgemeine Erweiterungen 1.0 17.06.05 xgadfbi Diverse Korrekturen, finaler Status 1.01 01.07.05 xgadfbi PHP Beispiel eingefügt, Überarbeitung aufgrund Revisionsbericht von 06/2005 1.02 13.07.05 xgadfbi Parameter Sprache wird zurzeit nicht unterstützt. (Änderung Redirect) 1.03 14.07.05 xgadgir Absatz Transaktionen über den Service PayPage bzgl. Redirect angepaßt 1.04 18.07.05 xgadoel Verifiziert 1.05 08.09.05 xgadgir Parameter NACHRICHTNR aus Benachrichtigungsantwort entfernt 1.06 07.10.05 xgadgir Neues PHP-Beispiel-Skript 1.07 20.10.05 xgadgir Fehlermeldungen und RMSG hinzugefügt 1.08 08.11.05 xgadfbi Layoutanpassung der Paypage per CSS überarbeitet 1.09 29.12.05 xgadfbi Auflistung der Systemfehler 2.00 22.11.06 xgadfbi Service DIALOG ersetzt Service PAYPAGE VR-Pay virtuell Anbindungshandbuch - 3 - Version 2.1
Version Erstellt von: Datum: Geprüft von: Datum: Grund der Änderung 2.01 06.09.07 xgadgir Erweiterung der Schnittstelle um die Brands AMEX und JCB 2.02 25.10.07 xgadgir Original-Sichten zum Bezahldialog hinzugefügt 2.03 22.11.07 xgadgir Einleitung um Zugangsdaten, Benutzer etc. erweitert 2.04 18.12.07 xgadgir Bezeichnung PayPage gelöscht 2.05 17.01.08 xgadgir Allgemeine Information 2.06 06.02.08 xgadfbi Geänderter Aufruf von Funktion http_build_query 2.07 29.04.08 xgadgir Hinweis bzgl. giropay hinzugefügt 2.08 22.08.08 xgadgir Brandparameter um GIROPAY erweitert 2.09 21.11.08 xgadfbi Bezahlparameter Auswahl & Brand erweitert 2.1 20.04.09 - PITCP Änderung der Namen VR-Pay virtuell in VR-Pay virtuell Übernahme CardProcess VR-Pay virtuell Anbindungshandbuch - 4 - Version 2.1
1 Einleitung Das Online- Payment- System der CardProcess für den Vertrieb über die Volks- und Raiffeisenbanken (VR-Pay virtuell) bietet Händlern die Möglichkeit, Ihren Online-Shop einfach, bequem und schnell an ein sicheres Bezahlverfahren anzuschließen. Hierbei werden die eingereichten Zahlungsdaten (bei ELV sind es Kontonummer und Bankleitzahl, bei Kreditkarte sind es Kartennummer, Verfallsdatum und Sicherheitscode) auf Plausibilität geprüft. Sollte die Plausibilitätsprüfung positiv ausfallen, werden die ELV- Daten direkt in die Buchungssysteme geleitet, die Kreditkartendaten werden direkt an den Acquirer geleitet und dort entsprechend reserviert bzw. gebucht. Weiterhin erhält der Händler ein webbasiertes Verarbeitungstool, seine VR-Pay virtuell Händlerkasse, über die er nach Transaktionen recherchieren und diese Transaktionen buchen, gutschreiben bzw. stornieren kann. Ebenso gibt es für Händler mit Call-Center oder Händler, die kein Terminal aufstellen möchten die Möglichkeit, Transaktionen (Mail- Order / Telefon- Order) über ein Web-Interface, VR-Pay virtuell Terminal, zu erfassen. Bezahlverfahren, die vom Payment- System der Volks- und Raiffeisenbanken zurzeit angeboten werden, sind VISA Kreditkarte, Verified by VISA (nur über Variante Dialog siehe Kap.2), www.visa.de MasterCard Kreditkarte, MasterCard SecureCode (nur über Variante Dialog siehe Kap.2), www.mastercard.com/de American Express Kreditkarte, www.americanexpress.com/germany Diners, www.dinersclub.de JCB Kreditkarte per SSL, www.jcb-global.com/english/ Onlineüberweisung giropay, www.giropay.de (Wichtiger Hinweis: Nur über Variante Dialog siehe Kap.2 und nur mit der ZAHLART=KAUFEN siehe Kap. 4 möglich. Die Bezahlseite darf nicht in einem iframe dargestellt werden.) (E)lektronisches (L)astschrift (V)erfahren VR-Pay virtuell Anbindungshandbuch - 5 - Version 2.1
Voraussetzung für die Anbindung an VR-Pay virtuell mit einem Shopsystem: Händler verfügt über einen Online-Auftritt, in dem er Formulardaten über eine SSL- verschlüsselte Verbindung, mittels HTTP- Client, an das Payment- System leitet. Zur Anbindung werden keine weiteren Softwarekomponenten und kein Plug-In benötigt. Der Händler sollte aber Anpassungen im Shopsystem vornehmen können und somit über entsprechende Programmierkenntnisse wie z.b. Java, Perl, PHP etc. verfügen. Ist nach einer Transaktion eine zusätzliche Benachrichtigung (Notifikation) gewünscht, so muss der Händler über einen SSL- fähigen Webserver verfügen, der diese Nachricht entsprechend verarbeiten kann. Das SSL Zertifikat wird nicht auf Gültigkeit geprüft. Voraussetzung für Transaktionen über die VR-Pay virtuell Terminal: Browser mit Anbindung zum Internet, der eine SSL- gesicherte Verbindung zur VR-Pay virtuell Terminal aufbaut. (Empfohlene Browser: Internet Explorer 7.x, Netscape 7.x (Mozilla), Mozilla Firefox 2.x) Zugangsdaten: Ihre Institutskennung und Ihr Passwort erhalten Sie nach Vertragsabschluss von Ihrer Bank. Bitte beachten Sie, dass Ihrem Account die zwei Benutzer admin und sendpay zugeordnet sind, deren Passworte Sie umgehend ändern sollten. Zu diesem Zeitpunkt besitzen beide Benutzer noch das gleiche Passwort. Systembenutzer: admin : Der Benutzer admin ist für die Bereitstellung der Händlerkasse, des Transaktionsdatenexports, der Benutzerverwaltung, etc. zuständig. Über die Benutzerverwaltung kann der admin weitere Benutzer mit gleichen / eingeschränkten Rechten anlegen. Mit dem Benutzer sendpay können hingegen nur Transaktionen eingereicht werden. Dies geschieht über Basic-Authentication mittels Institutskennung und Passwort. Systeme: Testsystem: https://payinte.vr-epay.de/pbr/transaktion Mit Hilfe des Testsystems können Testtransaktionen über ein externes System ins VR-Pay virtuell-system geleitet werden. Diese Transaktionen werden weder verbucht noch erscheinen sie auf irgendeiner Abrechnung. Es sollten alle verfügbaren Zahlarten möglich sein, bis auf die Reservierung einer Kreditkarte und giropay. Livesystem: https://pay.vr-epay.de/pbr/transaktion Achtung: Es wird zum Vertrag immer nur der produktive Account angelegt und freigeschaltet. Sollte ein Testaccount zum Anbindungstest nötig sein, so sollte dies unter der Adresse vr-pay@cardprocess.de mitgeteilt werden. Der Testaccount wird dann umgehend angelegt und Sie werden hierzu benachrichtigt. Webinterface: Über das VR-Pay virtuell Webinterface erhalten Sie Zugriff auf die Händlerkasse, das virtuelle Terminal den Transaktionsdatenexport, die Benutzerverwaltung, etc. Sie erreichen das Webinterface über die Adresse https://pay.vr-epay.de/adm. VR-Pay virtuell Anbindungshandbuch - 6 - Version 2.1
Informationen: Informationen / Dokumentation zu VR-Pay virtuell erhalten Sie im Internet unter der Adresse www.vrepay.info. Weitere Fragen zu VR-Pay virtuell beantworten wir Ihnen gerne unter der E-Mail-Adresse vrpay@cardprocess.de. VR-Pay virtuell Anbindungshandbuch - 7 - Version 2.1
2 Varianten der VR-Pay virtuell - Anbindung Der Händler kann zwischen zwei verschiedenen Anbindungsverfahren wählen, zwischen denen er zu jeder Zeit wechseln kann, ohne das erneute Konfigurationseinstellungen im Payment-System notwendig werden. Allerdings möchten wir darauf hinweisen, dass bestimmte Bezahlverfahren (bspw. giropay) nur den Dialog- Transaktionen vorenthalten bleiben. (siehe Kap. 1). Anbindungsvarianten: Dialog- Transaktionen Händler leitet Redirect zur Bezahlseite vom Payment- System an Kunden. d.h. Die Bezahlseite kommt aus VR-Pay virtuell direkt zum Kunden. Somit kommt der Händler mit den Bezahldaten nicht in Berührung Direkt- Transaktionen Händler erfragt Bezahlparameter und leitet diese an das Payment- System. d.h. Die Bezahlseite kommt aus dem Händler-Shopsystem. Somit kommt der Händler mit den Bezahldaten in Berührung Wir empfehlen die Einreichung von Dialog-Transaktionen, da Sie bei der Einreichung von Direkt- Transaktionen möglicherweise seitens der Kreditkartengesellschaften einer Zertifizierungspflicht unterliegen. Nähere Informationen hierzu erhalten Sie bei Ihrem Vertragspartner, mit dem Sie den Kreditkartenakzeptanzvertrag geschlossen haben. VR-Pay virtuell Anbindungshandbuch - 8 - Version 2.1
Ablauf einer Dialog- Transaktion 10 Kunde 1 4 7 Händlerkasse 9 Händler 5 2 3 6 8 Paymentsystem Ablaufbeschreibung: 1. Kunde stellt Warenkorb zusammen und möchte bezahlen. 2. Händler schickt Bestellinformationen an VR-Pay virtuell. 3. Händler erhält vom Bezahlsystem einen Redirect. 4. Händler leitet Redirect zur Bezahlseite an den Kunden weiter. 5. Kunde erhält über den Redirect die Bezahlseite von VR-Pay virtuell. 6. Kunde bezahlt über Bezahlseite direkt in VR-Pay virtuell (ELV- oder Kreditkartendaten = Bezahlinformationen). 7. Kunde erhält Rückmeldung über Erfolg/Nichterfolg der Bezahlung vom Bezahlsystem 8. Händler erhält Notifikation über Status der Transaktion vom Bezahlsystem 9. Händler findet Transaktion in der VR-Pay virtuell Händlerkasse. Sollte die Transaktion reserviert worden sein, so stellt er nun die Waren zusammen und bucht den Betrag der bereitgestellten Waren in der VR-Pay virtuell Händlerkasse. 10. Händler liefert die Waren an den Kunden aus. VR-Pay virtuell Anbindungshandbuch - 9 - Version 2.1
2.1 Ablauf einer Direkt- Transaktion 7 Kunde 1 4 6 Händlerkasse Händler 2 3 5 Paymentsystem Ablaufbeschreibung: 1. Kunde stellt Warenkorb zusammen und bezahlt über die Bezahlseite des Händlersystems. 2. Händler schickt Bestell- und Bezahlinformationen an VR-Pay virtuell. 3. Händler erhält Status zur Transaktion (Erfolg/Nichterfolg) vom Bezahlsystem. 4. Kunde erhält Rückmeldung über Erfolg/Nichterfolg der Bezahlung vom Händlersystem. 5. Händler erhält optional Notifikation über den Status der Transaktion. 6. Händler findet Transaktion in der VR-Pay virtuell Händlerkasse. Sollte Transaktion reserviert worden sein, so stellt er nun die Waren zusammen und bucht den Betrag der bereitgestellten Waren in der VR-Pay virtuell Händlerkasse. 7. Händler liefert die Waren an den Kunden aus. VR-Pay virtuell Anbindungshandbuch - 10 - Version 2.1
3 Schnittstellen-/Eingangsparameter im VR-Pay virtuell 3.1 Schnittstelle zum VR-Pay virtuell HTTPS HTTPS HTTPS INTERNET INTERNET HTTPS HTTPS HTTPS VR-Pay virtuell System Dialog - Modul Direkt - Modul VR-Pay virtuell Terminal VR-Pay virtuell Händlerkasse Backendsystem VR-Pay virtuell Anbindungshandbuch - 11 - Version 2.1
Das VR-Pay virtuell System besitzt die Module Dialog und Direkt, um Transaktionen, die über ein Shopsystem kommen, abzuwickeln. Die VR-Pay virtuell Terminal dient Händlern dazu, Transaktionen, die per Mail oder Telefon (CallCenter) aufgenommen wurden, direkt über VR-Pay virtuell abzuwickeln. Um Transaktionen, die über ein Shopsystem oder über die VR-Pay virtuell Terminal eingeleitet wurden, weiterprozessieren zu können, erhält der Händler die VR-Pay virtuell Händlerkasse. Mit dieser Kasse ist er in der Lage, Transaktionen zu autorisieren, buchen, stornieren oder gutschreiben zu können bzw. Teilbuchungen auszulösen. VR-Pay virtuell Anbindungshandbuch - 12 - Version 2.1
4 Transaktionsablauf auf HTTP- Basis (Beispiele) Zu einer Transaktion müssen die Anmeldeparameter (Credentials: Instituts- ID / Passwort) mit an VR-Pay virtuell übertragen werden, um sich gegenüber dem Bezahlsystem zu authentifizieren. Die Daten werden SSL- verschlüsselt per HTTP- Protokoll an VR-Pay virtuell übertragen. 4.1 HTTP - Protokoll Die Datenübertragung zwischen dem Händlersystem und dem Bezahlsystem erfolgt URL- Encoded als HTTP- POST- Aufruf. Ein HTTP- Datenstrom besteht aus dem Protokoll-Kopf und den nachfolgenden Nutzdaten und wird durch ein doppeltes Zeilenendezeichen (New-Line <\n> in UNIX Systemen / Carriage Return, New- Line <\r><\n> in WINDOWS Systemen ) getrennt. Die HTTP- Anfrage hat folgendes Format: POST / <Ziel-URI> HTTP/1.0<\n> HOST: <Ziel-Host><\n> Content-type: <Typ><\n> Content-length: <Länge der Nutzdaten><\n> Authorization: <Schema> <Bereich> <\n> <\n> <Nutzdaten> <Ziel-URI> Pfad und Name des Prozesses, der auf dem Server gestartet werden soll. <Ziel-Host> Name des Rechners, an den die Anfrage gestellt wurde. <Typ> Format der übertragenen Daten. Für die Transaktionsabwicklung muß application/x-www-formurlencoded verwendet werden. <Länge der Nutzdaten> Enthält die Angabe zur Länge der Nutzdaten in Bytes <Schema> <Bereich> Das allgemeine Autorisierungsschema beim HTTP ist BASIC. Hier werden die Autorisierungsdaten im Format BENUTZERNAME:PASSWORT (bei uns Institut:Passwort) in base64 codiert. Mehr Informationen hierzu unter folgendem Link: http://httpd.apache.org/docs/howto/auth.html Die Antwort des Servers auf eine HTTP-POST-Anfrage enthält ebenfalls einen Protokollkopf und nachfolgend Nutzdaten wie bereits oben erläutert. VR-Pay virtuell Anbindungshandbuch - 13 - Version 2.1
4.2 Transaktion über den Service DIALOG Der Ablauf der Transaktion sieht folgendermaßen aus: 1. Übertragung der Credentials und der benötigten Schnittstellen-Parameter an VR-Pay virtuell 2. Bezahlsystem gibt Redirect zur Bezahlseite an Händlersystem zurück Im Fehlerfall wird Fehlermeldung an Händlersystem zurückgegeben 3. Händlersystem gibt Redirect an Kunden weiter 4. Kunde lädt über Redirect automatisch die Dialogseite 5. Kunde übergibt Zahlungsparameter (ELV-/Kreditkartendaten) direkt an VR-Pay virtuell 6. Zahlung wird über VR-Pay virtuell prozessiert und Kunde erhält Status 7. Händler erhält Benachrichtigung über Zahlungsausgang (Erfolg/Nichterfolg) 4.2.1 Dialog - Zahlung über Auswahlseite Wichtiger Hinweis: Die Bezahlmethode giropay steht nur bei der ZAHLART=KAUFEN zur Verfügung. Wird ZAHLART=RESERVIEREN verwendet, so wird die Bezahlmethode giropay ausgeblendet. 4.2.1.1 Anfrage Auswahl Reservieren POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 344 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB12345678&BETRAG=40&WAEHRUNG=EUR&ARTIKELANZ=1 &URLERFOLG=http://VR-EPay.de/erfolg.html&URLFEHLER=http://VR- EPay.de/fehler.html&URLANTWORT=https://payinte.VR-EPay.de/notify &URLABBRUCH=http://VR- EPay.de/abbruch.html&URLAGB=http://VR- EPay.de/agb.html&ZAHLART=RESERVIEREN&SERVICENAME=DIALOG&VERWENDANZ=0&AUSWAHL=J VR-Pay virtuell Anbindungshandbuch - 14 - Version 2.1
4.2.1.2 Antwort Auswahl Reservieren Als Antwort erhalten Sie einen Redirct, den Sie direkt an den Kunden weiterleiten, bzw. im Fehlerfall eine Fehlernachricht zur Ursache des Fehlers. 4.2.2 Dialog - Zahlung über vorbestimmten Brand und Spracheinstellung 4.2.2.1 Anfrage Kreditkarte Kaufen POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 362 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB12345678&BETRAG=40&WAEHRUNG=EUR&ARTIKELANZ=1 &URLERFOLG=http://VR-EPay.de/erfolg.html&URLFEHLER=http://VR-EPay.de/fehler.html& URLANTWORT=https://payinte.VR-EPay.de/notify &URLABBRUCH=http://VR-EPay.de/abbruch.html& URLAGB=http://VR-EPay.de/agb.html&BRAND=VISA&ZAHLART=KAUFEN& SERVICENAME=DIALOG&VERWENDANZ=0&AUSWAHL=N 4.2.2.2 Antwort Kreditkarte Kaufen Als Antwort erhalten Sie einen Redirct, den Sie direkt an den Kunden weiterleiten, bzw. im Fehlerfall eine Fehlernachricht zur Ursache des Fehlers. VR-Pay virtuell Anbindungshandbuch - 15 - Version 2.1
4.3 Transaktion über Service DIREKT Der Ablauf der Transaktion sieht folgendermaßen aus: 1. Übertragung der Credentials und der benötigten Schnittstellen-Parameter an VR-Pay virtuell 2. Zahlung wird über VR-Pay virtuell prozessiert 3. Bezahlsystem gibt Zahlungsausgang (Erfolg/Nichterfolg) an Händlersystem 4. Händlersystem gibt Kunden den Status zum Zahlungsausgang 5. Optional erfolgt eine Benachrichtigungsmeldung/Notifikation an das Händlersystem 4.3.1 Direkt - Zahlung / EC-Karte Reservieren / weitere Verwendungszweckzeilen auf Kundenauszug 4.3.1.1 Anfrage EC-Karte Reservieren POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 223 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB123456783&BETRAG=4799&WAEHRUNG=EUR&ARTIKELANZ =1&BRAND=ELV&ZAHLART=RESERVIEREN&SERVICENAME=DIREKT&BLZ=12345678&KONTONR=123456& VERWENDANZ=2&VERWENDUNG1=Fischer%20GmbH&VERWENDUNG2=Kd.-Nr.1234 4.3.1.2 Antwort EC-Karte Reservieren HTTP/1.0 200 OK Content-type: text/html Content-length: 177 ZEITPUNKT=2005-04-06+12%3A32%3A24.000000&STATUS=RESERVIERT& RMSG=Transaktion+erfolgreich&REFERENZNR=AB123456783&HAENDLERNR=0000100001&TSAID=455C21 C9&ZAHLART=RESERVIEREN&BETRAG=40 VR-Pay virtuell Anbindungshandbuch - 16 - Version 2.1
4.3.2 Direkt - Zahlung Kreditkarte Buchen 4.3.2.1 Anfrage Kreditkarte Buchen POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 116 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB12345678&BETRAG=40&WAEHRUNG=EUR& ZAHLART=BUCHEN&SERVICENAME=DIREKT&TSAID=5BC2D3FC 4.3.2.2 Antwort Kreditkarte Buchen HTTP/1.0 200 OK Content-type: text/html Content-length: 168 RMSG=Transaktion+erfolgreich&TSAID=094F5167&BETRAG=40&REFERENZNR=AB12345678&ZAHLART=BU CHEN&HAENDLERNR=0000100001&STATUS=GEBUCHT&ZEITPUNKT=2005-04-07+14%3A50%3A34.000000 4.3.3 Direkt - Zahlung / Kreditkarte Kaufen / mit Warenkorb / mit ANTWGEHEIMNIS 4.3.3.1 Anfrage Kreditkarte Kaufen POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 394 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB12345678&BETRAG=4500&WAEHRUNG=EUR&ARTIKELANZ= 2&ARTIKELNR1=1234&ARTIKELBEZ1=Internethandbuch&ANZAHL1=1&EINZELPREIS1=2000&ARTIKELNR2= 1235&ARTIKELBEZ2=Ordner%20in%20allen%20Farben&ANZAHL2=5& EINZELPREIS2=500&BRAND=VISA&ZAHLART=KAUFEN&SERVICENAME=DIREKT&KARTENNR=12345678901 2345&GUELTIGKEITSMONAT=08&GUELTIGKEITSJAHR=05&CVC2=1234& VERWENDANZ=0&ANTWGEHEIMNIS=geheim 4.3.3.2 Antwort Kreditkarte Kaufen HTTP/1.0 200 OK Content-type: text/html Content-length: 189 STATUS=GEKAUFT&HAENDLERNR=0000100001&ZAHLART=KAUFEN&TSAID=03938001&RMSG=Transaktio n+erfolgreich&zeitpunkt=2005-04-13+10%3a32%3a52.000000&betrag=40& REFERENZNR=AB12345678&ANTWGEHEIMNIS=geheim VR-Pay virtuell Anbindungshandbuch - 17 - Version 2.1
4.3.4 Direkt - Zahlung Kreditkarte Gutschreiben 4.3.4.1 Anfrage Kreditkarte Gutschreiben POST /pbr/transaktion HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 109 Authorization: Basic d2vibwfzdgvyonpycw1hnhy= HAENDLERNR=0000100001&REFERENZNR=AB12345678&BETRAG=4799&WAEHRUNG=EUR& ZAHLART=GUTSCHREIBEN&SERVICENAME=DIREKT 4.3.4.2 Antwort Kreditkarte Gutschreiben HTTP/1.0 200 OK Content-type: text/html Content-length: 181 STATUS=GUTGESCHRIEBEN&HAENDLERNR=0000100001&ZAHLART=GUTSCHREIBEN&TSAID=03931201&R MSG=Transaktion+erfolgreich&ZEITPUNKT=2005-04-13+10%3A42%3A52.000000& BETRAG=20&REFERENZNR=AB12345678 VR-Pay virtuell Anbindungshandbuch - 18 - Version 2.1
5 Schnittstellenparameter 5.1 Alle Schnittstellenparameter für Dialog- und Direkt-Transaktionen Die Anmeldeparameter ( credential s ) dienen zur Anmeldung an VR-Pay virtuell. Im Falle eines einzelnen Händlers sind die User- ID und die HAENDLERNR identisch, bei Mehrfachanbindungen unterscheiden sich die beiden Parameter. Anmelde-Parameter UserId Passwort Beschreibung Wird vom Paymentbetreiber zugewiesen. Wird vom Paymentbetreiber mitgeteilt und kann über den Händlerzugang online geändert werden. POST-Parameter Format Gültige Werte Beschreibung Allgemeine Parameter HAENDLERNR C 10 Wird vom Paymentbetreiber zugewiesen. TSATYP C ECOM MOTO - ecommerce Transaktionen (über Ihre Shopanbindung) - Mail-Order / Telefon-Order (über VR-Pay virtuell Terminal) Bestelldaten REFERENZNR C 4-20 0-9A-Za-z Leerzeichen $%*+,-./ Bestell- / Zuordnungsnummer zu einer Bestellung im Shop. Diese Nummer erscheint bei Bezahlart ELV auf dem Kontoauszug des Kunden. Bei Kreditkartentransaktionen ist dies vom Abrechnungssystem Ihres Acquirers abhängig. BETRAG INT 0-9 Betrag zur jeweiligen Transaktion in der kleinsten Einheit. Bsp.: 3,59 EUR werden als 359 übermittelt. WAEHRUNG C EUR Währungskennzeichen INFOTEXT C 1- Informationstext zur Bestellung. 1024 ARTIKELANZ INT 1-3 Anzahl der unterschiedlichen Bestellpositionen/Artikel. Warenkorb ARTIKELNR... C 1-16 Artikelnummer eines Artikels, welcher im Warenkorb abgelegt ist. Die Punkte (...) hinter dem Parameternamen ARTIKELNR stehen für die Position des Artikels im Warenkorb. ARTIKELBEZ... C 1-128 Artikelbezeichnung eines Artikels, welcher im Warenkorb abgelegt ist. Die Punkte (...) hinter dem Parameternamen ARTIKELBEZ stehen für die Position des Artikels im Warenkorb. ANZAHL... INT 1-10 0-9 Anzahl/Menge eines Artikels, welcher im Warenkorb abgelegt ist. Die Punkte (...) VR-Pay virtuell Anbindungshandbuch - 19 - Version 2.1
POST-Parameter Format Gültige Werte Beschreibung hinter dem Parameternamen ANZAHL stehen für die Position des Artikels im Warenkorb. EINZELPREIS... INT 1-12 0-9 Einzelpreis eines Artikels, welcher im Warenkorb abgelegt ist. Die Punkte (...) hinter dem Parameternamen EINZELPREIS stehen für die Position des Artikels im Warenkorb. URLs URLERFOLG C 3-254 0-9A-Za-zÄÖÜäöü URL, die nach erfolgreicher Annahme der Zahlung aufgerufen wird.!#$%&*+-./:?^_~ URLFEHLER C 3-254 0-9A-Za-zÄÖÜäöü URL, die nach fehlgeschlagener Zahlung aufgerufen wird.!#$%&*+-./:?^_~ URLANTWORT C 3-254 0-9A-Za-zÄÖÜäöü URL, an die das Benachrichtigungsprogramm seinen HTTPS-Request sendet.!#$%&*+-./:?^_~ URLABBRUCH C 3-254 0-9A-Za-zÄÖÜäöü!#$%&*+-./:?^_~ URL, die nach abgebrochener Zahlung aufgerufen wird. Hiernach ist der Einstieg in den Warenkorb sinnvoll. URLAGB C 3-254 0-9A-Za-zÄÖÜäöü URL, die die AGB s des Händlers anzeigt.!#$%&*+-./:?^_~ URLCVC C 3-254 0-9A-Za-zÄÖÜäöü!#$%&*+-./:?^_~ URL, die Informationen zum CVC2/CAVV Feld bei Kreditkartenzahlungen liefert. Benachrichtigung ANTWGEHEIMNIS C 1-32 Ein Geheimnis, das der Händler zu Beginn einer Transaktion übergibt, welches Ihm bei der Benachrichtigung wieder übermittelt wird. Eindeutiges Kennzeichen, welches nur der Payment-Betreiber und der Händler kennen, um für den Händler sicherzustellen, das die Benachrichtigungsmeldung vom Payment-Betreiber gekommen ist. BENACHRPROF C BSG ZHL (Default) KEI ALL Transaktion ZAHLART C RESERVIEREN - Bei vollständigen Bestelldaten benachrichtigen. Zahlung noch nicht durchgeführt. - Nach durchgeführter Zahltransaktion (Autorisierung/Kauf) benachrichtigen. - Keine Transaktion benachrichtigen. - Alle Transaktionen (Bestellung, Zahlung, Gutschrift) benachrichtigen. Zusätzlich zur Zahlung auch alle Aktionen aus der VR-Pay virtuell Händlerkasse. Die Zahlart gibt an, um welche Art von Transaktion es sich handelt. Zu Beginn einer Transaktion wird zwischen Zahlart Reservieren und Kauf unterschieden. Anschließend kann eine Reservierung gebucht oder es können Stornierungen bzw. Gutschriften erfolgen. (siehe auch Statusmodell VR-Pay virtuell) VR-Pay virtuell Anbindungshandbuch - 20 - Version 2.1
POST-Parameter Format Gültige Werte Beschreibung STRESERVIEREN BUCHEN STBUCHEN KAUFEN STKAUFEN GUTSCHREIBEN STGUTSCHREIBEN Betrag wird reserviert Storno der Reservierung Buchung von reservierten Beträgen Storno einer Buchung Reservieren und buchen in einem Vorgang Storno eines Kaufs Gutschrift des Gesamtbetrages oder eines Teilbetrages SERVICENAME C DIALOG DIREKT Storno einer Gutschrift Dem Kunden wird eine Bezahlseite zur Transaktionsabwicklung präsentiert. Nach Durchführung des Bezahldialoges erhalten der Kunde und der Händler einen Status zur Transaktion. Der Händler kommt nicht in den Besitz der Bezahldaten. Händler erfragt Bezahldaten vom Kunden und führt Transaktion über VR-Pay virtuell durch. Anschließend informiert er den Kunden über den Status der Transaktion. Händler ist im Besitz der Bezahldaten. ELV BLZ INT 8 0-9 Bankleitzahl des Kunden; benötigt für Zahlart ELV. KONTONR INT 1-10 0-9 Kontonummer des Kunden; benötigt für Zahlart ELV. VERWENDANZ INT 1 Anzahl der übermittelten Verwendungszweckzeilen, die bei einer ELV- Zahlung dem Kunden auf dem Kontoauszug angezeigt werden. Zur Zeit können nur max. 2 Verwendungszweckzeilen frei vom Händler übergeben werden. VERWENDUNG... C 1-25 0-9A-Za-zäöüÄÖÜß Leerzeichen $%*+,-./ Kreditkarte KARTENNR INT 1-19 0-9 Kreditkartennummer des Kunden. Verwendungszweckzeile, die bei ELV-Transaktionen beim Kunden auf dem Kontoauszug erscheint. Die Punkte (...) hinter dem Parameternamen VERWENDUNG gibt an, um welche frei übergebene Verwendungszweckzeile es sich handelt. Kontoauszug des Kunden: 1. Pos - Referenz-Nr. (aus Shopsystem übergeben oder an der IDK eingegeben) 2. Pos - im Paymentsystem vordefinierter Text pro Händler (z.b. Händlername) 3. Pos - vom Shop übergebene zusätzliche Zeile Parameter VERWENDUNG1 4. Pos - vom Shop übergebene zusätzliche Zeile Parameter VERWENDUNG2 5. Pos - im Paymentsystem vordefinierter Text pro Terminal (z.b. Vielen Dank) Hinweis: Die maximale Anzahl Verwendungszweckzeilen kann durch das verarbeitende Bankinstitut beschränkt werden. VR-Pay virtuell Anbindungshandbuch - 21 - Version 2.1
POST-Parameter Format Gültige Werte Beschreibung GUELTIGKEITSMONAT INT 2 01,02,,12 Gültigkeitsmonat der Kreditkarte, in dem die Kreditkarte ihre Gültigkeit verliert. GUELTIGKEITSJAHR INT 2 00,01,02,,99 Gültigkeitsjahr der Kreditkarte, in dem die Kreditkarte ihre Gültigkeit verliert. CVC2 INT 3-4 0-9 CVC2/CAVV- Feld, welches auf der Kreditkarte aufgedruckt ist. Es ist ein zusätzliches Sicherheitsmerkmal der Kreditkarte. Service DIALOG SPRACHE C DE Dies ist die Sprache, in der der Bezahldialog dem Kunden präsentiert wird. EN AUSWAHL C J BRAND C N Dieser Parameter gibt die Möglichkeit, dem Kunden über die Bezahlseite alle verfügbaren Zahlungsmethoden oder eine Auswahl anzubieten (siehe auch Parameter BRAND ) oder nur explizit eine einzige (bei N ). Wurde ein N eingetragen, so wird dem Kunden die Bezahlmethode angezeigt, die der Händler als Pflichtparameter BRAND mit übergeben hat. Mit Hilfe dieses Parameters können die verfügbaren Bezahlmethoden innerhalb der Bezahlseite beeinflusst werden. & AUSWAHL= J & AUSWAHL= N ELV VISA ECMC DINERS AMEX JCB GIROPAY Trenner ist ; Bei Auswahl = J kann eine Liste von Brands übergeben werden (bspw.: VISA;ECMC;ELV) falls Parameter BRAND fehlt werden alle verfügbaren Bezahlmethoden angezeigt. Bei Auswahl = N wird nur ein Brand verlangt (bspw. GIROPAY) dieser Parameter ist dann Pflicht! Folgende Methoden stehen zur Verfügung: Elektronisches Lastschriftverfahren Kreditkarte Visa Kreditkarte Mastercard Kreditkarte Diners Kreditkarte AMEX Kreditkarte JCB Onlineüberweisung giropay Semikolon VR-Pay virtuell Anbindungshandbuch - 22 - Version 2.1
Service DIREKT BRAND C ELV VISA ECMC DINERS AMEX JCB Bestimmt die gewünschte Bezahlmethode. Folgende Methoden stehen zur Verfügung: Elektronisches Lastschriftverfahren Kreditkarte Visa Kreditkarte Mastercard Kreditkarte Diners Kreditkarte AMEX Kreditkarte JCB TSAID C 1-32 Transaktions- ID, die zu einer durchgeführten Zahlung oder Gutschrift von VR- Pay virtuell zurückgegeben wurde, um die Transaktion weiter prozessieren zu können. (ohne Händlerkassenfunktionalität muss dieser Wert daher im Shopsystem abgespeichert werden.) (bspw. Autorisierung danach buchen, Kauf danach Storno Kauf, etc. über Ihr Shopinterface) VR-Pay virtuell Anbindungshandbuch - 23 - Version 2.1
5.2 Service DIALOG Parameter name DB-Typ Beschreibung / Ausprägung SERVICE DIALOG ELV Kauf Kreditkarte Kauf ELV Reservierg Kreditkarte Reservierg Auswahl Kauf Auswahl Reservierg O O O O O O HAENDLERNR C10 Vertragspartner P P P P P P TSATYP C Transaktionstyp: ECOM/MOTO O O O O O O REFERENZNR C 4-20 Eindeutige Bestellnummer P P P P P P BETRAG INT Gesamtbetrag kl. Einheit P P P P P P WAEHRUNG C Währungscode EUR P P P P P P INFOTEXT C 1-1024 Infotext VR-Pay virtuell Händlerkasse ARTIKELANZ INT 1-3 Anzahl unterschiedlicher Artikel P P P P P P ARTIKELNR... C 1-16 Artikelnummer O O O O O O ARTIKELBEZ... C 1-128 Artikelbezeichnung O O O O O O ANZAHL... INT 1-10 Artikelanzahl O O O O O O EINZELPREIS... INT 1-12 Einzelpreis O O O O O O URLERFOLG C 3-254 URL nach Zahlungserfolg P P P P P P URLFEHLER C 3-254 URL nach Zahlungsmisserfolg P P P P P P URLANTWORT C 3-254 URL für Notifikation P P P P P P URLABBRUCH C 3-254 URL nach Zahlungsabbruch P P P P P P URLAGB C 3-254 URL für AGB s P P P P P P URLCVC C 3-254 Hilfe zu CVC2 O O O O O O ANTWGEHEIMNIS C 1-32 Notifikationsgeheimnis O O O O O O BENACHRPROF C BSG/ZHL/KEI/ALL O O O O O O ZAHLART C RESERVIERUNG/KAUF P P P P P P SERVICENAME C DIALOG P P P P P P BLZ C 8 Bankleitzahl --- --- --- --- --- --- KONTONR C 1-10 Kontonummer --- --- --- --- --- --- VERWENDANZ INT 1 Anzahl Verwendungszeilen P P P P P P VERWENDUNG... C 1-25 Verwendungszweck O O O O O O VR-Pay virtuell Anbindungshandbuch - 24 - Version 2.1
Parameter name DB-Typ Beschreibung / Ausprägung SERVICE DIALOG ELV Kauf Kreditkarte Kauf ELV Reservierg Kreditkarte Reservierg Auswahl Kauf Auswahl Reservierg KARTENNR C 1-19 Kreditkartennummer --- --- --- --- --- --- GUELTIGKEITSMONAT C 2 Karte ist gültig bis Monat --- --- --- --- --- --- GUELTIGKEITSJAHR C 2 Karte gültig bis Jahr --- --- --- --- --- --- CVC2 C 3-4 CVC2-Wert zur Kreditkarte --- --- --- --- --- --- SPRACHE C Sprachkennzeichen DE / EN O O O O O O AUSWAHL C Brandauswahl J / N J J J/N J/N J/N J/N BRAND C ELV;VISA; siehe AUSWAHL O O O/P O/P O/P O/P TSAID C 1-32 Transaktions- ID --- --- --- --- --- --- INT: Integer C: Character P: Pflichtfeld O: Optional N/U: Nicht unterstützt J: Ja N: Nein VR-Pay virtuell Anbindungshandbuch - 25 - Version 2.1
5.3 Service Direkt Transaktionen Parameter name DB-Typ Beschreibung / Ausprägung SERVICE DIREKT Kreditkarte Gutschrift ec-karte Kauf Kreditkarte Kauf ec-karte Buchung Kreditkarte Buchung ec-karte Reservierg Kreditkarte Reservierg HAENDLERNR C10 Vertragspartner P P P P P P P TSATYP C ECOM/MOTO O O --- --- O O --- REFERENZNR C 4-20 Eindeutige Bestellnummer P P P P P P P BETRAG INT Gesamtbetrag kl. Einheit P P P P P P P WAEHRUNG C Währungscode EUR P P P P P P P INFOTEXT C 1-1024 Infotext in VR-Pay virtuell Händlerkasse O O --- --- O O --- ARTIKELANZ INT 1-3 Anzahl unterschiedlicher P P --- --- P P --- Artikel ARTIKELNR... C 1-16 Artikelnummer O O --- --- O O --- ARTIKELBEZ... C 1-128 Artikelbezeichnung O O --- --- O O --- ANZAHL... INT 1- Artikelanzahl O O --- --- O O --- 10 EINZELPREIS... INT 1- Einzelpreis O O --- --- O O --- 12 URLERFOLG C 3-254 URL nach Zahlungserfolg --- --- --- --- --- --- --- URLFEHLER C 3-254 URL nach --- --- --- --- --- --- --- Zahlungsmisserfolg URLANTWORT C 3-254 URL für Notifikation O O --- --- O O --- URLABBRUCH C 3-254 URL nach --- --- --- --- --- --- --- Zahlungsabbruch URLAGB C 3-254 URL für AGB s --- --- --- --- --- --- --- URLCVC C 3-254 Hilfe zu CVC2 --- --- --- --- --- --- --- ANTWGEHEIMNIS C 1-32 Notifikationsgeheimnis O O --- --- O O --- BENACHRPROF C BSG/ZHL/KEI/ALL O O --- --- O O --- VR-Pay virtuell Anbindungshandbuch - 26 - Version 2.1
Parameter name DB-Typ Beschreibung / Ausprägung SERVICE DIREKT Kreditkarte Gutschrift ec-karte Kauf Kreditkarte Kauf ec-karte Buchung Kreditkarte Buchung ec-karte Reservierg Kreditkarte Reservierg ZAHLART C RESERVIEREN/BUCHEN/ P P P P P P P KAUFEN/GUTSCHREIBEN SERVICENAME C DIREKT P P P P P P P BLZ C 8 Bankleitzahl --- P --- --- --- P --- KONTONR C 1-10 Kontonummer --- P --- --- --- P --- VERWENDANZ INT 1 Anzahl --- P --- --- --- P --- Verwendungszeilen VERWENDUNG... C 1-25 Verwendungszweck --- O --- --- --- O --- KARTENNR C 1-19 Kreditkartennummer P --- --- --- P --- --- GUELTIGKEITSMONAT C 2 Karte ist gültig bis Monat P --- --- --- P --- --- GUELTIGKEITSJAHR C 2 Karte gültig bis Jahr P --- --- --- P --- --- CVC2 C 3-4 CVC2-Wert zur Kreditkarte O --- --- --- O --- --- SPRACHE C Sprachkennzeichen DE / --- --- --- --- --- --- --- EN AUSWAHL C Brandauswahl J / N --- --- --- --- --- --- --- BRAND C ELV/VISA/GIROPAY P P --- --- P P --- TSAID C 1-32 Transaktions- ID --- --- P P --- --- --- INT: Integer C: Character P: Pflichtfeld O: Optional N/U: Nicht unterstützt J: Ja N: Nein VR-Pay virtuell Anbindungshandbuch - 27 - Version 2.1
5.4 Service Direkt Transaktion Stornos Parametername DB- Typ Beschreibung / Ausprägung SERVICE DIREKT ec-karte Gutschrift Storno Kreditkarte Gutschrift Storno ec-karte Kauf Storno Kreditkarte Kauf Storno ec-karte Buchung Storno Kreditkarte Buchung Storno ec-karte Reservierg Storno Kreditkarte Reservierg Storno HAENDLERNR C10 Vertragspartner P P P P P P P P TSATYP C ECOM/MOTO --- --- --- --- --- --- --- --- REFERENZNR C 4-20 Eindeutige Bestellnummer P P P P P P P P BETRAG INT Gesamtbetrag kl. Einheit P P P P P P P P WAEHRUNG C Währungscode EUR P P P P P P P P INFOTEXT C 1- Infotext in --- --- --- --- --- --- --- --- 1024 VR-Pay virtuell Händlerkasse ARTIKELANZ INT 1-3 Anzahl unterschiedlicher Artikel --- --- --- --- --- --- --- --- ARTIKELNR... C 1-16 Artikelnummer --- --- --- --- --- --- --- --- ARTIKELBEZ... C 1- Artikelbezeichnung --- --- --- --- --- --- --- --- 128 ANZAHL... INT 1- Artikelanzahl --- --- --- --- --- --- --- --- 10 EINZELPREIS... INT 1- Einzelpreis --- --- --- --- --- --- --- --- 12 URLERFOLG C 3- URL nach Zahlungserfolg --- --- --- --- --- --- --- --- 254 URLFEHLER C 3- URL nach Zahlungsmisserfolg --- --- --- --- --- --- --- --- 254 URLANTWORT C 3- URL für Notifikation --- --- --- --- --- --- --- --- 254 URLABBRUCH C 3- URL nach Zahlungsabbruch --- --- --- --- --- --- --- --- 254 URLAGB C 3- URL für AGB s --- --- --- --- --- --- --- --- 254 URLCVC C 3-254 Hilfe zu CVC2 --- --- --- --- --- --- --- --- VR-Pay virtuell Anbindungshandbuch - 28 - Version 2.1
Parametername DB- Typ Beschreibung / Ausprägung SERVICE DIREKT ec-karte Gutschrift Storno Kreditkarte Gutschrift Storno ec-karte Kauf Storno Kreditkarte Kauf Storno ec-karte Buchung Storno Kreditkarte Buchung Storno ec-karte Reservierg Storno Kreditkarte Reservierg Storno ANTWGEHEIMNIS C 1-32 Notifikationsgeheimnis --- --- --- --- --- --- --- --- BENACHRPROF C BSG/ZHL/KEI/ALL --- --- --- --- --- --- --- --- ZAHLART C STRESERVIEREN/STBUCHEN/ P P P P P P P P STKAUFEN/STGUTSCHREIBEN SERVICENAME C DIREKT P P P P P P P P BLZ C 8 Bankleitzahl --- --- --- --- --- --- --- --- KONTONR C 1-10 Kontonummer --- --- --- --- --- --- --- --- VERWENDANZ INT 1 Anzahl Verwendungszeilen --- --- --- --- --- --- --- --- VERWENDUNG... C 1-25 Verwendungszweck --- --- --- --- --- --- --- --- KARTENNR C 1-19 Kreditkartennummer --- --- --- --- --- --- --- --- GUELTIGKEITSMONAT C 2 Karte ist gültig bis Monat --- --- --- --- --- --- --- --- GUELTIGKEITSJAHR C 2 Karte gültig bis Jahr --- --- --- --- --- --- --- --- CVC2 C 3-4 CVC2-Wert zur Kreditkarte --- --- --- --- --- --- --- --- SPRACHE C Sprachkennzeichen DE / EN --- --- --- --- --- --- --- --- AUSWAHL C Brandauswahl J / N --- --- --- --- --- --- --- --- BRAND C ELV/VISA/ECMC/DINERS --- --- --- --- --- --- --- --- TSAID C 1-32 Transaktions- ID P P P P P P P P INT: Integer C: Character P: Pflichtfeld O: Optional N/U: Nicht unterstützt J: Ja N: Nein VR-Pay virtuell Anbindungshandbuch - 29 - Version 2.1
6 Benachrichtigung an das Händlersystem Wurde eine Transaktion über den Service Dialog in das Payment- System gegeben, so benötigt der Händler eine Rückmeldung zum Status der Transaktion. Die möglichen Stati zu einem Bezahlvorgang sind unter dem Punkt Statusmodell VR-Pay virtuell erläutert. Wichtig: Es sollte beachtet werden, dass es sich bei der Zieladresse für die Benachrichtigung, der URLANTWORT, um eine SSL- verschlüsselte Verbindung handelt, die über den Port 443 abgewickelt wird. Es sollten nur Anfragen von der VR-Pay virtuell IP- Adresse auf die URLANTWORT zugelassen werden (sichere Verbindung durch Firewall). 6.1 Mögliche Parameter zu einer Benachrichtigungsantwort POST-Parameter Mögliche Werte Beschreibung HAENDLERNR Wird vom Paymentbetreiber zugewiesen. REFERENZNR 0-9A-Za-z Leerzeichen $%*+,-./ Bestell- / Zuordnungsnummer zu einer Bestellung im Shop. Diese Nummer erscheint bei ELV beim Kunden auf dem Kontoauszug. BETRAG 0-9 Betrag zur jeweiligen Transaktion in der kleinsten ZAHLART STATUS RESERVIEREN STRESERVIEREN BUCHEN STBUCHEN KAUFEN STKAUFEN GUTSCHREIBEN STGUTSCHREIBEN RESERVIERT GEBUCHT GEKAUFT GUTGESCHRIEBEN STORNIERT ABGELEHNT Einheit. 3,59 Euro werden als 359 übermittelt. Die Zahlart gibt an, um welche Art von Transaktion es sich handelt. Zu Beginn einer Transaktion wird zwischen dem Reservieren und dem Kauf unterschieden. Anschließend kann eine Reservierung gebucht oder es können Stornierungen bzw. Gutschriften erfolgen. Nach erfolgreicher Reservierung Nach erfolgreicher Buchung Nach erfolgreichem Kauf Nach erfolgreicher Gutschrift Nach erfolgreicher Stornierung Von VR-Pay virtuell oder Acquirer abgelehnt Fehlerfall (keine Antwort von Endsystemen, etc.) IN BEARBEITUNG RMSG siehe Kapitel 7.3 siehe Kapitel 7.3 Auflistung der Transaktionsfehler Beispielantworten: Transaktion erfolgreich Karte nicht zugelassen ZEITPUNKT Timestamp Zeitpunkt der Transaktion. z.b. 2004-10-14+10%3A43%3A32.000000 ANTWGEHEIMNIS C1-32 Ein Geheimnis, das der Händler zu Beginn einer Transaktion übergibt, welches Ihm bei der Benachrichtigung wieder mit übergeben wird. Eindeutiges Kennzeichen, welches nur der Payment-Betreiber und der Händler kennen, um für den Händler sicherzustellen, das die Benachrichtigungsmeldung vom Payment- Betreiber gekommen ist. VR-Pay virtuell Anbindungshandbuch - 30 - Version 2.1
POST-Parameter Mögliche Werte Beschreibung TSAID C1-32 Transaktions- ID, die zu einer durchgeführten Zahlung oder Gutschrift von VR-Pay virtuell zurückgegeben wird, um die Transaktion weiter prozessieren zu können. (Autorisierung buchen, Kauf stornieren, etc.) VR-Pay virtuell Anbindungshandbuch - 31 - Version 2.1
6.2 Beispiel zu einer Benachrichtigungsantwort Anfragenachricht von VR-Pay virtuell an das Händlersystem: Transaktion RESERVIEREN: Erfolgreich POST /notify HTTP/1.0 HOST: pay01.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 186 BETRAG=500&STATUS=RESERVIERT&TSAID=416FC67A&REFERENZNR=20041015144532%2F2&HAEN DLERNR=0000100001&ZAHLART=RESERVIEREN&ZEITPUNKT=2004-10-15+14%3A45%3A45.000000& RMSG=Transaktion+erfolgreich Transaktion KAUFEN: Erfolgreich POST /notify HTTP/1.0 HOST: pay01.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 166 BETRAG=500&STATUS=GEKAUFT&TSAID=47209585&REFERENZNR=IDKA001&HAENDLERNR=00001 00001&ZAHLART=KAUFEN&ZEITPUNKT=2004-10-13+10%3A43%3A32.000000& RMSG=Transaktion+erfolgreich Transaktion KAUFEN mit Antwortgeheimnis: Nicht erfolgreich POST / notify HTTP/1.0 HOST: pay01.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 178 BETRAG=103&ANTWGEHEIMNIS=GEHEIM&STATUS=ABGELEHNT&REFERENZNR=20041014160341%2 F2&HAENDLERNR=0000100001&ZAHLART=KAUFEN&ZEITPUNKT=2004-10- 14+16%3A05%3A43.000000&RMSG=Karte+abgelaufen Antwort vom Händlersystem: Antwort, die das Händlersystem an VR-EPay übermittelt. Es sollte jede Benachrichtigungsantwort vom Händlersystem quittiert werden, und nicht nur solche, die erfolgreich verlaufen sind. HTTP/1.1 200 OK CONNECTION: close Content-Type: text/html Content-length: 14 STATUS=SUCCESS VR-Pay virtuell Anbindungshandbuch - 32 - Version 2.1
7 Fehlermeldungen im VR-Pay virtuell Im VR-Pay virtuell gibt es zwei Arten an Fehlern. Dies sind zum einen Systemfehler im VR-Pay virtuell und zum anderen Transaktionsfehler. 7.1 Systemfehler Systemfehler treten auf, wenn die Schnittstelle zum VR-Pay virtuell nicht richtig bedient wird oder aber interne Probleme innerhalb des VR-Pay virtuell aufgetreten sind. Ein Systemfehler wird immer mit einem FEHLERCODE und einem FEHLERTEXT beantwortet. Bsp.: FEHLERCODE=55005 FEHLERTEXT=Fehler in Uebergabeparameter: Parameter REFERENZNR ist zu lang 7.2 Auflistung der Systemfehler Antwortcode Beschreibung 50000 50000: Unberechtigter Zugriff 50001 50001: Allgemeiner Fehler im VR-Pay virtuell 55000 55000: Systemfehler 55001 55001: Die Eingangsparameter fuer den Service -?- sind fehlerhaft. 55002 55002: Der Parameter -?- fehlt oder ist ungueltig. 55003 55003: Die Eingangsparameter fuer den Warenkorb enthalten folgende Fehler: -?- 55004 55004: Fehler in der Warenkorbpruefung: Betrag (-?-) stimmt nicht mit berechneter Warenkorbsumme (-?-) ueberein. 55005 55005: Fehler in Uebergabeparametern: -?- 55006 55006: Uebergabeparameter fuer den Service Dialog nicht korrekt: -?- 55007 55007: Uebergabeparameter fuer den Service Direkt nicht korrekt: -?- 55008 55008: Ungueltiger Servicename 55009 55009: Warnung bei Mallannmeldung: Anmeldung mit [-?-] für Haendlerid [-?-] nicht zugelassen. Bitte Haendler informieren! 56100 56100: Unberechtigter Zugriff 56200 56200: Fehler im Service Direkt 56301 56301: Zahlart -?- wird nicht unterstuezt 56302 56302: Fehler beim Service Dialog: -?- 60000 60000: Fehler in Transaktionssverarbeitung: [-?-] 60001 60001: Fehler in Transaktionssverarbeitung: Zahlart fehlt oder unbekannt 60100 60100: Datenbankfehler in Bestellvorgangsverarbeitung 60101 60101: Bestellvorgang konnte nicht geladen werden 60102 60102: Bestellvorgang konnte nicht geladen werden 60103 60103: Datenbankfehler in Bestellvorgangsverarbeitung 60110 60110: Fehler in der Betragsprüfung, Transaktion wird nicht durchgeführt: -?- 60111 60111: Bestellung hat bereits den Status abgelehnt 60112 60112: Fehler in Bestellvorgangsverarbeitung: Zahlart fehlt oder unbekannt 60113 60113: Datenbankfehler in Bestellvorgangsverarbeitung VR-Pay virtuell Anbindungshandbuch - 33 - Version 2.1
60200 60200: Datenbankfehler in Zahlungsvorgangsverarbeitung 60201 60201: Datenbankfehler in Zahlungsvorgangsverarbeitung 60202 60202: Zahlung konnte nicht geladen werden 60203 60203: Zahlung konnte nicht geladen werden 60204 60204: Zahlungsvorgang konnte nicht geladen werden 60205 60205: Zahlungsvorgang konnte nicht geladen werden 60206 60206: Zahlung besitzt falschen Status [-?-] 60207 60207: Innerhalb eines Zahlvorgangs kann der Betrag nicht geändert werden. Übergebener Betrag [-?-] ungleich Zahlbetrag [-?-] 60208 60208: Fehler im Zahlungsvorgang: Zahlart fehlt oder unbekannt 60210 60210: Datenbankfehler in Zahlungsvorgangsverarbeitung 60300 60300: Datenbankfehler in Gutschriftsvorgangsverarbeitung 60301 60301: Datenbankfehler in Gutschriftsvorgangsverarbeitung 60302 60302: Gutschrift konnte nicht geladen werden 60303 60303: Gutschrift konnte nicht geladen werden 60304 60304: Gutschriftsvorgang konnte nicht geladen werden 60305 60305: Gutschriftsvorgang konnte nicht geladen werden 60306 60306: Gutschrift besitzt falschen Status [-?-] 60307 60307: Innerhalb eines Gutschriftvorgangs kann der Betrag nicht geändert werden. Übergebener Betrag [-?-] ungleich Gutschriftbetrag [-?-] 60308 60308: Fehler im Gutschriftsvorgang: Zahlart fehlt oder unbekannt 60310 60310: Datenbankfehler in Gutschriftsvorgangsverarbeitung 65106 65106: Vorgang konnte nicht initialisiert werden 65107 65107: Benachrichtigungsvorgang konnte nicht angelegt werden: [-?-] 65150 65150: Konnte -?- nicht lesen. 65151 65151: Fehlerhafter Wert in -?- 65152 65152: Datenbankfehler bei der Vorgangsverarbeitung 67001 67001: Parameter -?- fehlt. 67002 67002: Parameter -?- ist zu kurz. 67003 67003: Parameter -?- ist zu lang. 67004 67004: Unzulaessiger Wert in Parameter -?-. 67005 67005: Unzulaessiger Wert in Parameter -?-. 67006 67006: Unbekannter Parameter -?-. 68000 68000: Vorgang konnte nicht angelegt werden: [-?-] 68010 68010: Datenbankfehler in Vorgangsverarbeitung 68011 68011: Vorgang konnte nicht geladen werden 68012 68012: Vorgang konnte nicht geladen werden 68013 68013: Datenbankfehler in Vorgangsverarbeitung 68020 68020: Referenznummer [-?-] zum Händler [-?-] bereits vorhanden 68030 68030: Vorgang konnte nicht initialisiert werden 68201 68201: Fehler im Verwendungszweck 68202 68202: Verwendung konnte nicht geladen werden VR-Pay virtuell Anbindungshandbuch - 34 - Version 2.1
68203 68203: Verwendungszeile -?- ist ungültig 68300 68300: Datenbankfehler im Zusatzparameter 68300 68300: Datenbankfehler im Warenkorb 68301 68301: Fehler bei der Parameterverarbeitung 68301 68301: Fehler in Warenkorbzeile -?- 68302 68302: Parametername -?- ist ungültig 68302 68302: Fehler in Warenkorbzeile 68303 68303: Parametername -?- ist ungültig 68303 68303: Warenkorb konnte nicht geladen werden 68304 68304: Parameter konnte nicht geladen werden 68304 68304: Fehler in Warenkorbzeile -?-: -?- 68500 68500: Konnte Parameter:-?- nicht lesen. 68501 68501: Fehlerhafter Wert in Parameter -?- 7.3 Transaktionsfehler Transaktionsfehler entstehen dann, wenn beim prozessieren einer Transaktion Fehler ermittelt werden bzw. Probleme im Autorisierungssystem vorhanden sind. Dies ist dann der Fall, wenn z.b. die Karte abgelaufen, das Limit überschritten oder aber auch der Kartenherausgeber zur Zeit nicht erreichbar ist. Transaktionsfehler werden im gleichen Format beantwortet wie auch erfolgreiche Transaktionen. Hier wird dann allerdings STATUS=ABGELEHNT und RMSG=Ablehnungsgrund gesetzt. Die Returnmessage (RMSG) enthält dort den ausgeschriebenen Antworttext, ein Returncode wird hier nicht mit ausgegeben. 7.4 Auflistung der Transaktionsfehler Hier finden Sie eine Liste mit Transaktionsfehlern. Die Liste der Transaktionsfehler kann sich während des Betriebs verändern. So ist es möglich, das weitere Fehlermeldungen hinzukommen bzw. entfallen oder aber auch, dass sich der Text einzelner Fehlermeldungen verändert. Antwortcode Beschreibung 00 Transaktion erfolgreich 02 Telefonische Autorisierung erforderlich 03 Ungültige Händler- ID 04 Karte nicht zugelassen 05 Autorisierung abgelehnt 09 verzögerte Bearbeitung der Autorisierung 12 Ungültige Transaktion 13 Limit überschritten 14 Ungültige Karte 21 Storno kann nicht erfolgen, da die zu stornierende Nachricht nicht gefunden wurde. 30 Format Fehler 31 Kartenherausgeber nicht zugelassen 33 Karte abgelaufen VR-Pay virtuell Anbindungshandbuch - 35 - Version 2.1
34 Manipulationsverdacht 40 Verlangte Funktion nicht unterstützt 43 Karte gestohlen 50 Autorisierung doppelt 51 Limit überschritten 54 ec- Chipkarte nicht mehr gültig 56 Karte nicht bekannt 57 Referenztransaktion enthielt andere Kartendaten 58 Terminal- ID unbekannt 59 Manipulationsverdacht bei ec- Chipkarte 61 Karte ist gesperrt in lokaler Sperrliste 62 Gesperrte Karte 64 Transaktionsbetrag ist abweichend von der Bezugstransaktion; bei Storno; Kreditkarten auch bei Endsummenbuchung 65 Limit der Transaktionsfrequenz überschritten 78 Sequenzfehler in BMP 62 80 Betrag nicht länger verfügbar 81 Initialisierung fehlerhaft (Warnung); Wiederholung erforderlich 82 (Vor-)Initialisierung unzulässig (Terminal gesperrt) 85 Ablehnung vom Kreditkarteninstitut 86 Händler unbekannt 87 Terminal (PIN- Pad) unbekannt 89 CRC falsch 91 Kartenherausgeber vorübergehend nicht erreichbar 92 Der Kartentyp wird von dem Autorisierungssystem nicht unterstützt 96 Verarbeitung zur Zeit nicht möglich 97 Sicherheitsverletzung MAC- Prüfung ergab Fehler 98 Datum/Uhrzeit nicht plausibel oder Tracenummer nicht aufsteigend 33 Die Karte ist verfallen. 101 Original-Transaktion nicht gefunden. 102 Original-Transaktion kann nicht gelesen werden. 200 Beleg-Nummer für das virtuelle POS- Terminal kann nicht gelesen werden 201 Trace- Nummer für das virtuelle POS- Terminal kann nicht gelesen werden. 203 Kein freies Terminal für diesen Händler 207 Autorisierung wegen timeout unterbrochen. 209 Die Verbindung zum Payment-Server kann nicht aufgebaut werden. 210 Fehler in der Verbindung zum Payment-Server 212 Die Trace- Nummer in der Antwort ist unterschiedlich von der in der Anfrage. 213 Die Terminal- ID in der Antwort ist unterschiedlich von der in der Anfrage. 214 Empfangene Nachricht kann nicht in das ZVT- Protokoll übernommen werden. 215 Nachricht kann nicht in das zu sendende Format übertragen werden. 216 Die Antwort vom Payment- Server ist nicht korrekt. VR-Pay virtuell Anbindungshandbuch - 36 - Version 2.1