Girocheckout API

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Zuletzt angesehen: • giropay

Seitenleiste

Einführung

Integration

Grundlagen
FAQ

eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Paydirekt
Payment Page
PayPal

Tools

Fehlernummern
Ergebniscode
Testdaten

Erweiterungen

UATP
Vertriebspartner
Risikoprüfung
Formularservice

SDK

PHP SDK
Java SDK
.NET SDK

Andere

API Changelog
Plugins Changelog

Impressum
Datenschutz
S-Public Services GmbH

Übersetzungen dieser Seite:
girocheckout:giropay:start

Inhaltsverzeichnis

giropay

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.

Testdaten giropay

Bitte verwenden Sie für Tests ausschließlich das u.a. giropay Testinstitut!

Formularfeld Eingabewert
Bank giropay Testbank
IBAN DE48499999601234567890
VR-NetKey / Alias(beliebiger Wert)
PIN1234
TAN‑Verfahren auswählen (nur bei Beträgen >= 20,00, s. unten)„Smart-TAN plus optisch / USB“ oder „Smart-TAN photo“
TAN123456

Besondere Beträge

Das Verhalten der Transaktion kann über die Checkoutsumme (Magic-Numbers) gesteuert werden (s.u.). Für die Integration von giropay in einen Shop oder eine Behörde ist vor allem wichtig, dass die u.a. Beträge eine Sonderbehandlung haben und somit bei Nichtbeachtung unerwartete Testergebnisse produzieren können.

Betrag Reaktion
2,00 EURBei PSD2-Zahlung wird die Zahlung von PSD2-Bank sofort mit dem Status REJECTED abgelehnt.
20,00 EURBis zu diesem Betrag wird keine TAN Authentifizierung erwartet, bei genau 20 Euro wird die Auswahl der TAN-Verfahren noch zusätzlich ausgespielt (ohne dass eine TAN eingegeben werden muss)
20,02 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Photo-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 21,00€ verhalten. Bei Auswahl des TAN-Verfahrens wird dann festgelegt, dass keine TAN-Eingabe notwendig ist (EXEMPTED)
21,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Photo-TAN Verfahren ausgespielt
21,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Photo-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 21,00€ verhalten.
22,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Push-TAN Verfahren ausgespielt
22,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Push-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 22,00€ verhalten.
23,00 EURBei PSD2-Zahlung mit TAN Authentifizierung wird nur Flicker-TAN Verfahren ausgespielt
23,01 EURBei PSD2-Zahlung mit TAN Authentifizierung wird das Flicker-TAN Verfahren sowie zwei nicht unterstützte TAN-Verfahren ausgespielt. Für den Nutzer sollte sich diese Magic Number analog zu 23,00€ verhalten.
23,45 EURBei PSD2-Zahlung mit TAN Authentifizierung wird keine automatische Status-Änderung für Push-, Photo- und Flicker-TAN passieren. Der SCA-Status und der Transaktion-Status müssen im testportal per paymentId manuell gesetzt werden.
403,01 EURSimuliert beim Start einer PSD2-TAN-Authentifizierung bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,03 EURSimuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund EXPIRED als Antwort.
403,04 EURSimuliert beim Abschicken einer PSD2-TAN bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,05 EURSimuliert bei Auswahl einer PSD2-TAN-Authentifizierungsmethode bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort.
403,13 EURSimuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund BLOCKED als Antwort.
405,02 EURSimuliert bei einer PSD2-Löschung eine 405 (method not allowed) als Antwort.
408,04 EURSimuliert bei einer PSD2-TAN-Authentifizierung eine lange Antwortzeit (für einen Timeout).
422,00 EURSimuliert bei einer PSD2-Zahlung eine 422 (not processable) als Antwort.
422,01 EURSimuliert bei einer PSD2-Authentifizierung eine 422 (not processable) als Antwort.
503,00 EURSimuliert bei einer PSD2-Zahlung eine 503 (not available) als Antwort.
503,01 EURSimuliert bei einer PSD2-Authentifizierung eine 503 (not available) als Antwort.

Workflow

Käufer/KundeShopGiroCheckoutgiropayOnline-Banking1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 (c)2022 by GiroSolution AG

  1. Käufer/Kunde wählt giropay
  2. Shop initiiert giropay Transaktion (Initialisierung)
  3. GiroCheckout initialisiert Transaktion bei giropay
  4. giropay übermittelt Ergebnis an GiroCheckout
  5. Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
  6. Shop sendet Redirect URL an Käufer-/Kundenbrowser
  7. Käufer-/Kundenbrowser leitet zu giropay weiter, wo die Bankauswahl erfolgt (optional, falls nicht schon im Browser gespeichert)
  8. giropay leitet dann an das Online-Banking der entsprechenden Bank weiter
  9. Online-Banking zeigt Loginseite an
  10. Käufer/Kunde autorisiert Transaktion
  11. Bank führt Auftrag durch
  12. Bank übermittelt Ergebnis an giropay
  13. giropay übermittelt Ergebnis an GiroCheckout
  14. GiroCheckout benachrichtigt Shop über Ausgang (Benachrichtigung)
  15. Shop verarbeitet Ausgang
  16. Shop sendet HTTP Statuscode an GiroCheckout
  17. GiroCheckout sendet Rücksprung zum Händler an giropay
  18. Käufer/Kunde klickt „Zurück zum Shop“ (Rücksprung)

API-Funktionen

Übersicht

Wie im Workflow dargestellt, gibt es mehrere API-Aufrufe während einer giropay Transaktion.

  1. Transaktion initiieren
  2. Bezahlinformation an Händler übermitteln
  3. Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst oder automatisch nach einigen Sekunden)

Im Folgenden werden die API-Felder und Aufrufe näher erläutert.

Initialisierung einer giropay Zahlung

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.

Anfrage

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

POST Parameter
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(19) 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(100) Vorname des Addressaten, Pflicht bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen: Alle Buchstaben (UTF-8, auch ausländisch), 0-9, die Zeichen .-!#$%&'*+/=?^_’`´{|}~"(),:;<>@[] , außerdem Leerzeichen und Zeilenumbruch.
shippingAddresseLastName (s. Beschr.) String(100) Nachname des Addressaten, Pflicht bei Warenkorbtypen PHYSICAL, DIGITAL und MIXED, optional bei ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCompany Optional String(100) Firmenname. Zulässige Zeichen s. shippingAddresseLastName.
shippingAdditionalAddressInformation Optional String(100) Addresszusatz. Zulässige Zeichen s. shippingAddresseLastName.
shippingStreet Optional String(100) Straße des Addressaten. Zulässige Zeichen s. shippingAddresseLastName.
shippingStreetNumber Optional String(10) Hausnummer des Addressaten. Zulässige Zeichen s. shippingAddresseLastName.
shippingZipCode (s. Beschr.) String(10) PLZ des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCity (s. Beschr.) String(100) Ort des Addressaten. Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT. Zulässige Zeichen s. shippingAddresseLastName.
shippingCountry (s. Beschr.) String(2) Ländercode (nach ISO 3166-1). Pflicht bei Warenkörben der Typen PHYSICAL und MIXED, optional bei DIGITAL, ANONYMOUS_DONATION und AUTHORITIES_PAYMENT.
shippingEmail (s. Beschr.) String(255) 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. Zulässige Zeichen s. shippingAddresseLastName.
deliveryType Optional String(12) 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(2048) URL, an die der Kunde nach der Zahlung geschickt werden soll.
urlNotify Ja String(2048) URL, an die der Zahlungsausgang gemeldet werden soll.
kassenzeichen Optional String(255) 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 sind alle UTF-8-Zeichen.
giropayCustomerId Optional String(20) Kundennummer, max. Länge: 20
hash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren
Beispiel
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

Antwort

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.

Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String(255) zusätzliche Informationen im Fehlerfall
reference Optional String(36) eindeutige GiroCheckout Transaktions-ID
redirect Optional String(2048) Redirect URL zur Weiterleitung des Kunden an sein Online Banking
HEADER Parameter
hash Ja String(32) HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort
Beispiel im Erfolgsfall

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
Beispiel im Fehlerfall

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}

SEPA-konforme Zeichen

In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:

  • a b c d e f g h i j k l m n o p q r s t u v w x y z
  • A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
  • 0 1 2 3 4 5 6 7 8 9
  • ' : ? , - ( + . ) /
  • Leerzeichen

cart-Element

JSON Array mit item Objekten

Name Pflicht Type Beschreibung
name Ja String(100) Artikelname
ean Optional String(100) Die Internationale Artikel Nummer (EAN bzw. GTIN)
quantity Ja Integer 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
Beispiel
[ {
    "name" : "Bobbycar",
    "ean" : "800001303",
    "quantity" : 3,
    "grossAmount" : 2599
  }, {
    "name" : "Helm",
    "quantity" : 1,
    "grossAmount" : 1853
  } ]

Benachrichtigung über den Zahlungsausgang

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.

Anfrage

URL: notifyUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
gcReference Ja String(36) GiroCheckout Transaktions-ID
gcMerchantTxId Ja String(255) Händler Transaktions-ID
gcBackendTxId Ja String(36) Zahlungsabwickler Transaktions-ID
gcAmount Ja Integer bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent
gcCurrency Ja String(3) Währung
gcResultPayment Ja Integer/String(1) String „0“ oder numerischer Ergebniscode der giropay Zahlung
gcHash Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Antwort

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.

Rückleitung des Kunden zum Händler

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.

Anfrage

URL: redirectUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout

GET Parameter
Name Pflicht Type Beschreibung
giropaygiropay-IDgiropay+giropay-ID
gcReference Ja Ja Ja String(36) GiroCheckout Transaktions-ID
gcMerchantTxId Ja Ja Ja String(255) Händler Transaktions-ID
gcBackendTxId Ja Ja Ja String(36) 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(3) Währung
gcResultPayment Ja Ja Integer/String(1) String „0“ oder numerischer Ergebniscode der giropay Zahlung
gcHash Ja Ja Ja String(32) HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Senderinformationen abrufen

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.

API-Aufruf

URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

POST-Parameter
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)
Beispiel
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

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode. Wird rc = 0 zurückgeliefert, enthalten die entsprechenden Felder die Senderinformationen.

JSON-Parameter
Name Pflicht Type Beschreibung
rc Ja Integer Fehlernummer
msg Ja String(255) zusätzliche Informationen im Fehlerfall
accountholder Optional String(255) Inhaber des Absenderkontos
iban Optional String(36) IBAN des Absenderkontos
bic Optional String(11) BIC des Absenderkontos
HEADER Parameter
hash Ja String(32) HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort
Beispiel im Erfolgsfall

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
Beispiel im Fehlerfall

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
girocheckout/giropay/start.txt · Zuletzt geändert: 2023/11/16 20:57

Seiten-Werkzeuge