Benutzer-Werkzeuge

Webseiten-Werkzeuge


Übersetzungen dieser Seite:
girocheckout:giropay:start

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

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

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 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/giropay/start.txt · Zuletzt geändert: 2023/02/10 21:48

Seiten-Werkzeuge