Integration
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
Grundlagen
FAQ
eps
giropay
iDEAL
Kreditkarte
Lastschrift
Bluecode
Maestro
Payment Page
PayPal
Tools
Fehlernummern
Ergebniscode
Testdaten
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.
Im Folgenden finden Sie die Testdaten sowohl für giropay ALT (der frühere giropay-Weg über das Online-Banking), als auch für giropay NEU (der frühere Paydirekt-Weg über Login und Passwort).
Welcher Weg (ALT und/oder NEU) Ihnen beim Testen zur Verfügung steht, hängt von Ihrem Vertrag ab. Wenden Sie sich bei Bedarf an Ihren Kundenberater, sollte nicht der erwartete Weg erscheinen. Bedenken Sie aber bitte auch, dass je nach Browser-Einstellung (der sich den Weg i.d.R. merkt) im ersten Augenblick ALT oder NEU angezeigt werden könnte und Sie über die Linkspfeile innerhalb der giropay-Seiten (NICHT zu verwechseln mit dem Browser-Zurück-Knopf!) zur Auswahl des gewünschten Weges gelangen können.
Verwenden Sie bitte die folgenden Logindaten (ändern Sie bitte dort nicht das Passwort und bedenken Sie, dass Ihre Testtransaktionen u.U. auch durch andere testende Kunden eingesehen werden können.):
Formularfeld | Eingabewert |
---|---|
Benutzername | Giropay_test |
Passwort | 8x5hHDs+98Q2W |
TAN (sollte sie abgefragt werden) | 123456 |
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) |
PIN | 1234 |
TAN‑Verfahren auswählen (nur bei Beträgen >= 20,00, s. unten) | „Smart-TAN plus optisch / USB“ oder „Smart-TAN photo“ |
TAN | 123456 |
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 EUR | Bei PSD2-Zahlung wird die Zahlung von PSD2-Bank sofort mit dem Status REJECTED abgelehnt. |
20,00 EUR | Bis 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 EUR | Bei 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 EUR | Bei PSD2-Zahlung mit TAN Authentifizierung wird nur Photo-TAN Verfahren ausgespielt |
21,01 EUR | Bei 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 EUR | Bei PSD2-Zahlung mit TAN Authentifizierung wird nur Push-TAN Verfahren ausgespielt |
22,01 EUR | Bei 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 EUR | Bei PSD2-Zahlung mit TAN Authentifizierung wird nur Flicker-TAN Verfahren ausgespielt |
23,01 EUR | Bei 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 EUR | Bei 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 EUR | Simuliert beim Start einer PSD2-TAN-Authentifizierung bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort. |
403,03 EUR | Simuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund EXPIRED als Antwort. |
403,04 EUR | Simuliert beim Abschicken einer PSD2-TAN bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort. |
403,05 EUR | Simuliert bei Auswahl einer PSD2-TAN-Authentifizierungsmethode bei einer Volksbank eine 403 (forbidden) mit dem Grund SERVICE_BLOCKED als Antwort. |
403,13 EUR | Simuliert bei einer PSD2-Statusabfrage bei einer Volksbank eine 403 (forbidden) mit dem Grund BLOCKED als Antwort. |
405,02 EUR | Simuliert bei einer PSD2-Löschung eine 405 (method not allowed) als Antwort. |
408,04 EUR | Simuliert bei einer PSD2-TAN-Authentifizierung eine lange Antwortzeit (für einen Timeout). |
422,00 EUR | Simuliert bei einer PSD2-Zahlung eine 422 (not processable) als Antwort. |
422,01 EUR | Simuliert bei einer PSD2-Authentifizierung eine 422 (not processable) als Antwort. |
503,00 EUR | Simuliert bei einer PSD2-Zahlung eine 503 (not available) als Antwort. |
503,01 EUR | Simuliert bei einer PSD2-Authentifizierung eine 503 (not available) als Antwort. |
Eine Reservierung ist zu verwenden, wenn die Erfüllung eines Auftrages zu einem späteren Zeitpunkt erfolgt, zum Zeitpunkt der Bestellung aber der Bestellwert für die vom Kunden vorgelegte Karte genehmigt werden soll (bei Kreditkarten-Transaktionen) bzw. die angegebene Bankverbindung geprüft werden soll (z.B. bei Paydirekt). Nach Ablauf dieses Zeitraumes wird die Reservierung entweder gebucht oder storniert.
Verkauf ist zu verwenden, wenn der Geschäftsvorgang abgeschlossen ist, also z. B. ein Warenkorb angeboten, bestellt und an den Kunden ausgeliefert wurde. Das Zahlungsmittel des Kunden wird in Höhe des Betrags belastet.
Wie im Workflow dargestellt, gibt es mehrere API-Aufrufe während einer giropay Transaktion.
Im Folgenden werden die API-Felder und Aufrufe näher erläutert.
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.
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler
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). |
type | Optional | String(4) | Transaktionsart (siehe Transaktionsarten) SALE = Verkauf wird sofort gebucht (default) AUTH = Reservierung des Betrags |
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 |
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
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.
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 |
hash : f56b5f91094cd22ace93b76ef250aa62
{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
hash : baf3c9b7217f362c29dd5cf6f098320c
{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
In SEPA-Zahlungen sind gemäß Anlage 3 des DFÜ-Abkommens nur Zeichen des eingeschränkten SWIFT Latin Character Set zugelassen:
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 |
[ { "name" : "Bobbycar", "ean" : "800001303", "quantity" : 3, "grossAmount" : 2599 }, { "name" : "Helm", "quantity" : 1, "grossAmount" : 1853 } ]
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.
URL: notifyUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
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 |
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. |
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.
URL: redirectUrl aus der Transaktionsinitialisierung
Bereitzustellen von: Händler
Aufzurufen von: GiroCheckout
Name | Pflicht | Type | Beschreibung | ||
---|---|---|---|---|---|
giropay | giropay-ID | giropay+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 |
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.
URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Bereitzustellen von: GiroCheckout
Aufzurufen von: Händler
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) |
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
Die Antwort besteht aus einem JSON Objekt. Das Feld rc liefert einen Fehlercode. Wird rc = 0 zurückgeliefert, enthalten die entsprechenden Felder die Senderinformationen.
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 |
hash : cde71b6b98e8dae709fdc1e17aef885f
{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
hash : f1d186103b8c4cb59c54ae7b987a9d4c
{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
Diese Transaktionen verweisen (referenzieren) auf 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
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.
Eine Erstattung ist zu verwenden, wenn dem Kunden eine vorangegangene Zahlung komplett oder teilweise erstattet werden soll.
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 | |
---|---|---|---|---|
CAPTURE | REFUND | |||
merchantId | Ja | Ja | Integer | Händler-ID eines giropay-Projekts |
projectId | Ja | Ja | Integer | Projekt-ID eines giropay-Projekts |
merchantTxId | Ja | Ja | String(255) | Eindeutige Transaktions-ID des Händlers. Zulässige Zeichen: beliebige Buchstaben (inkl. sprachl. Sonderzeichen), 0-9, Zeichen & = + , : ; . _ ! ? # / |
amount | Ja | Ja | Integer | Betrag oder Teilbetrag, zwischen 1 und 5000000 (also min. 1 Cent, max. 50000 EUR), bei Refund zwischen 1 und 10000000 (max. 100000 EUR). Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent, Penny |
currency | Ja | Ja | String(3) | Währung der Transaktion, gemäß ISO 4217. EUR = Euro |
purpose | Ja | Ja | String(37) | Verwendungszweck der Transaktion. Diese Information erscheint auf der Abrechnung. |
reference | Ja | Ja | String(36) | GiroCheckout Transaktions-ID der zugrundeliegenden AUTH-Transaktion. |
merchantReconciliationReferenceNumber | Optional | Optional | String(30) | Zusatzinformation für die Zahlungszuordnung, die im Verwendungszweck angezeigt wird. |
final | Optional | Boolean | NUR CAPTURE. Letzter CAPTURE auf eine Reservierung. Danach kann auf die referenzierte Reservierung kein weiterer CAPTURE mehr erstellt werden. | |
kassenzeichen | Optional | String(255) | NUR CAPTURE. 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 | Ja | String(32) | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=10000" \ -d "currency=EUR" \ -d "purpose=Beispiel-Capture" \ -d "reference=dd724940-5e86-4072-8442-2c2ba2aebc79" \ -d "final=true" \ -d "hash=e4e57b71b094d7fa197374f4fbdd4ca9" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/capture
Die Antwort besteht aus einem JSON Objekt. Das Feld resultPayment liefert einen Fehlercode zurück. Wird resultPayment = 4000 zurückgeliefert, wurde die Transaktion erfolgreich durchgeführt. Sie bekommen als Antwort eine Transaktionsnummer zurück.
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(36) | Zahlungsabwickler Transaktions-ID |
amount | Ja | Integer | Bei Dezimalwährungen den Betrag in der kleinsten Währungseinheit angeben, z.B. Cent |
currency | Ja | String(3) | Währung |
resultPayment | Ja | Integer | Ergebnis der Zahlung |
hash | Ja | String(32) | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
hash : 36dc1f4622d0c1260fe5da76fe83fbd3
{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
hash : c7dcb2d7d5e6719c6a51d81705bfc3af
{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
Stornieren ist zu verwenden, wenn eine akzeptierte Transaktion nicht ausgeführt werden soll.
URL VOID: https://payment.girosolution.de/girocheckout/api/v2/transaction/void
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 & = + , : ; . _ ! ? # / |
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 |
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
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.
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(36) | GiroCheckout Transaktions-ID der zugrundeliegenden Ursprungstransaktion |
merchantTxId | Ja | String(255) | Händler Transaktions-ID |
backendTxId | Ja | String(36) | 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 |
{"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":""}
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}