Inhaltsverzeichnis

Lastschrift

Lastschrift

Eine Lastschrift kann ausschließlich mit der Währung EURO verwendet werden.

Testdaten

Kontonummer	Bankleitzahl	Antwortcode	Ergebnisart	Hinweis
1234567890	12345678	4000	erfolgreiche Transaktion	Eine erfolgreiche Transaktion wird ausgelöst
1212121211	12345679	4051	nicht erfolgreiche Transaktion	Eine erfolglose Transaktion wird ausgelöst

IBAN	Antwortcode	Ergebnisart	Hinweis
DE87123456781234567890	4000	erfolgreiche Transaktion	Eine erfolgreiche Transaktion wird ausgelöst
DE23690516200012345600	5027	erfolglose Transaktion	Eine erfolglose Transaktion wird ausgelöst

Workflow

Die Integration einer Zahlung per Lastschrift kann auf zwei Wege erfolgen.

Sind die Kontodaten (IBAN oder Kontonummer und Bankleitzahl) des Käufers bekannt, kann die Transaktion über eine direkte Schnittstelle abgewickelt weden.
Alternativ kann der Formularservice verwendet werden.

Lastschriftzahlung mit Formularservice

SVG | PNG | TXT

Käufer wählt Zahlart Lastschrift aus
Shop initiiert Lastschriftzahlung (Initialisierung)
GiroCheckout initialisiert Transaktion bei Zahlungsabwickler
Zahlungsabwickler übermittelt Ergebnis an GiroCheckout
Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
Shop sendet Redirect URL an Kundenbrowser
Kundenbrowser leitet zum Zahlungsabwickler weiter
Zahlungsabwickler zeigt Zahlformular an
Kunde autorisiert Transaktion
Zahlungsabwickler führt Transaktion durch
Zahlungsabwickler übermittelt Ergebnis an GiroCheckout
GiroCheckout benachrichtigt Shop über Transaktionsausgang (Benachrichtigung)
Shop verarbeitet Transaktionsausgang
Shop sendet HTTP Statuscode an GiroCheckout
GiroCheckout sendet Rücksprung zum Händler an Zahlungsabwickler
Kunde klickt „Zurück zum Shop“ (Rücksprung)

Lastschriftzahlung ohne Formularservice

SVG | PNG | TXT

Käufer wählt Zahlart Lastschrift aus und gibt seine Kontodaten (IBAN) ein
Shop sendet Lastschriftzahlung an GiroCheckout (Lastschrift ohne Formularservice)
GiroCheckout reicht Zahlung bei Bank ein
Bank gibt Ausgang der Zahlung an GiroCheckout weiter
GiroCheckout leitet Antwort an Händler weiter
Händler informiert Kunde über Zahlungsausgang

API-Funktionen

Übersicht

Wie im Workflow mit Formularservice dargestellt gibt es mehrere API-Aufrufe während einer Lastschrift-Transaktion.

Transaktion initiieren
Kontoabfrage beim Käufer
Bezahlinformation an Händler übermitteln
Bezahlinformation mit Käuferbrowserweiterleitung zurück zum Händler (durch Käufer nach Zahlung ausgelöst)

Wie im Workflow Direkt dargestellt gibt es einen API-Aufruf während einer Lastschrift-Transaktion.

Transaktion durchführen

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

Initialisierung einer Lastschrifttransaktion mit Formularservice

Durch eine erfolgreiche Initialisierung wird eine Referenznummer erstellt sowie ein Weiterleitunslink (redirect) an den Händler übermittelt. Der übermittelte Link führt zum Bezahlformular. Der Kunde 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 Lastschrift Projekts
projectId	Ja	integer	Projekt-ID eines Lastschrift 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, gemäß ISO 4217 EUR = Euro
purpose	Ja	String(50)	Verwendungszweck der Lastschrift Transaktion. Diese Information erscheint auf dem Kontoauszug.
type	Optional	String(4)	Transaktionsart (siehe Transaktionsarten) SALE = Verkauf wird sofort gebucht (default) AUTH = Reservierung des Betrags
locale	Optional	String(4)	Sprache des Lastschriftformulars. de = deutsch (default) en = englisch es = spanisch fr = französisch it = italienisch pt = portugiesisch nl = niederländisch cs = tschechisch sv = schwedisch da = dänisch pl = polnisch spde = deutsch Spende spen = englisch Spende de_DE_stadtn = deutsch Kommunen
mobile	Optional	Boolean	Definiert, ob das Formular für Smartphones und mobile Browser optimiert angezeigt werden soll. 0 = nein (default) 1 = ja
mandateReference	Optional	String(35)	Mandatsreferenz Wird keine angegeben, wird eine eindeutige Mandatsreferenz generiert. Die Mandatsreferenz ist in der Antwort enthalten. Ziffern: 0 – 9 Buchstaben: A – Z und a – z Sonderzeichen: ' : \ , ? - + . ( ) /
mandateSignedOn	Optional	String(10)	Datum im Format JJJJ-MM-TT, wann das SEPA-Lastschriftmandat erteilt wurde. Wenn kein Datum angegeben wird, wird das aktuelle Datum verwendet.
mandateReceiverName	Optional	String(70)	Names des Empfängers, der im SEPA Mandat verwendet wurde. Falls nichts angegeben, wird der in den Stammdaten hinterlegte Firmenname verwendet. Ziffern: 0 – 9 Buchstaben: A – Z und a – z Sonderzeichen: & / = + , : ; . _ - ! ?
mandateSequence	Optional	Integer	Sequenztyp der SEPA-Lastschrift. Falls nichts angegeben, wird eine Einmalzahlung angenommen. 1 = Einmalzahlung (default) 2 = erste Zahlung einer Sequenz 3 = Folgezahlung 4 = letzte Zahlung einer Sequenz
pkn	Optional	String(50)	Das Feld dient dazu eine erneute Transaktion, ohne erneute Eingabe der Bankverbindung, zu starten. create = neue Pseudo-Kartennummer für die verwendete Bankverbindung generieren [Pseudo-Kartennummer] = Kartennumer der zu verwendenden Bankverbindung (siehe Pseudokartennummer) Für diese Funktion ist eine separate Einrichtung erforderlich und es fallen einmalige Einrichtungsgebühren an.
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.
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=52dd237537dce" \
     -d "amount=100" \
     -d "currency=EUR" \
     -d "purpose=Lastschrift Transaktion" \
     -d "mandateReference=12345abcde" \
     -d "mandateSignedOn=2014-01-01" \
     -d "mandateReceiverName=mein Shop" \
     -d "mandateSequence=1" \
     -d "urlRedirect=https://www.your-domain.de/girocheckout/redirect-directdebit" \
     -d "urlNotify=https://www.your-domain.de/girocheckout/notify-directdebit" \
     -d "hash=f7ee5f58036e459bf42002fa89279041" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/start

Antwort

Die Antwort enthält ein 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 Transaktionsnummer und die redirectURL zum Zahlformular zurück.

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
mandateReference	Optional	String(35)	eindeutige Mandatsreferenz-ID
redirect	Optional	String(2048)	Redirect URL zur Weiterleitung des Kunden zum Zahlungsformular
HEADER Parameter
hash	Ja	String(32)	HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort

Beispiel im Erfolgsfall

{"mandateReference":"12345abcde","reference":"928f3815-7e66-4650-aab5-a0edf92d41e6","redirect":"https://testmerch.directpos.de/web-api/SSLPayment.po?n=vjqRec7hizjYXLE1t9272wi96FXqHKQQw5XD7RwwyiFH","rc":"0","msg":""}

Beispiel im Fehlerfall

hash : 0afc26687fa0dcb2440a19107c273a7d

{"mandateReference":null,"reference":null,"redirect":null,"rc":5010,"msg":"Sprache ungültig"}

Benachrichtigung über den Zahlungsausgang

Der Ausgang einer Zahlung wird, an die im urlNotify Paramter 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 einer Transaktion steht im Feld gcResultPayment.

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(22)	Zahlungsabwickler Transaktions-ID
gcAmount	Ja	Integer	bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency	Ja	String(3)	Währung
gcResultPayment	Ja	Integer	Ergebniscodes der 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 Zahlung kann der Kunde über einen Link zurück zum Händler kommen. Eine Weiterleitung erfolgt erst, wenn der Käufer den „Abbrechen“ oder „Zurück zum Shop“ Button drückt. Diese Rückleitung erfolgt nicht automatisch.

Anfrage

URL: redirectUrl 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(22)	Zahlungsabwickler Transaktions-ID
gcAmount	Ja	Integer	bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
gcCurrency	Ja	String(3)	Währung
gcResultPayment	Ja	Integer	Ergebnis der Zahlung
gcHash	Ja	String(32)	HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Durchführen einer Lastschrifttransaktion ohne Formularservice

Sie übermitteln die Transaktionsdaten und erhalten direkt das Ergebnis der Lastschrift Zahlung.

Anfrage

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

POST Parameter

Name	Pflicht	Type	Beschreibung
merchantId	Ja	Integer	Händler-ID eines Lastschrift Projekts
projectId	Ja	integer	Projekt-ID eines Lastschrift 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, gemäß ISO 4217 EUR = Euro
purpose	Ja	String(50)	Verwendungszweck der Lastschrift Transaktion. Diese Information erscheint auf dem Kontoauszug.
type	Optional	String(4)	Transaktionsart (siehe Transaktionsarten) SALE = Verkauf wird sofort gebucht (default) AUTH = Reservierung des Betrags
bankcode	Optional	String(8)	Bankleitzahl Plicht, wenn keine IBAN angegeben ist.
bankaccount	Optional	String(10)	Kontonummer Plicht, wenn keine IBAN angegeben ist.
iban	Optional	String(34)	IBAN-Nummer des Käufers ohne Leerzeichen Plicht, wenn bankcode und bankaccount nicht angegeben sind.
accountHolder	Optional	String(27)	Kontoinhaber
mandateReference	Optional	String(35)	Mandatsreferenz Wird keine angegeben, wird eine eindeutige Mandatsreferenz generiert. Die Mandatsreferenz ist in der Antwort enthalten. Ziffern: 0 – 9 Buchstaben: A – Z und a – z Sonderzeichen: ' : \ , ? - + . ( ) /
mandateSignedOn	Optional	String(10)	Datum im Format JJJJ-MM-TT, wann das SEPA-Lastschriftmandat erteilt wurde. Wenn kein Datum angegeben wird, wird das aktuelle Datum verwendet.
mandateReceiverName	Optional	String(70)	Names des Empfängers, der im SEPA Mandat verwendet wurde. Falls nichts angegeben, wird der in den Stammdaten hinterlegte Firmenname verwendet. Ziffern: 0 – 9 Buchstaben: A – Z und a – z Sonderzeichen: & / = + , : ; . _ - ! ?
mandateSequence	Optional	Integer	Sequenztyp der SEPA-Lastschrift. Falls nichts angegeben, wird eine Einmalzahlung angenommen. 1 = Einmalzahlung (default) 2 = erste Zahlung einer Sequenz 3 = Folgezahlung 4 = letzte Zahlung einer Sequenz
pkn	Optional	String(50)	Das Feld dient dazu eine erneute Transaktion, ohne erneute Eingabe der Bankverbindung, zu starten. create = neue Pseudo-Kartennummer für die verwendete Bankverbindung generieren [Pseudo-Kartennummer] = Kartennumer der zu verwendenden Bankverbindung (siehe Pseudokartennummer) Für diese Funktion ist eine separate Einrichtung erforderlich und es fallen einmalige Einrichtungsgebühren an.
urlNotify	Optional	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.
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=Lastschrift Transaktion" \
     -d "iban=DE23690516200012345600" \
     -d "accountHolder=Max Mustermann" \
     -d "mandateReference=12345abcde" \
     -d "mandateSignedOn=2014-01-01" \
     -d "mandateReceiverName=mein Shop" \
     -d "mandateSequence=1" \
     -d "hash=28caaa92da143ed83cef2e73213ff162" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/payment

Antwort

Die Antwort ist ein JSON Objekt. Wenn rc = 0 zurückgeliefert wird, war der Aufruf fehlerfrei und das Ergebnis der Lastschrift Transaktion ist dem Parameter resultPayment zu entnehmen.

Parameter

Name	Pflicht	Type	Beschreibung
rc	Ja	Integer	Antwortcode
msg	Ja	String(255)	zusätzliche Informationen im Fehlerfall
reference	Optional	String(32)	eindeutige GiroCheckout Transaktions-ID
backendTxId	Optional	String(22)	Zahlungsabwickler Transaktions-ID
mandateReference	Optional	String(35)	Mandatsreferenz der SEPA Lastschrift
resultPayment	Optional	Integer	Ergebnis der Lastschrift Zahlung
HEADER Parameter
hash	Ja	String(32)	HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort

Beispiel im Erfolgsfall

hash : 6c8cef797350587f535c8dc65333cf15

{"reference":"d01068e3-50a3-48f5-8185-70835e631809","backendTxId":"1196323_01","mandateReference":"12345abcde","resultPayment":"4000","rc":0,"msg":""}

Beispiel im Fehlerfall

hash : 02e0057b4055ab71715d48a4bde7240d

{"reference":"8e0a2a4f-ffee-4ca0-954e-e619038e46ac","backendTxId":"1196322_01","mandateReference":"12345abcde","resultPayment":"5100","rc":0,"msg":""}

Pseudo-Kartennummer (PKN)

Für diese Funktion ist eine separate Einrichtung erforderlich und es fallen einmalige Einrichtungsgebühren an.

Eine Pseudo-Kartennummer ist eine Referenz auf eine vom Käufer verwendete Bankverbindung (Kontoinhaber, Kontonummer, Bankleitzahl / IBAN). Durch diese Referenz wird dem Händler ermöglicht, eine bereits verwendete Bankverbindung zur Auswahl anzubieten. Wird die Nummer bei der Initiierung einer Lastschrift-Transaktion mitgeschickt, wird die Bankverbindung im Zahlformular vorausgefüllt oder die Zahlung direkt durchgeführt (je nach Wunsch, also mit oder ohne Formularservice).

Pseudo-Kartennummer Informationen abfragen

Durch diese Funktion werden PKN-Informationen bereitgestellt. Sie liefert als Ergebnis eine PKN sowie die hinterlegte Bankverbindung (Kontoinhaber, Kontonummer, Bankleitzahl / IBAN), welche für eine bereits durchgeführte Transaktion verwendet wurde.

Anfrage

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

POST Parameter

Name	Pflicht	Type	Beschreibung
merchantId	Ja	Integer	Händler-ID eines Lastschrift Projekts
projectId	Ja	Integer	Projekt-ID eines Lastschrift Projekts
reference	Ja	String(36)	Eindeutige 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=6d2d31b6-c23f-47c4-8f6c-1a0495f35f0f" \
     -d "hash=dc1686b621c9cc15bd271390c694258d" \
     https://payment.girosolution.de/girocheckout/api/v2/creditcard/pkninfo

Antwort

Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode zurück. Wird rc = 0 zurückgeliefert, wurde die Anfrage erfolgreich abgesetzt. Die Antwort enthält die PKN-Nummer, den Kontoinhaber und die Bankverbindung.

Parameter

Name	Pflicht	Type	Beschreibung
rc	Ja	Integer	Fehlernummer
msg	Ja	String(255)	zusätzliche Informationen im Fehlerfall
pkn	Ja	String(50)	Pseudo-Kartennummer
holder	Ja	String(255)	Kontoinhaber
bankcode	Ja	String(8)	Bankleitzahl
bankaccount	Ja	String(10)	Kontonummer
iban	Ja	String(36)	IBAN
HEADER Parameter
hash	Ja	String(32)	HMAC MD5 hash über alle Werte der Rückmeldung. Siehe hash der Rückantwort

Beispiel im Erfolgsfall

{"pkn":"ad5c386b38cc9aeb839705d1d10da499","cardnumber":"411111******1111","expiremonth":"2","expireyear":"2016","rc":0,"msg":""}

Beispiel im Fehlerfall

{"pkn":null,"cardnumber":null,"expiremonth":null,"expireyear":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}

Weitere Transaktionsarten

Diese Transaktionen referenzieren eine zuvor erfolgte Transaktion. Die Transaktion basiert auf einer Server zu Server Kommunikation und erfordert keine Kundenaktion (Eingabe von Daten).

Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler

Workflow

SVG | PNG | TXT

Shop sendet referenzierende Transaktion
GiroCheckout leitet Transaktion zum Abwickler
Abwickler übermittelt Ergebnis an GiroCheckout
Shop bekommt Rückmeldung über Transaktionsausgang (Benachrichtigung)

Buchung (CAPTURE)

Beim Buchen (capture) wird das Kundenkonto mit einem Betrag belastet, die Gutschrift erfolgt auf das Händlerkonto. Dieses Modell setzt voraus, dass der zugrundeliegende Geschäftsvorfall abgeschlossen ist, z.B. wurde ein Warenkorb angeboten, bestellt und an den Kunden ausgeliefert.

Bedingung: nur reservierte Transaktionen können gebucht werden
Betrag ⇐ Reservierungsbetrag
Buchung von Teilbeträgen möglich

Erstattung (REFUND)

Eine Erstattung ist zu verwenden, wenn dem Kunden eine vorangegangene Zahlung komplett oder teilweise erstattet werden soll.

Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
- Buchung (capture)
- Reservierung + Buchung (sale)
Betrag ⇐ Transaktionsbetrag der vormals gesendeten Transaktion

POST Parameter

URL CAPTURE: https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
URL REFUND: https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

Name	Pflicht	Type	Beschreibung
merchantId	Ja	Integer	Händler-ID eines Lastschrift Projekts
projectId	Ja	Integer	Projekt-ID eines Lastschrift 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, gemäß ISO 4217. EUR = Euro
purpose	Optional	String(27)	Verwendungszweck der Erstattung. Diese Information erscheint auf dem Kontoauszug.
reference	Ja	String(36)	GiroCheckout Transaktions-ID, für die eine Buchung oder Erstattung durchgeführt 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.
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 "reference=f84e606f-817d-439f-ada1-d37e85cb6314" \
     -d "hash=256b7bb16edbc76871c830d0d623c303" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/refund

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. Sie bekommen als Antwort eine Transaktionsnummer und die redirectURL zum Formular service zurück.

Parameter

Name	Pflicht	Type	Beschreibung
rc	Ja	Integer	Antwortcode
msg	Ja	String(255)	zusätzliche Informationen im Fehlerfall
reference	Ja	String(36)	GiroCheckout Transaktions-ID
merchantTxId	Ja	String(255)	Händler Transaktions-ID
backendTxId	Ja	String(22)	Zahlungsabwickler Transaktions-ID
amount	Ja	Integer	bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency	Ja	String(3)	Währung
resultPayment	Ja	Integer	Ergebnis der Transaktion
hash	Ja	String(32)	HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Beispiel im Erfolgsfall

hash : 17790db9c9745b94e1b8db1b22cc7876

{"reference":"e897ef6c-cfd0-4c5e-a932-b15ba24c15cb","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}

Beispiel im Fehlerfall

hash : 98d9d8b133acf97eb92601fa72d804a0

 {"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","rc":"5100","msg":""}

Stornierung (VOID)

Stornieren ist zu verwenden, wenn eine akzeptierte Transaktion nicht ausgeführt werden soll.

Bedingung: kann nur auf folgende Transaktionstypen angewendet werden:
- Reservierung (solange keine Buchung erfolgte und Reservierung nicht abgelaufen ist)
- Reservierung/Buchung (nur am selben Tag)
- Erstattung (nur am selben Tag)

POST Parameter

URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Name	Pflicht	Type	Beschreibung
merchantId	Ja	Integer	Händler-ID eines Lastschrift Projekts
projectId	Ja	Integer	Projekt-ID eines Lastschrift Projekts
merchantTxId	Ja	String(255)	eindeutige Transaktions-ID des Händlers. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # /
reference	Ja	String(36)	GiroCheckout Transaktions-ID, für die eine Stornierung durchgeführt werden soll
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 "reference=fb70602d-c137-4413-8432-7dcc69a9d891" \
     -d "hash=edb7459114db25c2991d1783d4ab5388" \
     https://payment.girosolution.de/girocheckout/api/v2/transaction/void

Antwort

Parameter

Name	Pflicht	Type	Beschreibung
rc	Ja	Integer	Fehlernummer
msg	Ja	String(255)	zusätzliche Informationen im Fehlerfall
reference	Ja	String(36)	GiroCheckout Transaktions-ID
referenceParent	Ja	String	GiroCheckout Transaktions-ID der zugrundeliegenden Ursprungstransaktion
merchantTxId	Ja	String(255)	Händler Transaktions-ID
backendTxId	Ja	String(22)	Zahlungsabwickler Transaktions-ID
amount	Ja	Integer	Stornierter Betrag, bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny
currency	Ja	String(3)	Währung
resultPayment	Ja	Integer	Ergebnis der Transaktion
hash	Ja	String(32)	HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren

Beispiel im Erfolgsfall

{"reference":"ef27303f-87b3-465e-9c39-fabfb749d253","referenceParent":"5a101478-df14-4a79-86af-f743784c2c24","merchantTxId":"58e39be91fce8","backendTxId":"1226723_01","amount":"100","currency":"EUR","resultPayment":"4000","rc":0,"msg":""}

Beispiel im Fehlerfall

{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

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.

API-Aufruf

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

POST-Parameter

Name	Pflicht	Type	Beschreibung
merchantId	Ja	Integer	Händler-ID eines Lastschrift-Projekts
projectId	Ja	Integer	Projekt-ID eines Lastschrift-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/directdebit/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"}