Benutzer-Werkzeuge

Webseiten-Werkzeuge


Übersetzungen dieser Seite:
girocheckout:directdebit:start

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

KundeShopGiroCheckoutZahlungsabwickler1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 (c)2016 by GiroSolution AG

  1. Käufer wählt Zahlart Lastschrift aus
  2. Shop initiiert Lastschriftzahlung (Initialisierung)
  3. GiroCheckout initialisiert Transaktion bei Zahlungsabwickler
  4. Zahlungsabwickler übermittelt Ergebnis an GiroCheckout
  5. Shop bekommt Rückmeldung über Initialisierungsausgang (bei Fehler ist Transaktion beendet)
  6. Shop sendet Redirect URL an Kundenbrowser
  7. Kundenbrowser leitet zum Zahlungsabwickler weiter
  8. Zahlungsabwickler zeigt Zahlformular an
  9. Kunde autorisiert Transaktion
  10. Zahlungsabwickler führt Transaktion durch
  11. Zahlungsabwickler übermittelt Ergebnis an GiroCheckout
  12. GiroCheckout benachrichtigt Shop über Transaktionsausgang (Benachrichtigung)
  13. Shop verarbeitet Transaktionsausgang
  14. Shop sendet HTTP Statuscode an GiroCheckout
  15. GiroCheckout sendet Rücksprung zum Händler an Zahlungsabwickler
  16. Kunde klickt „Zurück zum Shop“ (Rücksprung)

Lastschriftzahlung ohne Formularservice

KundeShopGiroCheckoutBank1 2 3 4 5 6 (c)2013 by GiroSolution AG

  1. Käufer wählt Zahlart Lastschrift aus und gibt seine Kontodaten (IBAN) ein
  2. Shop sendet Lastschriftzahlung an GiroCheckout (Lastschrift ohne Formularservice)
  3. GiroCheckout reicht Zahlung bei Bank ein
  4. Bank gibt Ausgang der Zahlung an GiroCheckout weiter
  5. GiroCheckout leitet Antwort an Händler weiter
  6. 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.

  1. Transaktion initiieren
  2. Kontoabfrage beim Käufer
  3. Bezahlinformation an Händler übermitteln
  4. 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.

  1. 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 = dä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
mandateReferenceOptional 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

ShopGiroCheckoutAbwickler1 2 3 4 (c)2016 by GiroSolution AG

  1. Shop sendet referenzierende Transaktion
  2. GiroCheckout leitet Transaktion zum Abwickler
  3. Abwickler übermittelt Ergebnis an GiroCheckout
  4. 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

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 weitere Informationen zurück.

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"}
girocheckout/directdebit/start.txt · Zuletzt geändert: 2024/06/04 21:21

Seiten-Werkzeuge