ANBINDUNGSHANDBUCH FÜR VR-PAY VIRTUELL GIROPAY ONLY

Transkript

1 ANBINDUNGSHANDBUCH FÜR VR-PAY VIRTUELL GIROPAY ONLY VR-Pay virtuell Shop giropay only - Anbindungshandbuch Version 2.4 / Stand 02/2010

2 1 EINLEITUNG ANBINDUNG AN VR-PAY VIRTUELL ABLAUF EINER GIROPAY - TRANSAKTION BEISPIEL EINER ANFRAGE FÜR DEN GESCHÄFTSVORFALL KAUFEN SCHNITTSTELLENPARAMETER BESCHREIBUNG ALLER SCHNITTSTELLENPARAMETER FÜR GIROPAY-TRANSAKTIONEN PARAMETER FÜR GIROPAY - TRANSAKTIONEN IM ÜBERBLICK BENACHRICHTIGUNG AN DAS HÄNDLERSYSTEM MÖGLICHE PARAMETER ZU EINER BENACHRICHTIGUNGSANTWORT BEISPIEL ZU EINER BENACHRICHTIGUNGSANTWORT FEHLERMELDUNGEN IM VR-PAY VIRTUELL SYSTEMFEHLER TRANSAKTIONSFEHLER LAYOUT-ANPASSUNG DER BEZAHLSEITE BEISPIELE DIALOG - BEZAHLSEITE HÄNDLERSPEZIFISCHE BEZEICHNER PROGRAMMIERBEISPIELE PROGRAMMIERSPRACHE PERL DIALOG-TRANSAKTION PROGRAMMIERSPRACHE PHP DIALOG-TRANSAKTION GLOSSAR...20 VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4

3 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: Datum: Geprüft von: Datum: Grund der Änderung nk_ch Ursprung Anbindungshandbuch VR-Pay virtuell Shop. Reduktion auf giropay only xgadgir Prüfung giropay only 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 Version 2.4

4 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, 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 Version 2.4

5 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: 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: 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 Informationen: Informationen / Dokumentation zu VR-Pay virtuell erhalten Sie im Internet unter der Adresse Weitere Fragen zu VR-Pay virtuell beantworten wir Ihnen gerne unter der -Adresse vr-pay@cardprocess.de. VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4

6 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 Version 2.4

7 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= &REFERENZNR=BEST123&BETRAG=200&WAEHRUNG=EUR&ARTIKELANZ=0&UR LERFOLG= ttps:// 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 Version 2.4

8 3 Schnittstellenparameter 3.1 Beschreibung aller Schnittstellenparameter für giropay-transaktionen Die Anmeldeparameter ( Credential s ) dienen zur Anmeldung an VR-Pay virtuell. Anmelde-Parameter Partner-Nr. Passwort Beschreibung Wird von der Cardprocess GmbH zugewiesen. 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 A-Za-z Leerzeichen $%*+,-./ Bestell- / Zuordnungsnummer zu einer Bestellung im Shop. 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 INFOTEXT C 1- Informationstext zur Bestellung 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 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 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 Version 2.4

9 POST-Parameter Format Gültige Werte Beschreibung EINZELPREIS... INT 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 A-Za-zÄÖÜäöü URL, die nach erfolgreicher Annahme der Zahlung aufgerufen wird.!#$%&*+-./:?^_~ URLFEHLER C A-Za-zÄÖÜäöü URL, die nach fehlgeschlagener Zahlung aufgerufen wird.!#$%&*+-./:?^_~ URLANTWORT C A-Za-zÄÖÜäöü URL, an die das Benachrichtigungsprogramm seinen HTTPS-Request sendet.!#$%&*+-./:?^_~ URLABBRUCH C A-Za-zÄÖÜäöü!#$%&*+-./:?^_~ URL, die nach abgebrochener Zahlung aufgerufen wird. Hiernach ist der Einstieg in den Warenkorb sinnvoll. URLAGB C A-Za-zÄÖÜäöü URL, die die AGB s des Händlers anzeigt.!#$%&*+-./:?^_~ URLCVC C A-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) KEI Nach durchgeführter Zahltransaktion benachrichtigen. 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 Version 2.4

10 POST-Parameter Format Gültige Werte Beschreibung Verwendungszweckzeilen keine Verwendung, daher sollte hier der Parameter auf 0 (VERWENDANZ=0) gesetzt werden. VERWENDUNG C A-Za-zäöüÄÖÜß Leerzeichen $%*+,-./ Sollten bei giropay-transaktionen Verwendungszweckzeilen übergeben 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 Version 2.4

11 3.2 Parameter für giropay - Transaktionen im Überblick Parameter name Typ Beschreibung / Ausprägung SERVICE DIALOG GIROPAY Kauf HAENDLERNR C10 Vertragspartner P TSATYP C Transaktionstyp: ECOM O REFERENZNR C 4-20 Eindeutige Bestellnummer P BETRAG INT Gesamtbetrag kl. Einheit P WAEHRUNG C 3 Währungscode EUR P INFOTEXT C Infotext Händlerkasse O ARTIKELANZ INT 1-3 Anzahl unterschiedlicher Artikel P ARTIKELNR... C 1-16 Artikelnummer O ARTIKELBEZ... C Artikelbezeichnung O ANZAHL... INT 1-10 Artikelanzahl O EINZELPREIS... INT 1-12 Einzelpreis O URLERFOLG C URL nach Zahlungserfolg P URLFEHLER C URL nach Zahlungsmisserfolg P URLANTWORT C URL für Notifikation P URLABBRUCH C URL nach Zahlungsabbruch P URLAGB C URL für AGB s P URLCVC C 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 C 2 Sprache DE,EN,FR,ES,IT,NL,PL,CS O AUSWAHL C 1 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 Version 2.4

12 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 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 Einheit. 3,59 Euro werden als 359 übermittelt. WAEHRUNG C 3 Währungskennzeichen nach ISO ZAHLART KAUFEN Die Zahlart gibt an, um welche Art von Transaktion es sich handelt. STATUS GEKAUFT ABGELEHNT IN BEARBEITUNG Nach erfolgreichem Kauf Von VR-Pay virtuell oder Acquirer abgelehnt Fehlerfall (keine Antwort von Endsystemen, etc.) RMSG siehe Kapitel 5 siehe Fehlermeldungen in VR-Pay virtuell ZEITPUNKT Zeitstempel Zeitpunkt der Transaktion. z.b %3A43%3A 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 Version 2.4

13 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=SSLverschl%FCsselt&RMSG=Zahlungsgarantie+erteilt.+Transaktion+erfolgreich+abgeschlossen.&NACHRIC HTNR=57674&STATUS=GEKAUFT&BETRAG=500&BLZ= &ZEITPUNKT= %3A57%3A &WAEHRUNG=EUR&ZAHLART=KAUFEN&REFERENZNR= &BRAND=GIROPAY&TSAID=F000002QAE&HAENDLERNR= &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/ OK CONNECTION: close Content-Type: text/html Content-length: 14 STATUS=SUCCESS VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4

14 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 Transaktion erfolgreich abgeschlossen. 20 Bezahlvorgang nicht erfolgreich Abbruch vor PIN-Eingabe Abbruch nach Eingabe falscher PIN Abbruch nach Kontosperrung durch falsche PIN Abbruch, weil PIN in initialem Zustand Account nicht für giropay geeignet Abbruch vor TAN-Eingabe Abbruch nach Eingabe falscher TAN 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 Benutzerseitiger Abbruch Keine Verbindung zum Bank-RZ möglich. 40 Konto des Käufers ist nicht für Onlinebanking freigeschaltet bzw. gesperrt Transaktion nicht erfolgreich abgeschlossen. VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4

15 6 Layout-Anpassung der Bezahlseite Wünschen Sie Anpassungen zur Dialogseite, so senden Sie bitte eine Mail an 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 Version 2.4

16 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 ######################################################################## # Konfiguration # ######################################################################## # Fehlerausgabe: 1 0 my $LOGTXT = "[".localtime(time())."]"." [pay.cgi]: "; my $DEBUG = 0; # Verbindungsparameter zum Payment my $PROT = ' my $PROTS = ' 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 = ' # 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 Version 2.4

17 ### 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 = $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 Version 2.4

18 7.2 Programmiersprache PHP Dialog-Transaktion <?php // Daten zum Service Dialog (Erklärung im Kapitel Schnittstellenparameter) $post = array( // Testsystem: " ", Livesystem: " " 'HAENDLERNR' => "10000xxxxx", // "Bestnr.1", Zuordnungsnummer immer eindeutig, hier Zeitstempel 'REFERENZNR' => time(), // "100" -> 1,- 'BETRAG' => "100", // "EUR" -> Währung ist Vertragsabhängig (EUR,USD,CHF,GBP...) 'WAEHRUNG' => "EUR", // Aufruf nach erfolgreicher Zahlung 'URLERFOLG' => " // Aufruf nach fehlgeschlagener Zahlung 'URLFEHLER' => " // Aufruf nach abgebrochener Zahlung (sinnvoll ist Einstieg in Warenkorb) 'URLABBRUCH' => " // Benachrichtigungs-URL zum Status der Zahlung // (HTTPS-Request von Paymentserver an Shop) 'URLANTWORT' => " // URL zu AGB des Händlers 'URLAGB' => " // fix: "KAUFEN" 'ZAHLART' => "KAUFEN", // fix: "DIALOG" 'SERVICENAME' => "DIALOG", // Wert vom Händler vergeben, der nur dem Händler und dem Paymentsystem // bekannt ist, wird bei Rückantwort mit übergeben 'ANTWGEHEIMNIS' => "mysecret", // Sprache, in der der Bezahldialog dem Kunden präsentiert wird: // Default wird die Browsersprache des Kunden ausgewertet, kann hier mit // den Werten "DE","EN","FR","IT","ES","NL","CS","PL" überschrieben werden //'SPRACHE' => "DE", // Default "0" (auch wenn keine Parameter übergeben werden), // Anzahl unterschiedlicher Bestellpositionen 'ARTIKELANZ' => '0', // zu welchem Zeitpunkt erfolgt die Rückmeldung vom Paymentserver // an den Shop ("ZHL","GTS","ALL") 'BENACHRPROF' => "ZHL", // Default "0" (auch wenn keine Parameter übergeben werden), // Anzahl der übertragenen Verwendungszweckzeilen 'VERWENDANZ' => "2", // Verwendungszweckzeile 1 (max. 25 Bytes) 'VERWENDUNG1' => substr("verwendungstext 1", 0, 25), // Verwendungszweckzeile 2 (max. 25 Bytes) 'VERWENDUNG2' => substr("verwendungstext 2", 0, 25), // Transaktionstyp kann nur ecommerce sein 'TSATYP' => "ECOM", // Auswahl = "N" und Brand = giropay erzeugt die Eingabeseite 'BRAND' => "GIROPAY", 'AUSWAHL' => "N"); // HTTP-Anfrage $query = http_build_query($post, '', '&'); // Zugangsparameter für Paymentserver / Produktion: " " : "Password" $auth = "10000xxxxx". ":". "xxxxxx"; // curl init & options $ch = curl_init(); // URL zum Payment-Server (Testsystem) curl_setopt($ch, CURLOPT_URL,' 'payinte.vr-epay.de/pbr/transaktion'); // Anmeldedaten für Paymentserver curl_setopt($ch, CURLOPT_USERPWD, $auth); curl_setopt($ch, CURLOPT_HTTP_VERSION, 1.1); // Datenübertragung als HTTP-POST-Anfrage curl_setopt($ch, CURLOPT_POST, 1); // Parameter (Inhalt) zum POST-Aufruf curl_setopt($ch, CURLOPT_POSTFIELDS, $query); curl_setopt($ch, CURLOPT_SSLVERSION, 3); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4

19 // 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 Version 2.4

20 8 Glossar Name Acquirer Acquirer Brand Autorisierung Autorisierungsanfrage BLZ Brand Browser CGI CSS CSV -Datei DTA ecommerce ELV Firewall HTML HTTP HTTP-GET HTTP-POST HTTPS Issuer IP -Adresse Paymentsystem SSL Beschreibung Kreditkartenautorisierer, z.b. CardProcess, WGZBank, DZ-Bank Beziehung des Acquirers zum Kreditkartenunternehmen Reservierung eines Kaufbetrages Anfrage für die Reservierung eines Kaufbetrages Bankleitzahl, eindeutige Institutskennung einer Bank Marke = Kreditkartenunternehmen (z.b. VISA, Mastercard, Diners etc.) Client-Programm, das Anforderungen an einen Web-Server leitet und die vom Server zurückgegebenen Informationen anzeigt CommonGatewayInterface = Schnittstelle, die es einem Browser erlaubt, über einen Server Programme auszuführen, dient bspw. der Formularverarbeitung im Internet, Cascading Style Sheets Dient der Beschreibung des Layouts von HTML-Seiten, Dateitransferformat für Dateien, durch Kommata getrennte Werte Datenträgeraustauschverfahren, Lastschriftdateien werden mit Hilfe dieses Verfahrens zwischen den Bankinstituten ausgetauscht. Electronic commerce => elektronischer Handel, geschäftliche Transaktionen über ein Computernetz wie das Internet Elektronisches Lastschriftverfahren für den bargeldlosen Zahlungsverkehr, Schutz eines internen Computer-Netzwerks vor Angriffen- /Zugriffen von außen wie z.b. dem Internet. Hyper Text Markup Language, Seitenbeschreibungssprache für Internetseiten Hyper Text Transmission Protokoll, Protokoll zur Übertragung von Daten im Internet. HTTP Methode, die angibt, das die Daten in der URI übertragen werden. HTTP Methode die angibt, dass die Daten vom Client zum Server im Content übertragen werden, bspw. mit Hilfe eines Formulars. Hyper Text Transmission Protokoll Secure, gibt an, dass die Daten zwischen dem Client und Server SSL - Verschlüsselt übertragen werden. Kartenherausgebende Bank Eindeutige Adresse im Internet, über die ein Computer ansprechbar ist. Abwicklung des Zahlungsverkehrs, digitales Zahlungssystem Secure Socket Layer; verschlüsselte Datenübertragung (Kanal) im Internet, VR-Pay virtuell Anbindungshandbuch - giropay Version 2.4