ANBINDUNGSHANDBUCH FÜR VR-PAY VIRTUELL "GIROPAY ONLY"
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
VR-Pay virtuell Shop giropay only - Anbindungshandbuch Version 2.4 / Stand 02/2010
„GIROPAY ONLY“
FÜR VR-PAY VIRTUELL
ANBINDUNGSHANDBUCH
VR-Pay virtuell Anbindungshandbuch - giropay
1 EINLEITUNG ........................................................................................................................................................4
2 ANBINDUNG AN VR-PAY VIRTUELL ............................................................................................................6
2.1 ABLAUF EINER GIROPAY - TRANSAKTION .........................................................................................................6
2.2 BEISPIEL EINER ANFRAGE FÜR DEN GESCHÄFTSVORFALL „KAUFEN“............................................................7
3 SCHNITTSTELLENPARAMETER....................................................................................................................8
3.1 BESCHREIBUNG ALLER SCHNITTSTELLENPARAMETER FÜR GIROPAY-TRANSAKTIONEN ...................................8
3.2 PARAMETER FÜR „GIROPAY“- TRANSAKTIONEN IM ÜBERBLICK ....................................................................11
4 BENACHRICHTIGUNG AN DAS HÄNDLERSYSTEM ...............................................................................12
4.1 MÖGLICHE PARAMETER ZU EINER BENACHRICHTIGUNGSANTWORT...............................................................12
4.2 BEISPIEL ZU EINER BENACHRICHTIGUNGSANTWORT ......................................................................................13
5 FEHLERMELDUNGEN IM VR-PAY VIRTUELL.........................................................................................14
5.1 SYSTEMFEHLER ..............................................................................................................................................14
5.2 TRANSAKTIONSFEHLER...................................................................................................................................14
6 LAYOUT-ANPASSUNG DER BEZAHLSEITE ..............................................................................................15
6.1 BEISPIELE „DIALOG“- BEZAHLSEITE...............................................................................................................15
6.2 HÄNDLERSPEZIFISCHE BEZEICHNER ...............................................................................................................15
7 PROGRAMMIERBEISPIELE...........................................................................................................................16
7.1 PROGRAMMIERSPRACHE PERL – DIALOG-TRANSAKTION ...............................................................................16
7.2 PROGRAMMIERSPRACHE PHP – DIALOG-TRANSAKTION ................................................................................18
8 GLOSSAR ............................................................................................................................................................20
VR-Pay virtuell Anbindungshandbuch - giropay -2- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
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.
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: Geprüft von: Grund der Änderung
Datum: Datum:
2.3 14.01.10 – nk_ch Ursprung Anbindungshandbuch VR-Pay virtuell Shop.
Reduktion auf giropay only
2.31 01.02.10 – xgadgir Prüfung giropay only
2.4 10.02.10 – xgadfbi xgadgir Änderungen zum Release Feb. 2010:
• Mehrsprachigkeit der Bezahlseite erweitert
• Notifikationsnachricht wurde erweitert
• weitere Fremdwährungen werden unterstützt
• Bezahlseite berücksichtigt die Anlage einer
Bestellung im Shopsystem über
Parameter „BENACHRPROF“
• Generelle Überarbeitung aus Rückfragen
VR-Pay virtuell Anbindungshandbuch - giropay -3- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
1 Einleitung
Das Online- Payment- System der CardProcess für den Vertrieb über die Volksbanken Raiffeisenbanken
(VR-Pay virtuell) bietet Händlern die Möglichkeit, Ihren Online-Shop einfach, bequem und schnell an das
sichere Bezahlverfahren GIROPAY anzuschließen.
Die Zahlung im Online-Shop wird vom Endkunden über sein Homebanking-System (automatische
Weiterleitung) freigegeben und von der Bank durch Übermittlung einer Zahlungsgarantie bestätigt. Dadurch
profitiert der Händler von höchster Zahlungssicherheit.
Weiterhin erhält der Händler ein webbasiertes Verarbeitungstool, seine VR-Pay virtuell Händlerkasse, über die
er nach Transaktionen recherchieren kann.
⇒ Onlineüberweisung giropay, www.giropay.de
Die Bezahlform giropay unterliegt gewissen Einschränkungen:
• Für giropay sind keine Reservierungen möglich.
• Es kann keine Bestellprüfung (BENACHRPROF = SHOP) durchgeführt
werden. ( Anbindungshandbuch VR-Pay virtuell Shop Kapitel 2.2 )
• Die Bezahlseite darf nicht in einem iFrame dargestellt werden.
VR-Pay virtuell Anbindungshandbuch - giropay -4- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay Voraussetzung für die Anbindung an VR-Pay virtuell mit einem Shopsystem: Händler verfügt über einen Online-Auftritt, in dem er Formulardaten 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. Zugangsdaten: Ihre Partner-Nr. 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 Partner-Nr. 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. 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. Informationen: Informationen / Dokumentation zu VR-Pay virtuell erhalten Sie im Internet unter der Adresse www.vr-pay-virtuell.de. Weitere Fragen zu VR-Pay virtuell beantworten wir Ihnen gerne unter der E-Mail-Adresse vr-pay@cardprocess.de. VR-Pay virtuell Anbindungshandbuch - giropay -5- Version 2.4
VR-Pay virtuell Anbindungshandbuch - giropay
2 Anbindung an VR-Pay virtuell
Sie können sich über den Service Dialog-Transaktion an VR-Pay virtuell anbinden. Hierzu müssen Sie
Grundparameter einer Transaktion wie z.B. den Betrag, die Währung, die Referenznummer,
verschiedene URLs etc. an VR-Pay virtuell übergeben. Die Datenübertragung zwischen dem
Händlersystem und dem Bezahlsystem erfolgt URL- Encoded als HTTP-POST- Aufruf. Dabei müssen die
Daten in jedem Fall SSL- verschlüsselt an VR-Pay virtuell übertragen werden.
Daraufhin erhält der Kunde die Bezahlseite direkt vom VR-Pay virtuell.
In die Bezahlseite trägt der Kunde nun die Bezahldaten für giropay ein (Bankleitzahl und optional auch
die Kontonummer). Nun wird der Kunde über giropay an sein Homebanking weitergeleitet und gibt die
vorausgefüllte Überweisung frei. Im Anschluss erhält der Kunde den Status zur Transaktion (erfolgreich
oder fehlerhaft) über die Bezahlseite angezeigt. Betätigt der Kunde nun den „weiter“-Button, so wird er
zurück in Ihr System geleitet. Über einen separaten Vorgang werden Sie zum Status der Transaktion
benachrichtigt.
2.1 Ablauf einer giropay - Transaktion
VR-Pay virtuell Anbindungshandbuch - giropay -6- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
2.2 Beispiel einer Anfrage für den Geschäftsvorfall „KAUFEN“
POST /pbr/transaktion HTTP/1.0
HOST: payinte.vr-epay.de
Content-type: application/x-www-form-urlencoded
Content-length: 352
Authorization: Basic TVRBd01EQXhNREF3TURwdVpYVm5hV1Z5YVdjLw==
HAENDLERNR=1000010001&REFERENZNR=BEST123&BETRAG=200&WAEHRUNG=EUR&ARTIKELANZ=0&UR
LERFOLG=http://www.shop.de/erfolg.html&URLFEHLER=http://www.shop.de/fehler.html&URLANTWORT=h
ttps://www.shop.de/vrpayantwort&URLABBRUCH=http://www.shop.de/abbruch.html&URLAGB=http://ww
w.shop.de/agb.html&ZAHLART=KAUFEN&SERVICENAME=DIALOG&VERWENDANZ=0&AUSWAHL=N&BRAN
D=GIROPAY
Antwort als Redirect mit Auswahl = „N“ & BRAND = „GIROPAY“
VR-Pay virtuell Anbindungshandbuch - giropay -7- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
3 Schnittstellenparameter
3.1 Beschreibung aller Schnittstellenparameter für giropay-Transaktionen
Die Anmeldeparameter („Credential´s“) dienen zur Anmeldung an VR-Pay virtuell.
Anmelde-Parameter Beschreibung
Partner-Nr. Wird von der Cardprocess GmbH zugewiesen.
Passwort Wird von der Cardprocess GmbH mitgeteilt und kann über den Händlerzugang online geändert werden. (Benutzer „sendpay“)
POST-Parameter Format Gültige Werte Beschreibung
Allgemeine Parameter
HAENDLERNR C 10 Wird von der Cardprocess GmbH zugewiesen.
TSATYP C ECOM - eCommerce Transaktionen (über Ihre Shopanbindung)
Bestelldaten
REFERENZNR C 4-20 0-9A-Za-z Bestell- / Zuordnungsnummer zu einer Bestellung im Shop.
Leerzeichen Diese Nummer erscheint bei Bezahlart GIROPAY auf dem Kontoauszug des
$%*+,-./ Kunden.
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 nach ISO 4217
http://de.wikipedia.org/wiki/ISO_4217
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 (...)
hinter dem Parameternamen ANZAHL stehen für die Position des Artikels im
Warenkorb.
VR-Pay virtuell Anbindungshandbuch - giropay -8- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
POST-Parameter Format Gültige Werte Beschreibung
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 ZHL (Default) • Nach durchgeführter Zahltransaktion benachrichtigen.
KEI • Keine Benachrichtigung.
Transaktion
ZAHLART C KAUFEN Die Zahlart gibt an, um welche Art von Transaktion es sich handelt.
Zu Beginn einer Transaktion wird zwischen dem Reservieren und dem Kaufen
unterschieden. Im Falle von Giropay gibt es nur „KAUFEN“.
Kaufen = Reservieren und buchen in einem Vorgang
SERVICENAME C DIALOG 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.
Verwendungszweck
VERWENDANZ INT 1 Anzahl der übermittelten Verwendungszweckzeilen, die bei einer ELV-Zahlung
dem Kunden auf dem Kontoauszug angezeigt werden. Bei giropay finden die
VR-Pay virtuell Anbindungshandbuch - giropay -9- Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
POST-Parameter Format Gültige Werte Beschreibung
Verwendungszweckzeilen keine Verwendung, daher sollte hier der Parameter
auf 0 (VERWENDANZ=0) gesetzt werden.
VERWENDUNG… C 1-25 0-9A-Za-zäöüÄÖÜß Sollten bei giropay-Transaktionen Verwendungszweckzeilen übergeben
Leerzeichen werden, so haben diese rein informativen Wert für den Händler. Ersichtlich in
$%*+,-./ der Händlerkasse oder beim Transaktionsdatenexport.
Service “DIALOG”
SPRACHE C DE, EN, FR, ES, IT, NL, PL, CS Dies ist die Sprache, in der der Bezahldialog dem Kunden präsentiert wird. Falls
kein Wert übermittelt wird, wird die bevorzugte Sprache des Kundenbrowsers
ausgelesen (dieses Vorgehen wird empfohlen).
AUSWAHL C N Dieser Parameter gibt die Möglichkeit, dem Kunden über die Bezahlseite alle
verfügbaren Zahlungsmethoden oder eine Auswahl anzubieten oder nur
explizit eine einzige (bei „N“).
Für giropay-only muss hier Auswahl=“N“ gesetzt werden
BRAND C GIROPAY Bei Auswahl = “N” wird nur ein Brand verlangt (bspw. GIROPAY)
VR-Pay virtuell Anbindungshandbuch - giropay - 10 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
3.2 Parameter für „giropay“- Transaktionen im Überblick
Parameter name Typ Beschreibung / Ausprägung SERVICE DIALOG
Kauf
GIROPAY
HAENDLERNR C10 Vertragspartner P
TSATYP C Transaktionstyp: ECOM O
REFERENZNR C 4-20 Eindeutige Bestellnummer P
BETRAG INT Gesamtbetrag kl. Einheit P
WAEHRUNG C3 Währungscode EUR P
INFOTEXT C 1-1024 Infotext Händlerkasse O
ARTIKELANZ INT 1-3 Anzahl unterschiedlicher Artikel P
ARTIKELNR... C 1-16 Artikelnummer O
ARTIKELBEZ... C 1-128 Artikelbezeichnung O
ANZAHL... INT 1-10 Artikelanzahl O
EINZELPREIS... INT 1-12 Einzelpreis O
URLERFOLG C 3-254 URL nach Zahlungserfolg P
URLFEHLER C 3-254 URL nach Zahlungsmisserfolg P
URLANTWORT C 3-254 URL für Notifikation P
URLABBRUCH C 3-254 URL nach Zahlungsabbruch P
URLAGB C 3-254 URL für AGB ´s P
URLCVC C 3-254 Hilfe zu CVC2 O
ANTWGEHEIMNIS C 1-32 Notifikationsgeheimnis O
BENACHRPROF C ZHL / KEI O
ZAHLART C KAUFEN P
SERVICENAME C DIALOG P
VERWENDANZ INT 1 Anzahl Verwendungszeilen P
VERWENDUNG... C 1-25 Verwendungszweck O
SPRACHE C2 Sprache DE,EN,FR,ES,IT,NL,PL,CS O
AUSWAHL C1 Brandauswahl N N
BRAND C Giropay P
INT: Integer C: Character P: Pflichtfeld O: Optional N/U: Nicht unterstützt J: Ja N: Nein
VR-Pay virtuell Anbindungshandbuch - giropay - 11 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
4 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.
Wichtig:
Es sollte beachtet werden, dass es sich bei der Zieladresse für die Benachrichtigung
(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 eine Firewall).
4.1 Mögliche Parameter zu einer Benachrichtigungsantwort
POST-Parameter Mögliche Werte Beschreibung
HAENDLERNR C 10 Wird von der Cardprocess GmbH zugewiesen.
REFERENZNR 0-9A-Za-z Bestell- / Zuordnungsnummer zu einer Bestellung im Shop.
Leerzeichen Diese Nummer erscheint bei ELV beim Kunden auf dem
$%*+,-./ Kontoauszug.
BETRAG 0-9 Betrag zur jeweiligen Transaktion in der kleinsten Einheit.
3,59 Euro werden als 359 übermittelt.
WAEHRUNG C3 Währungskennzeichen nach ISO 4217.
ZAHLART KAUFEN Die Zahlart gibt an, um welche Art von Transaktion es sich
handelt.
STATUS GEKAUFT Nach erfolgreichem Kauf
ABGELEHNT Von VR-Pay virtuell oder Acquirer abgelehnt
IN BEARBEITUNG Fehlerfall (keine Antwort von Endsystemen, etc.)
RMSG siehe Kapitel 5 siehe Fehlermeldungen in VR-Pay virtuell
ZEITPUNKT Zeitstempel Zeitpunkt der Transaktion.
z.B. 2010-01-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, dass die Benachrichtigungsmeldung
vom Payment-Betreiber gekommen ist.
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.)
SICHERHEIT C1-64 Mit welchen Sicherheitsmerkmalen wurde die Transaktion
abgewickelt.
BRAND C Welche Bezahlmethode wurde vom Kunden verwendet
GIROPAY
KONTONR INT 3-10 Maskierte Kontonummer.
BLZ INT 8 Bankleitzahl.
VR-Pay virtuell Anbindungshandbuch - giropay - 12 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay POST-Parameter Mögliche Werte Beschreibung NACHRICHTNR INT 1-10 Interne Systemnummer der Benachrichtigung. 4.2 Beispiel zu einer Benachrichtigungsantwort Transaktion KAUFEN mit Antwortgeheimnis: Erfolgreich POST / notify HTTP/1.0 HOST: payinte.vr-epay.de Content-type: application/x-www-form-urlencoded Content-length: 336 SICHERHEIT=SSL- verschl%FCsselt&RMSG=Zahlungsgarantie+erteilt.+Transaktion+erfolgreich+abgeschlossen.&NACHRIC HTNR=57674&STATUS=GEKAUFT&BETRAG=500&BLZ=44448888 &ZEITPUNKT=2010-02- 05+12%3A57%3A19.000000&WAEHRUNG=EUR&ZAHLART=KAUFEN&REFERENZNR=104000- 0100205084348&BRAND=GIROPAY&TSAID=F000002QAE&HAENDLERNR=1000010001&ANTWGEHEI MNIS=GEHEIM Antwort vom Händlersystem: Antwort, die das Händlersystem an VR-Pay virtuell ü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 - giropay - 13 - Version 2.4
VR-Pay virtuell Anbindungshandbuch - giropay
5 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.
5.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
5.2 Transaktionsfehler
Transaktionsfehler entstehen dann, wenn beim Durchführen einer Transaktion Fehler ermittelt werden
bzw. Probleme im Homebanking erkannt werden. (bspw. Fehlerhafte PIN-Eingabe.)
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.
Antwortcode Beschreibung
10 Zahlungsgarantie erteilt.
4000 Transaktion erfolgreich abgeschlossen.
20 Bezahlvorgang nicht erfolgreich.
2000 Abbruch vor PIN-Eingabe.
2100 Abbruch nach Eingabe falscher PIN.
2200 Abbruch nach Kontosperrung durch falsche PIN.
2300 Abbruch, weil PIN in initialem Zustand.
2400 Account nicht für giropay geeignet.
2500 Abbruch vor TAN-Eingabe.
2600 Abbruch nach Eingabe falscher TAN.
2700 Abbruch nach Kontosperrung durch falsche TAN.
21 Zahlungsgarantie nicht erteilt.
22 Vorgang kundenseitig abgebrochen.
23 Vorgang aus technischen Gründen abgebrochen.
30 Wartezeit abgelaufen. Keine Statusinformationen verfügbar.
3100 Benutzerseitiger Abbruch.
3900 Keine Verbindung zum Bank-RZ möglich.
40 Konto des Käufers ist nicht für Onlinebanking freigeschaltet bzw. gesperrt.
4900 Transaktion nicht erfolgreich abgeschlossen.
VR-Pay virtuell Anbindungshandbuch - giropay - 14 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay 6 Layout-Anpassung der Bezahlseite Wünschen Sie Anpassungen zur Dialogseite, so senden Sie bitte eine Mail an vr-pay@cardprocess.de und Sie erhalten die benötigten Dateien (CSS – Datei und Beispielseiten zur Offline- Darstellung). 6.1 Beispiele „Dialog“- Bezahlseite 6.2 Händlerspezifische Bezeichner Desweiteren können einzelne Bezeichner in den verfügbaren Sprachen durch händlerspezifische Texte ersetzt werden. Senden Sie uns in diesem Fall bitte den originalen Text inklusive der gewünschten Bezeichnung unter Angabe Ihrer Partner-Nr. an vr-pay@cardprocess.de. Bspw. Die Buttons „Abbrechen“ & „Bezahlen“ in deutscher (DE) und englischer Sprache (EN): Original „DE“ Geändert „DE“ Geändert „EN“ VR-Pay virtuell Anbindungshandbuch - giropay - 15 - Version 2.4
VR-Pay virtuell Anbindungshandbuch - giropay
7 Programmierbeispiele
Hinweis: Diese Codesegmente dienen lediglich der Veranschaulichung und sind nicht für
eine produktive Systemumgebung geeignet!
7.1 Programmiersprache Perl – Dialog-Transaktion
#!/opt/perl/bin/perl -w
#######################################################################
## pay.cgi ##
## Version 1.0 ##
## Copyright (c) 2005 by GAD eG - vr-epay ##
#######################################################################
## Sinn und Zweck:
## Dieses CGI-Programm nimmt Bezahlparameter entgegen und leitet den
## Redirect des Paymentsystems an den Kundenbrowser weiter
##
## Kurzbeschreibung des Programmablaufs:
## Übergabeparameter werden entgegen genommen und auf Vollständigkeit geprüft.
## Zu diesen werden die Standardwerte aus dem Programm in einer Hashreferenz
## abgelegt und ein UserAgent Objekt erzeugt. Bei Bedarf wird eine
## Proxyadresse eingefügt.
##
## Anschließend wird der Request abgeschickt und die Antwort ausgewertet:
## -> Im Gutfall erhält man einen Redirect auf die Bezahlseite (DIALOG)
## -> Im negativen Fall wird eine Fehlermeldung im Content zurückgeben
#######################################################################
use strict;
use CGI;
use URI::Escape;
use Data::Dumper;
use LWP::UserAgent;
use HTTP::Request::Common;
########################################################################
# Konfiguration #
########################################################################
# Fehlerausgabe: 1 | 0
my $LOGTXT = "[".localtime(time())."]"." [pay.cgi]: ";
my $DEBUG = 0;
# Verbindungsparameter zum Payment
my $PROT = 'http://';
my $PROTS = 'https://';
my $PAY_DOMAIN = 'payinte.vr-epay.de'; # Testsystem
#my $PAY_DOMAIN = 'pay.vr-epay.de'; # Livesystem !
my $PAY_LOCATION = '/pbr/transaktion';
my $PAY_URL = $PROTS . $PAY_DOMAIN . $PAY_LOCATION;
# Adresse des Proxy, falls benötigt
my $PROXY_URL = 'http://ihr.proxy.de:8080';
# Autorisierung IID=Institut=Haendlernr & Passwort für sendpay Benutzer
my $IID = 'ihre Haendlernummer';
my $PWD = 'ihr Passwort';
### Einlesen der HTTP-POST/HTTP-GET Parameter
my $query = new CGI;
my $params = $query->Vars;
# Eintrag ins Webserver-Log
print STDERR "$LOGTXT ÜBERGABEWERTE: " . Dumper($params) . "\n\n" if ($DEBUG);
VR-Pay virtuell Anbindungshandbuch - giropay - 16 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
### Parameter für Service "DIALOG" zusammenstellen
# 1. Übergabe ans Programm:
my $pp_get = ['REFERENZNR','BETRAG','WAEHRUNG'];
# 2. Standardwerte aus Konfiguration:
my $pp_post = { HAENDLERNR => 'ihre Haendlernummer',
ZAHLART => 'KAUFEN',
AUSWAHL => 'N',
BRAND => 'GIROPAY',
SERVICENAME => 'DIALOG',
VERWENDANZ => 0,
ARTIKELANZ => 0,
# URLANTWORT Standardwert: "$PROTS$PAY_DOMAIN/notify"
URLANTWORT => 'ihr Benachrichtigungs-CGI',
URLERFOLG => 'ihre Erfolgsseite.html',
URLFEHLER => 'ihre Fehlerseite.html',
URLABBRUCH => 'ihre Abbruchseite.html',
URLAGB => 'ihre Hilfeseite.html',
URLCVC => 'ihre AGB´s.html',
};
### Prüfen auf Vollständigkeit und erzeugen der POST-Parameter
for (@$pp_get) {
exists $params->{$_} or &msg ("Parameter fehlt: $_\n");
$pp_post = { # Standardwerte & Übergabewerte
%$pp_post,
$_ => $params->{$_}
};
}
print STDERR "$LOGTXT POSTPARAMETER: ".Dumper($pp_post). "\n\n" if ($DEBUG);
### Request absetzen
my $ua = LWP::UserAgent->new;
# wird Proxy benötigt ?
#$ua->proxy(http => $PROXY_URL);
my $request = HTTP::Request::Common::POST $PAY_URL, [ %$pp_post ];
$request->authorization_basic($IID, $PWD);
my $response = $ua->request($request);
print STDERR "$LOGTXT RESPONSE-OBJEKT: ".Dumper($response)."\n\n" if ($DEBUG);
### Antwort auswerten
if ($response->is_redirect) {
### OK: Antwort ist ein Redirect -> Übergabe an Kundenbrowser
# HTTP-Header direkt durchreichen
print $response->headers->as_string, "\n\n";
} else {
# NOK: Systemfehler
print STDERR "$LOGTXT FEHLER BEIM AUFRUF DES BEZAHLSYSTEMS:
".Dumper($response)."\n\n";
&msg( uri_unescape($response->content) );
}
exit(1);
# Ausgabe einer Meldung
sub msg {
my $message = shift;
print "Content-type: text/plain";
print "\n\n";
print "$LOGTXT " . $message;
exit(0);
VR-Pay virtuell Anbindungshandbuch - giropay - 17 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay 7.2 Programmiersprache PHP – Dialog-Transaktion
VR-Pay virtuell Anbindungshandbuch - giropay
// Gibt HTTP-Header aus
curl_setopt($ch, CURLOPT_HEADER, 1);
// keine automatische Weiterleitung
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Connection Timeout nach 20 Sek.
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 20);
// cURL Anfrage ausführen
$ret = curl_exec($ch);
// cURL-Parameter ausgeben (zu Testzwecken)
//var_dump($ret);
//var_dump(curl_getinfo($ch));
//break;
if ($ret == false) {
// schließt cURL handler
curl_close($ch);
// cURL Fehler wird ausgegeben
echo 'Fehler: Paymentserver nicht erreichbar ' .
'(Falsche Payment-Server-URL oder Timeout nach 20 Sek., ' .
'da Firewall nicht freigeschaltet)';
} else {
// mehr Informationen zur cURL-Anfrage
$info = curl_getinfo($ch);
// schließt cURL handler
curl_close($ch);
// HTTP-Code prüfen
switch ( $info['http_code'] ) {
case "302": // carriage return wird entfernt
$message = str_replace("\r","", $ret);
// Trennung von Header & Content
$message = explode("\n\n", $message);
// Header in Array
$header_array = explode("\n",$message[0]);
// Header-Zeilen werden durchlaufen
foreach($header_array as $value) {
// Zeile aufbrechen
$param = explode(": ",$value);
// Location wird gesucht
if(strtoupper($param[0]) == 'LOCATION') {
// Redirect wird zurückgegeben
header($value);
}
}
break;
case "200": // Fehler ist aufgetreten (Fehlermeldung im Content)
// carriage return wird entfernt
$message = str_replace("\r","", $ret);
// Trennung von Header & Content
$content = explode("\n\n", $message);
// Fehlermeldung wird zurückgegeben
echo $content[1];
break;
case "401": // Anmeldefehler wird zurückgegeben
echo '401: Anmeldung am Paymentserver fehlgeschlagen: ' .
'Bitte prüfen Sie die Anmeldedaten (Partner-Nr/ sendpay-Passwort) ' .
'und die URL zum Payment-Server.';
break;
default: // weitere HTTP-Codes - Systemfehler
echo 'Ein Systemfehler ist aufgetreten.';
break;
}
}
?>
VR-Pay virtuell Anbindungshandbuch - giropay - 19 - Version 2.4VR-Pay virtuell Anbindungshandbuch - giropay
8 Glossar
Name Beschreibung
Acquirer Kreditkartenautorisierer, z.B. CardProcess, WGZBank, DZ-Bank
Acquirer Brand Beziehung des Acquirers zum Kreditkartenunternehmen
Autorisierung Reservierung eines Kaufbetrages
Autorisierungsanfrage Anfrage für die Reservierung eines Kaufbetrages
BLZ Bankleitzahl, eindeutige Institutskennung einer Bank
Brand Marke = Kreditkartenunternehmen (z.B. VISA, Mastercard, Diners
etc.)
Browser Client-Programm, das Anforderungen an einen Web-Server leitet
und die vom Server zurückgegebenen Informationen anzeigt
CGI CommonGatewayInterface = Schnittstelle, die es einem Browser
erlaubt, über einen Server Programme auszuführen, dient bspw.
der Formularverarbeitung im Internet,
http://de.wikipedia.org/wiki/Common_Gateway_Interface
CSS Cascading Style Sheets – Dient der Beschreibung des Layouts von
HTML-Seiten, http://de.wikipedia.org/wiki/Cascading_Style_Sheets
CSV -Datei Dateitransferformat für Dateien, durch Kommata getrennte Werte
DTA Datenträgeraustauschverfahren, Lastschriftdateien werden mit
Hilfe dieses Verfahrens zwischen den Bankinstituten ausgetauscht.
www.zahlungsverkehrsfragen.de
eCommerce Electronic commerce => elektronischer Handel, geschäftliche
Transaktionen über ein Computernetz wie das Internet
ELV Elektronisches Lastschriftverfahren für den bargeldlosen
Zahlungsverkehr, http://de.wikipedia.org/wiki/Lastschrift
Firewall Schutz eines internen Computer-Netzwerks vor Angriffen-
/Zugriffen von außen wie z.B. dem Internet.
HTML Hyper Text Markup Language, Seitenbeschreibungssprache für
Internetseiten
HTTP Hyper Text Transmission Protokoll, Protokoll zur Übertragung von
Daten im Internet.
HTTP-GET HTTP Methode, die angibt, das die Daten in der URI übertragen
werden.
HTTP-POST HTTP Methode die angibt, dass die Daten vom Client zum Server
im Content übertragen werden, bspw. mit Hilfe eines Formulars.
HTTPS Hyper Text Transmission Protokoll Secure, gibt an, dass die Daten
zwischen dem Client und Server SSL - Verschlüsselt übertragen
werden.
Issuer Kartenherausgebende Bank
IP -Adresse Eindeutige Adresse im Internet, über die ein Computer ansprechbar
ist.
Paymentsystem Abwicklung des Zahlungsverkehrs, digitales Zahlungssystem
SSL Secure Socket Layer; verschlüsselte Datenübertragung (Kanal) im
Internet, http://de.wikipedia.org/wiki/Secure_Sockets_Layer
VR-Pay virtuell Anbindungshandbuch - giropay - 20 - Version 2.4Sie können auch lesen
