Integration
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Paydirekt
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Paydirekt
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
giropay kann ausschließlich mit der Währung EURO verwendet werden.
Wichtiger Hinweis
In den nächsten Monaten stellen wir voraussichtlich schrittweise unsere Unterstützung für die bisherige giropay-Schnittstelle (s. alte giropay-Beschreibung) ein. Danach gilt AUSSCHLIEßLICH die hier beschriebene neue Schnittstelle. Falls Sie umsteigen, beachten Sie bitte unseren Migrationsleitfaden auf unserer giropay Übersichtsseite. Dort finden Sie auch einen Vergleich der alten und neuen Schnittstelle.
Änderung an der API
Folgende Änderung an der API wird in diesen Tagen durchgeführt:
Der Parameter merchantReconciliationReferenceNumber wird ersetzt durch merchantOrderReferenceNumber, welcher weiterhin optional ist aber nur 20 Zeichen lang sein darf. Man beachte auch die unten angegebenen Restriktionen bzgl. der zugelassenen Zeichen.
Bitte verwenden Sie für Tests ausschließlich das u.a. giropay Testinstitut!
Formularfeld | Eingabewert |
---|---|
Bank | Testbank / Test- und Spielbank AG |
Sie landen in einer Simulation, wo Sie die an Ihre Anwendung zurück gesandten Felder einsehen und sogar bearbeiten können. Wenn Sie nichts ändern und nur „Ausführen“ klicken, ist die Transaktion erfolgreich.
Transaktionsausgang
ResultCode | Antwortcode | Hinweis |
---|---|---|
4000 | erfolgreiche Transaktion | Die Transaktion wurde erfolgteich abgeschlossen. |
4502 | abgebrochene Transaktion | Eine abgebrochene Transaktion wird durch Klicken des Links „Zurück zur Bankensuche“ gefolgt von „Zahlung abbrechen“ ausgelöst. |
Wie im Workflow dargestellt, gibt es mehrere API-Aufrufe während einer giropay Transaktion.
Im Folgenden werden die API-Felder und Aufrufe näher erläutert.
Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunslink (redirect) an den Händler übermittelt. Der übermittelte Link führt zum Onlinebanking des Käufers. Er muss an diese URL weitergeleitet werden. Dies kann durch einen HTTP-Redirect-Header, eine HTML-Seite mit entsprechendem Meta-Tag oder Javascript erfolgen.
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Bereitzustellen von: GiroCheckout
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 |
merchantTxId | Ja | String(255) | eindeutige Transaktions-ID des Händlers. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # / |
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 EUR = Euro |
purpose | Ja | String(27) | Verwendungszweck der giropay Überweisung. Zulässige Zeichen entsprechend dem SEPA-Zeichensatz (s. SEPA-konforme Zeichen). |
shoppingCartType | Optional | String | Typ des Warenkorbs. Folgende Werte sind zulässig: PHYSICAL = Alle Waren im Warenkorb sind physischer Natur, DIGITAL = Alle Waren im Warenkorb sind digitaler Natur (benötigen also keinen Versand), MIXED = Der Warenkorb enthält sowohl physische als auch digitale Waren (dies ist der Default-Wert, wenn der Parameter nicht angegeben wird), ANONYMOUS_DONATION = Es handelt sich um eine anonyme Spende (keine Adressdaten notwendig), AUTHORITIES_PAYMENT = Es handelt sich um eine Behördenzahlung (keine Adressdaten notwendig) |
shippingAddresseFirstName | (s. Beschr.) | String | Vorname des Addressaten, Pflicht bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. |
shippingAddresseLastName | (s. Beschr.) | String | Nachname des Addressaten, Pflicht bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. |
shippingCompany | Optional | String | Firmenname |
shippingAdditionalAddressInformation | Optional | String | Addresszusatz |
shippingStreet | Optional | String | Straße des Addressaten |
shippingStreetNumber | Optional | String | Hausnummer des Addressaten |
shippingZipCode | (s. Beschr.) | String | PLZ des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. |
shippingCity | (s. Beschr.) | String | Ort des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. |
shippingCountry | (s. Beschr.) | String(2) | Ländercode (ISO 3166-1). Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. |
shippingEmail | (s. Beschr.) | String | Email-Adresse des Käufers. Pflicht bei digitalen Warenkörben (DIGITAL), bei allen anderen optional. |
merchantOrderReferenceNumber | Optional | String(20) | Zusatzinformation für die Zahlungszuordnung, die im Verwendungszweck angezeigt wird (nur bei type=SALE). Zulässige Zeichen entsprechend dem SEPA-Zeichensatz (s. SEPA-konforme Zeichen). |
cart | Optional | JSON String | alle Elemente des Warenkorbs im folgenden Format: s. weiter unten: Beschreibung cart-Element |
deliveryType | Optional | String | Typ des Versands. Folgende Werte sind zulässig: STANDARD = Die Ware wird an eine normale Postadresse versandt (dies ist der Default-Wert, wenn der Parameter nicht angegeben wird), PACKSTATION = Die Waren werden an eine Selbstbedienungs-Packstation für Pakete geliefert, STORE_PICKUP = Die Waren werden in der Geschäftsstelle des Verkäufers abhgeholt. |
urlRedirect | Ja | String | URL, an die der Kunde nach der Zahlung geschickt werden soll. |
urlNotify | Ja | String | URL, an die der Zahlungsausgang gemeldet werden soll. |
kassenzeichen | Optional | String(30) | Optionales Feld für die Übergabe eines Kassenzeichens. Dieses wird dann im GiroCockpit in den Transaktionsdetails angezeigt (und bald auch exportiert) und es kann dort auch danach gesucht werden. Zulässige Zeichen entsprechend dem SEPA-Zeichensatz (s. SEPA-konforme Zeichen). |
hash | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "shoppingCartType=DIGITAL" \ -d "shippingAddresseFirstName=Max" \ -d "shippingAddresseLastName=Mustermann" \ -d "shippingEmail=mmuster@example.com" \ -d "urlRedirect=http://www.ihre-domein.de/girocheckout/redirect" \ -d "urlNotify=http://www.ihre-domein.de/girocheckout/notify" \ -d "hash=2017e2f4d694e24a3396d83a20b3828b" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/start
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. Es wird als Antwort eine Transaktionsnummer und die redirectURL zum Online Banking des Käufers zurückgeliefert.
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
rc | Ja | Integer | Fehlernummer |
msg | Ja | String | zusätzliche Informationen im Fehlerfall |
reference | Optional | String | eindeutige GiroCheckout Transaktions-ID |
redirect | Optional | String | Redirect URL zur Weiterleitung des Kunden an sein Online Banking |
HEADER Parameter | |||
hash | Ja | String | HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort |
hash : f56b5f91094cd22ace93b76ef250aa62
{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
hash : baf3c9b7217f362c29dd5cf6f098320c
{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:
JSON Array mit item Objekten
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
name | Ja | String | Artikelname |
ean | Optional | String | Die Internationale Artikel Nummer (EAN bzw. GTIN) |
quantity | Ja | Dezimal | Menge des Artikels (Ganzzahl) |
grossAmount | Optional | Integer | Brutto- und Einzelbetrag des Artikels (also Preis pro Stück, bei mehreren), bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny |
[ { "name" : "Bobbycar", "ean" : "800001303", "quantity" : 3, "grossAmount" : 2599 }, { "name" : "Helm", "quantity" : 1, "grossAmount" : 1853 } ]
Der Ausgang einer giropay-Zahlung wird an die im urlNotify-Parameter angegebene URL übermittelt. Diese Rückmeldung dient dazu, dem Händler den Ausgang der Transaktion mitzuteilen. Durch diese Information kann der Transaktionsstatus beim Händler geändert werden.
Der Zahlungausgang der giropay Transaktion steht im Feld gcResultPayment.
Am Ende des Bezahlvorganges auf giropay-Seite findet nach 5 Sekunden eine Weiterleitung an den Shop statt.
URL: notifyUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
Name | Pflicht | Type | Beschreibung | ||
---|---|---|---|---|---|
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 | |||
gcCurrency | Ja String | Währung | |||
gcResultPayment | Ja Integer | Ergebniscodes der giropay Zahlung | |||
gcHash | Ja String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
Als Antwort auf den GET-Request wird einer der folgenden HTTP Statuscodes erwartet.
HTTP Statuscode | Beschreibung |
---|---|
200 (OK) | Die Benachrichtigung wurde korrekt verarbeitet. |
400 (Bad Request) | Der Händler hat die Benachrichtigung nicht verarbeitet, möchte aber auch nicht erneut benachrichtigt werden. |
Alle anderen | Die Benachrichtigung wird max. 10 Mal alle 30 Minuten wiederholt, bis der Händler den HTTP Statuscode 200 oder 400 zurückgibt. |
Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Händler kommen. Nach 5 Sekunden erfolgt aber auch eine automatische Weiterleitung.
URL: redirectUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
Name | Pflicht | Type | Beschreibung | ||
---|---|---|---|---|---|
giropay | giropay-ID | giropay+giropay-ID | |||
gcReference | Ja | Ja | Ja | String | GiroCheckout Transaktions-ID |
gcMerchantTxId | Ja | Ja | Ja | String | Händler Transaktions-ID |
gcBackendTxId | Ja | Ja | Ja | String | Zahlungsabwickler Transaktions-ID |
gcAmount | Ja | Ja | Integer | bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent | |
gcCurrency | Ja | Ja | String | Währung | |
gcResultPayment | Ja | Ja | Integer | Ergebniscodes der giropay Zahlung | |
gcHash | Ja | Ja | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
Mit dieser Funktion können die Senderinformationen einer erfolgreich durchgeführten Transaktion abgerufen werden. Anhand der angegebenen Referenz wird Kontoinhaber, IBAN und BIC des Absenders geliefert. Diese Information kann dann für eine Rücküberweisung an den Zahler genutzt werden.
URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Bereitzustellen von: GiroCheckout
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 |
reference | Ja | String(36) | GiroCheckout Transaktions-ID |
hash | Ja | String(32) | HMAC MD5 hash über alle Werte des Aufrufs (siehe hash generieren) |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \ -d "hash=246d1fa2ed97ecff895de974c560f9ec" \ https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode. Wird rc = 0 zurückgeliefert, enthalten die entsprechenden Felder die Senderinformationen.
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
rc | Ja | Integer | Fehlernummer |
msg | Ja | String | zusätzliche Informationen im Fehlerfall |
accountholder | Optional | String | Inhaber des Absenderkontos |
iban | Optional | String | IBAN des Absenderkontos |
bic | Optional | String | BIC des Absenderkontos |
HEADER Parameter | |||
hash | Ja | String | HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort |
hash : cde71b6b98e8dae709fdc1e17aef885f
{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
hash : f1d186103b8c4cb59c54ae7b987a9d4c
{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}