Integration
Credit Card
Direct Debit
Bluecode
eps
giropay
iDEAL
Maestro
PayPal
Payment Page
Tools
Error codes
Result codes
Test data
This is an old revision of the document!
You can use this function to check if a bank supports the giropay payment method and allows payments and/or age verification. Please use this function prior to every transaction to make sure that the customer's bank supports the corresponding giropay transaction and is available.
URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus
To be provided by: GiroSolution AG
To be called by: Merchant
Name | Mandatory | Type | Description |
---|---|---|---|
merchantId | Yes | Integer | Merchant ID of a giropay project |
projectId | Yes | Integer | Project ID of a giropay project |
bankcode | Optional | String(8) | Bank code (Bankleitzahl) of the customer's bank to be checked |
bic | Optional | String(11) | BIC of the customer's bank to be checked |
hash | Yes | String(32) | HMAC MD5 hash on all the values of the function call. See generate hash |
For this check, either the bank code (Bankleitzahl) or the BIC of the customer's bank must be specified. If both are present, they must refer to the same bank.
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
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"}
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
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"}
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
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"}
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
{"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"}
The reply is a JSON object. If rc = 0 is returned, a giropay transaction may be carried through with this bank. Please note the parameters payment and verifyAge. Additionally, the bank code and the bank name are returned.
Name | Mandatory | Type | Description |
---|---|---|---|
rc | Yes | Integer | Error code |
msg | Yes | String | Additional information in case of error |
bankcode | Optional | Integer | Bank code (Bankleitzahl) |
bic | Optional | String | BIC, if available |
bankname | Optional | String | Bank name |
payment | Optional | Integer | 0 = giropay payment not supported 1 = giropay payment supported |
verifyAge | Optional | Integer | 0 = giropay age verification not supported 1 = giropay age verification supported |
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
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"}
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
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"}
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
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"}
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
{"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"}
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
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"}
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
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"}
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
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"}
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
{"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"}
You send the transaction data and receive a link (redirect URL) as a reply. Afterwards, you send your customer a redirection to that URL. This may be done through an HTTP redirect header, an HTML page with a corresponding meta tag or Javascript. The actual payment processing takes place as the customer logs into his online banking platform and confirms the prefilled transfer form there by entering a TAN. The notification of your application about the payment outcome is done via a GET request sent by GiroCheckout to the URL specified in the urlNotify parameter.
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
To be provided by: GiroSolution AG
To be called by: Merchant
Name | Mandatory | Type | Description |
---|---|---|---|
merchantId | Yes | Integer | Merchant ID of a giropay project |
projectId | Yes | integer | Project ID of a giropay project |
merchantTxId | Yes | String(255) | Merchant's unique transaction ID |
amount | Yes | Integer | Amount in Cents If kind = 2, then specify amount as 0 |
currency | Optional | String(3) | Currency of the transaction EUR = Euros (default) |
purpose | Yes | String(27) | Reason for payment to be included in giropay transfer |
bankcode | Optional | String(8) | Bank code of the customer's bank Only supported until January 31st, 2014 |
bankaccount | Optional | String(10) | Customer's account number (for a possible refund) Only supported until January 31st, 2014 |
bic | Optional | String(11) | BIC of the customer's bank |
iban | Optional | String(34) | Customer's IBAN |
info[1..5]Label | Optional | String(30) | Additional information for the giropay transfer pages (field name) |
info[1..5]Text | Optional | String(80) | Additional information for the giropay transfer pages (information) |
urlRedirect | Yes | String | URL to which the customer is to be redirected after the payment |
urlNotify | Yes | String | URL to which the payment outcome is to be notified |
hash | Yes | String | HMAC MD5 hash on all the values of the function call. See generate hash |
Using the info parameters, you may display additional information on the giropay transfer pages. A maximum of 5 elements is possible. Each information is comprised of a label and the information itself.
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 ist ein JSON Objekt. Wenn rc = 0 zurückgeliefert wird, sind die Parameter reference und redirect gesetzt. Leiten Sie den Kunde bitte an die redirect URL weiter.
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 |
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"}
Nach Beendigung der giropay Zahlung/Altersverifikation erhalten Sie einen GET-Request an die im Parameter urlNotify angegebene URL. Bitte nutzen Sie diese Meldung, um z.B. den Status der Bestellung zu ändern und eine Bestellbestätigung zu verschicken. Aufgrund des giropay Ablaufes findet eine Rückleitung des Kunden an die urlRedirect nicht automatisch statt, sondern nur nach einem Klick durch den Kunden.
URL: notifyUrl aus dem Transaktionsstart
Bereitzustellen von: Händler
Aufzurufen von: GiroSolution AG
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
gcReference | Ja | String | Eindeutige GiroCheckout Transaktions-ID |
gcMerchantTxId | Ja | String | Transaktions-ID des Händlers |
gcBackendTxId | Ja | String | giropay Transaktions-ID |
gcAmount | Ja | Integer | Betrag in Cent |
gcCurrency | Ja | String | Währung |
gcResultPayment | Optional | Integer | Ergebnis der giropay Zahlung |
gcResultAVS | Optional | Integer | Ergebnis der giropay Altersverifikation |
gcHash | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |
Als Antwort auf den GET-Request wird einer der folgendes HTTP Statuscodes erwartet.
HTTP Statuscode | Beschreibung |
---|---|
200 (OK) | Die Benachrichtigung wurde korrekt verarbeitet. |
400 (Bad Request) | Der Shop 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 Shop den HTTP Statuscode 200 oder 400 zurückgibt. |
Nach Beendigung der giropay Zahlung kann der Kunde über einen Link zurück zum Shop kommen. Diese Rückleitung erfolgt nicht automatisch.
URL: redirectUrl aus dem Transaktionsstart
Bereitzustellen von: Händler
Aufzurufen von: GiroSolution AG
Name | Pflicht | Type | Beschreibung |
---|---|---|---|
gcReference | Ja | String | Eindeutige GiroCheckout Transaktions-ID |
gcMerchantTxId | Ja | String | Transaktions-ID des Händlers |
gcBackendTxId | Ja | String | giropay Transaktions-ID |
gcAmount | Ja | Integer | Betrag in Cent |
gcCurrency | Ja | String | Währung |
gcResultPayment | Optional | Integer | Ergebnis der giropay Zahlung |
gcResultAVS | Optional | Integer | Ergebnis der giropay Altersverifikation |
gcHash | Ja | String | HMAC MD5 hash über alle Werte des Aufrufs. Siehe hash generieren |