Inhaltsverzeichnis

giropay

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	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.

Workflow

SVG | PNG | TXT

Käufer/Kunde wählt giropay
Shop initiiert giropay Transaktion (Initialisierung)
GiroCheckout initialisiert Transaktion bei giropay
giropay übermittelt Ergebnis an GiroCheckout
Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
Shop sendet Redirect URL an Käufer-/Kundenbrowser
Käufer-/Kundenbrowser leitet zu giropay weiter, wo die Bankauswahl erfolgt (optional, falls nicht schon im Browser gespeichert)
giropay leitet dann an das Online-Banking der entsprechenden Bank weiter
Online-Banking zeigt Loginseite an
Käufer/Kunde autorisiert Transaktion
Bank führt Auftrag durch
Bank übermittelt Ergebnis an giropay
giropay übermittelt Ergebnis an GiroCheckout
GiroCheckout benachrichtigt Shop über Ausgang (Benachrichtigung)
Shop verarbeitet Ausgang
Shop sendet HTTP Statuscode an GiroCheckout
GiroCheckout sendet Rücksprung zum Händler an giropay
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.

Transaktion initiieren
Bezahlinformation an Händler übermitteln
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	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

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	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

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	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

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
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

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
	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

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	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

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 API

Seitenleiste

Integration

Erweiterungen

SDK

Andere

Inhaltsverzeichnis

giropay

Testdaten giropay

Workflow

API-Funktionen

Übersicht

Initialisierung einer giropay Zahlung

Anfrage

POST Parameter

Beispiel

Antwort

Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

SEPA-konforme Zeichen

cart-Element

Beispiel

Benachrichtigung über den Zahlungsausgang

Anfrage

GET Parameter

Antwort

Rückleitung des Kunden zum Händler

Anfrage

GET Parameter

Senderinformationen abrufen

API-Aufruf

POST-Parameter

Beispiel

Antwort

JSON-Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

Girocheckout API

Benutzer-Werkzeuge

Webseiten-Werkzeuge

Seitenleiste

Integration

Erweiterungen

SDK

Andere

Inhaltsverzeichnis

giropay

Testdaten giropay

Workflow

API-Funktionen

Übersicht

Initialisierung einer giropay Zahlung

Anfrage

POST Parameter

Beispiel

Antwort

Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

SEPA-konforme Zeichen

cart-Element

Beispiel

Benachrichtigung über den Zahlungsausgang

Anfrage

GET Parameter

Antwort

Rückleitung des Kunden zum Händler

Anfrage

GET Parameter

Senderinformationen abrufen

API-Aufruf

POST-Parameter

Beispiel

Antwort

JSON-Parameter

Beispiel im Erfolgsfall

Beispiel im Fehlerfall

Seiten-Werkzeuge