Integration
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
Dies ist eine alte Version des Dokuments!
In diesem Dokument werden alle Abläufe und Schnittstellen beschrieben, die zur Integration der GiroCheckout Payment Page notwendig sind.
Diese Payment Page ermöglicht eine viel einfachere Anbindung von Shops an GiroCheckout, ohne dass innerhalb des Shops alle Zahlungsarten einzeln konfiguriert werden müssen. Die GiroCheckout Payment Page bietet dem Endkunden alle beim Händler verfügbaren Zahlungsarten zur Auswahl an und initialisiert die entsprechende Zahlung nach Auswahl.
Beispiel
Es werden die folgenden Zahlarten unterstützt:
Eine Payment Page muss initialisiert werden, damit eine Payment-Page-URL generiert wird. Diese Payment-Page-URL ist das Ergebnis einer erfolgreichen Payment-Page-Initialisierung. Der Endkunde muss anschließend auf diese URL weitergeleitet werden.
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler
Sollte bei Ihnen der Bedarf bestehen, in Ihrer Payment- oder Spenden-Page nur bestimmte Projekte aus Ihrem GiroCockpit zu verwenden und dies in Ihrer Implementierung auswählen zu lassen, können Sie diese Abfrage verwenden, um sich Ihre Projekte zurückliefern zu lassen.
URL: https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
Bereitzustellen von: GiroSolution AG
Aufzurufen von: Händler
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
merchantId | Ja | Integer | Händler-ID eines giropay Projekts |
projectId | Ja | Integer | Projekt-ID eines giropay Projekts |
hash | Ja | String(32) | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/projects
Die Antwort enthält ein JSON Objekt. Wenn rc = 0 zurückgeliefert wird, enthält das Element projects die zur Verfügung stehenden Projekte.
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
rc | Ja | Integer | Fehlernummer |
msg | Ja | String | Zusätzliche Informationen im Fehlerfall |
projects | Optional | Array | Liste der GiroCockpit-Projekte bestehend aus der Id (id), dem Projektnamen (name), der Nummer der zugehörigen Zahlungsart (paymethod) und dem Modus (mode) = TEST oder LIVE. |
HEADER Parameter | |||
hash | Ja | String | HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort |
{"projects":[{"id":"12345","name":"iDEAL - ICEPAY","paymethod":"12","mode":"LIVE"},{"id":"12346","name":"giropay","paymethod":"1","mode":"TEST"},{"id":"12347","name":"Kreditkarte","paymethod":"11","mode":"TEST"}],"rc":0,"msg":""}
URL https://payment.girosolution.de/girocheckout/api/v2/paypage/init
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
merchantId | Ja | Integer | Händler-ID eines Paypage-Projekts |
projectId | Ja | Integer | Projekt-ID eines Paypage-Projekts |
merchantTxId | Ja | String(255) | Eindeutige Transaktions-ID des Händlers |
amount | Ja | Integer | Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny |
currency | Ja | String(3) | Währung der Transaktion, gemäß ISO 4217. EUR = Euro |
purpose | Ja | String(27) | Verwendungszweck der Transaktion. Diese Information erscheint auf der Kartenabrechnung bzw. dem Kontoauszug. Es sind nur SEPA-konforme Zeichen zulässig (s. SEPA-konforme Zeichen). Wenn pagetype=2 und projectlist nicht leer, kann der Platzhalter {SPENDENPROJEKT} verwendet werden, der dann mit dem Namen des vom Kunden gewählten Projekts gefüllt wird. Der Inhalt dieses Feldes (erste 20 Zeichen) wird auch verwendet, um die orderid bei der Zahlungsart Paydirekt zu befüllen, wenn diese nicht explizit angegeben ist (s. Parameter orderid). |
description | Optional | String(120) | Beschreibung für die Bezahlung. Wird nur auf der Payment Page angezeigt. Zulässige Zeichen s. Zulässige Beschreibungszeichen |
pagetype | Optional | Integer | Typ der zu erzeugenden Bezahlseite: 0=normale API-Paypage (kompatibel zu früheren Paypages, Defaultwert), 1=Bezahlseite, 2=Spendenseite |
expirydate | Optional | String(10) | Verfallsdatum: Leer=Bezahlseite ist immer gültig, JJJJ-MM-TT=Datumsangabe im Format Jahr-Monat-Tag, bis zu diesem Datum ist die Bezahlseite gültig. Die Option 'once' ist deprecated, sollte also nicht mehr genutzt werden, weil sie in einer nächsten API-Version nicht mehr zur Verfügung stehen wird. Statt dessen, bitte single=2 verwenden. |
single | Optional | Integer | Steuert, ob und wie der Link wiederverwendet werden darf. 0 = Link is beliebig oft wiederholbar (default) 1 = Erlaubt nur einen einzigen Bezahlversuch für diesen Payment-Link, egal ob erfolgreich oder nicht 2 = Bezahlseite kann nur für eine erfolgreiche Bezahlung genutzt werden, danach ungültig. |
type | Optional | String(4) | Transaktionsart (siehe Transaktionsarten), SALE = Verkauf wird sofort gebucht (default), AUTH = Reservierung des Betrags (nicht bei allen Zahlarten verfügbar) |
locale | Optional | String(4) | Sprache der Payment Page de = deutsch (default) en = englisch |
paymethods | Optional | String | Kommaseparierte Liste der Zahlarten, die angezeigt werden sollen. Wird hier nichts angegeben, werden alle beim Händler unterstützen Zahlarten zur Auswahl angeboten. Jede Zahlungsart ist als Zahl anzugeben, s. Zahlungsarten |
payprojects | Optional | String | Kommaseparierte Liste der Projekt-IDs, deren zugehörige Zahlungsarten in der Payment Page verfügbar sein sollen. Wird hier nichts angegeben, werden alle Projekte des Händlers berücksichtigt. Die Projekt-Ids können entweder manuell im GiroCockpit oder über Aufruf der Funktion Projektabfrage ermittelt werden. |
organization | Optional | String(70) | Name des Anbieters der Bezahl- oder Spendenseite. Wenn nicht angegeben, wird der Name aus dem GiroCockpit verwendet. |
freeamount | Optional | Integer | Gibt an, ob der Anwender einen freien Betrag eingeben darf (=1) oder nicht (=0, Defaultwert). |
fixedvalues | Optional | String | JSON-codierter String, der einen Array der zur Auswahl stehenden Beträge enthält. z.B. '[„10000“,„20000“,„50050“]', alle Beträge sind in Cent anzugeben. Ist dieses Feld leer, wird der Inhalt des Amount-Feldes als einziger fester Wert verwendet. Enthält dieses Feld Werte, wird der Betrag im Feld Amount ignoriert! |
minamount | Optional | Integer | Mindestwert, wenn ein freier Betrag eingegeben werden darf, also freeamount=1 ist. Fehlt dieser Wert, ist der Default 1,00. |
maxamount | Optional | Integer | Maximalwert, wenn ein freier Betrag eingegeben werden darf, also freeamount=1 ist. |
orderid | Optional | String(20) | Wird nur bei Zahlungsart Paydirekt verwendet, wenn leer wird die orderid aus dem Purpose erzeugt. Es sind nur SEPA-konforme Zeichen zulässig (s. SEPA-konforme Zeichen) |
projectlist | Optional | String | JSON-codierter String, der einen Array der Projekte enthält (Strings=Projektnamen), für die auf dieser Spendenseite gespendet werden kann. Macht nur Sinn, wenn pagetype=2. |
pkn | Optional | String | Das Feld dient dazu eine erneute Transaktion, ohne erneute Eingabe der Kreditkarten- oder Lastschriftdaten, zu starten. create = neue Pseudo-Kartennummer für die verwendete Kreditkarte/Kontoverbindung generieren. |
test | Ja | Integer | 1 = Zahlarten im Test-Modus werden angezeigt 0 = Zahlarten im LIVE-Modus werden angezeigt |
paydirektShippingFirstName | Optional | String(100) | Vorname für die Lieferadresse (nur für paydirekt PHYSICAL-Bestellungen) |
paydirektShippingLastName | Optional | String(100) | Nachname für die Lieferadresse (nur für paydirekt PHYSICAL-Bestellungen) |
paydirektShippingZipCode | Optional | String(10) | Postleitzahl für die Lieferadresse (nur für paydirekt PHYSICAL-Bestellungen) |
paydirektShippingCity | Optional | String(100) | Ort für die Lieferadresse (nur für paydirekt PHYSICAL-Bestellungen) |
paydirektShippingCountry | Optional | String(2) | Ländercode (ISO 2-stellig) für die Lieferadresse (nur für paydirekt PHYSICAL-Bestellungen) |
successUrl | Optional | String | URL, an die der Kunde nach erfolgreicher Zahlung weitergeleitet wird. |
backUrl | Optional | String | URL, an die der Kunde weitergeleitet wird, wenn er auf Zurück klickt. |
failUrl | Optional | String | URL, an die der Kunde nach erfolgloser Zahlung weitergeleitet wird. |
notifyUrl | Optional | String | URL, an die in einer Server-to-Server-Verbindung die Payment Notification geschickt wird. |
hash | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:
Folgende Zeichen sind für den Beschreibungstext (Feld description) zulässig:
Dies sind die zulässigen Werten für die im Parameter paymethods anzugebenden Zahlungsarten:
ID | Zahlungsart |
---|---|
1 | giropay |
2 | eps |
6 | Lastschrift |
7 | Lastschrift mit Sperrdatei |
8 | Garantierte Lastschrift |
11 | Kreditkarte |
12 | iDEAL |
14 | PayPal |
23 | paydirekt |
27 | Sofort. |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "description=Fahrradleuchte klein" \ -d "type=SALE" \ -d "locale=de" \ -d "paymethods=1,2,6,11,14" \ -d "test=1" \ -d "successUrl=http://www.my-domain.de/girocheckout/success" \ -d "backUrl=http://www.my-domain.de/girocheckout/back" \ -d "failUrl=http://www.my-domain.de/girocheckout/fail" \ -d "notifyUrl=http://www.my-domain.de/girocheckout/notify" \ -d "hash=9d7cc3729790bfdbe68a7156bb4d386b" \ https://payment.girosolution.de/girocheckout/api/v2/paypage/init
Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Transaktion erfolgreich initialisiert. Sie bekommen als Antwort eine Referenznummer für die Payment Page und die redirectURL zum Formular zurück.
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
rc | Ja | Integer | Fehlernummer |
msg | Ja | String | zusätzliche Informationen im Fehlerfall |
reference | Optional | String | eindeutige Payment Page ID |
url | Optional | String | URL zur Payment Page, an die der Kunde weitergeleitet werden muss. |
HEADER Parameter | |||
hash | Ja | String | HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort |
hash : 6c4da0504e8e6a359c7f2df86cb5318d
{"reference":"4f88b6c8-6209-4c96-a450-b6de22633f6b","url":"http:\/\/pay.girosolution.de\/v1\/paypage\/en\/EG-ddvXSrAHmXRClBeamKGAyzXU-uAYbNYFLQ3uz_zj_J4rYCb0GIrWIQ-H_g8h3_-yf3WvSenh2Dg6TLhmTAA","rc":0,"msg":""}
hash : f55ce87e132ebb7eb20004c6b186ce09
{"reference":null,"redirect":null,"rc":5030,"msg":"Betrag ungültig"}
Der Ausgang einer Transaktion wird auf 2 parallelen Wegen übermittelt. Der Notification und dem Redirect.
Der erste Kommunikationsweg ist eine Host-to-Host-Meldung an die im notifyUrl-Parameter angegebene URL. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen, auch wenn der Käufer nicht mehr auf die Shopseite zurückkehrt. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden. Der Zahlungsausgang einer Transaktion steht im Feld gcResultPayment.
URL: notifyUrl aus der Payment-Page-Initialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
Methode: GET
Name | Pflicht | Typ | Beschreibung |
---|---|---|---|
gcPaymethod | Ja | Integer | ID der Zahlungsart der Transaktion |
gcType | Ja | String | Transaktionsart: SALE AUTH |
gcProjectId | Ja | String | GiroCheckout Projekt-Id, über die die Transaktion abgewickelt wurde. |
gcReference | Ja | String | GiroCheckout Transaktions-ID |
gcMerchantTxId | Ja | String | Händler Transaktions-ID |
gcBackendTxId | Ja | String | Zahlungsabwickler Transaktions-ID |
gcAmount | Ja | Integer | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny |
gcCurrency | Ja | String | Währung |
gcResultPayment | Ja | Integer | Ergebniscodes der Zahlung |
gcPkn | Optional | String | Pseudokartennummer, wenn pkn aktiv |
gcCardnumber | Optional | String | Maskierte Kreditkartennummer, wenn pkn aktiv |
gcCardExpDate | Optional | String | Gültigkeitsdatum der Kreditkarte im Format Monat/Jahr, wenn pkn aktiv |
gcAccountHolder | Optional | String | Kontoinhaber bei Lastschrift, wenn pkn aktiv |
gcIban | Optional | String | IBAN bei Lastschrift, wenn pkn aktiv |
gcHash | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
Der zweite Kommunikationsweg ist die Rückleitung des Käufers in seinem Browser auf eine der drei bei der Initialisierung angegebenen Weiterleitungsadressen:
Alle 3 URLs werden mit der POST-Methode aufgerufen und erhalten als Parameter die selben Werte wie oben beim Notify angegeben.