Table of Contents

giropay / giropay-ID

giropay can only process EURO payments.

Workflow

buyer/ customermerchantGiroCheckoutgiropayonline banking1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 (c)2021 by GiroSolution AG

  1. buyer/ customer chooses giropay/ giropay-ID
  2. merchant initialises giropay/giropay-ID request (initialise giropay payment)
  3. GiroCheckout initialises request at giropay
  4. giropay submits response to GiroCheckout
  5. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  6. merchant sends redirect URL to buyer/ customer
  7. the buyer's/ customer's browser redirects to giropay where the bank is selected (optional, only if bank is not already stored in browser)
  8. giropay redirects to the customer's online banking
  9. bank shows login page
  10. buyer/ customer authorises giropay payment/ giropay-ID
  11. bank processes reqest
  12. bank submits result to giropay
  13. giropay submits result to GiroCheckout
  14. GiroCheckout notifies merchant about the result (payment result notification)
  15. merchant processes result
  16. merchant sends HTTP Statuscode to GiroCheckout
  17. GiroCheckout sends merchants redirect page to giropay
  18. buyer/customer clicks “Zurück zum Shop” and gets redirected to the merchant (buyer redirection)

API functions

Overview

As shown in the workflow there are different API calls during a giropay transaction or giropay-ID verification. A combinaion of giropay and giropay-ID is also possible.

  1. check bankstatus
  2. initialise transaction
  3. payment result notification to merchant
  4. buyer redirection to the merchant (triggered by buyer)

Check bankstatus

This call should not be used anymore. All giropay transactions now use an external bank selection form!

This API call checks if a bank supports the giropay payment method or giropay-ID verification. Therefore the BIC of the buyer's account has to be submitted. The response shows if the bank provides giropay or giropay-ID. It is recommended to do this prior to an initial payment, to make sure that the buyer's bank supports giropay.

API call

URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/bankstatus
provided by: GiroCheckout
called by: merchant

POST parameter
parameter mandatory type description
merchantId yes Integer Merchant ID of a giropay, giropay-ID or giropay-ID + giropay project
projectId yes Integer Project ID of a giropay, giropay-ID or giropay-ID + giropay project
bic yes String(11)the buyer's bank account BIC (8 or 11-digits), which schould be checked
hash yes String(32)HMAC MD5 hash over all API call params (see hash generation)
Example
transactionstart.request
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
transactionstart.response.true

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
transactionstart.response.false

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
senderinfo.request
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
senderinfo.response.true

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
senderinfo.response.false

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
capture.request
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
capture.response.true

hash : 36dc1f4622d0c1260fe5da76fe83fbd3 

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
capture.response.false

hash : c7dcb2d7d5e6719c6a51d81705bfc3af 

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
void.request
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
void.response.true
{"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":""}
void.response.false
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Reply

The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains rc = 0, the bank supports giropay. Additional information which feature of giropay is supported can be found in the giropay and giropay-ID parameters. There will also be additional information about the bank returned, if they are known.

JSON parameter
name mandatory type description
rc yes Integer error codes
msg yes String additional informationen about the response code
bankcode optional Integer bank code
bic optional String BIC
bankname optional String name of the bank
giropay optional Integer 0 = giropay payment is not supported
1 = giropay payment is supported
giropayid optional Integer 0 = giropay-ID and giropay-ID + giropay payment are not supported
1 = giropay-ID and giropay-ID + giropay payment are supported
HEADER parameter
hash yes String HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success
transactionstart.request
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
transactionstart.response.true

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
transactionstart.response.false

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
senderinfo.request
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
senderinfo.response.true

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
senderinfo.response.false

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
capture.request
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
capture.response.true

hash : 36dc1f4622d0c1260fe5da76fe83fbd3 

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
capture.response.false

hash : c7dcb2d7d5e6719c6a51d81705bfc3af 

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
void.request
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
void.response.true
{"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":""}
void.response.false
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}
Example in case of error
transactionstart.request
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
transactionstart.response.true

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
transactionstart.response.false

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
senderinfo.request
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
senderinfo.response.true

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
senderinfo.response.false

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
capture.request
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
capture.response.true

hash : 36dc1f4622d0c1260fe5da76fe83fbd3 

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
capture.response.false

hash : c7dcb2d7d5e6719c6a51d81705bfc3af 

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
void.request
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
void.response.true
{"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":""}
void.response.false
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

giropay issuer bank request

This call should not be used anymore. All giropay transactions now use an external bank selection form!

Returns a list which contains all supported giropay issuer banks. The buyer has to choose his one.

URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/issuer
provided by: GiroSolution AG
called by: Händler

POST parameter
name mandatory type description
merchantId yes Integer Merchant ID
projectId yes Integer Project ID
hash yes String(32)HMAC MD5 hash (see hash generation)
Example
transactionstart.request
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
transactionstart.response.true

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
transactionstart.response.false

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
senderinfo.request
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
senderinfo.response.true

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
senderinfo.response.false

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
capture.request
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
capture.response.true

hash : 36dc1f4622d0c1260fe5da76fe83fbd3 

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
capture.response.false

hash : c7dcb2d7d5e6719c6a51d81705bfc3af 

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
void.request
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
void.response.true
{"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":""}
void.response.false
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Reply

The reply contains an encoded JSON string. An response code is submitted in the field rc. If the response contains rc = 0, the request was successful.

JSON parameter
name mandatory type description
rc yes Integer error codes
msg yes String additional informationen about the response code
issuer optional Mixed list of all supported issuer banks containing bic as key and name
Example
transactionstart.request
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
transactionstart.response.true

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
transactionstart.response.false

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}
senderinfo.request
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
senderinfo.response.true

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
senderinfo.response.false

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}
capture.request
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
capture.response.true

hash : 36dc1f4622d0c1260fe5da76fe83fbd3 

{"reference":"ehd82947-5e86-4072-8442-2c2ba2ae74a","referenceParent":null,"merchantTxId":"123456","backendTxId":"5720d913a1338","amount":"100","currency":"EUR","resultPayment":4000,"rc":0,"msg":""}
capture.response.false

hash : c7dcb2d7d5e6719c6a51d81705bfc3af 

{"reference":null,"rc":5030,"msg":"Betrag ungültig"}
void.request
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
void.response.true
{"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":""}
void.response.false
{"reference":null,"referenceParent":null,"merchantTxId":null,"backendTxId":null,"amount":null,"currency":null,"resultPayment":null,"rc":5200,"msg":"Transaktion nicht akzeptiert"}

Initialize giropay payment

The initialization of a giropay can be processed in different ways. This will be distinguished just by the project id.

Towards a successful initialization you receive a reference number and an redirect link. The redirect link leads to the online banking account of the buyer's bank. He has to be redirected to his bank. This can be achieved by a HTTP-Redirect-Header, HTML page with an corresponding Meta-Tag or JavaScript redirect.

Request

URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: Merchant

POST parameter
Name Mandatory Type Description
giropaygiropay-IDgiropay+giropay-ID
merchantId yes yes yes Integer merchant ID of a giropay project
projectId yes yes yes integer project ID of a giropay project
merchantTxId yes yes yes String(255) unique transaction id of the merchant. Allowed characters: any letters (incl. language-specific special characters such as German Umlauts), 0-9, symbols & = + , : ; . _ ! ? # /
amount yes yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny
currency yes yes String(3) currency
EUR = Euro
purpose yes yes String(27) purpose
bic deprecated deprecated depcrecated String(11) This parameter must not be used anymore. All giropay transactions now use an external bank selection form! BIC (8 or 11-digits)
iban optional optional optional String(34) IBAN without whitespaces
The IBAN is usually not required anymore because it is selected during the process inside the customer's home banking apolication. The only exception is the combined account and age verification in one call. Here you must specify an IBAN.
info1Labeloptional optional optional String(30) additional information field which is shown on the payment form (label)
info1Text optional optional optional String(80) additional information field which is shown on the payment form (text)
info2Labeloptional optional optional String(30) additional information field which is shown on the payment form (label)
info2Text optional optional optional String(80) additional information field which is shown on the payment form (text)
info3Labeloptional optional optional String(30) additional information field which is shown on the payment form (label)
info3Text optional optional optional String(80) additional information field which is shown on the payment form (text)
info4Labeloptional optional optional String(30) additional information field which is shown on the payment form (label)
info4Text optional optional optional String(80) additional information field which is shown on the payment form (text)
info5Labeloptional optional optional String(30) additional information field which is shown on the payment form (label)
info5Text optional optional optional String(80) additional information field which is shown on the payment form (text)
urlRedirect yes yes yes String URL, where the buyer has to be sent after payment
urlNotify yes yes yes String URL, where the notification has to be sent after payment
kassenzeichen optional String Optional field that allows passing an additional reference/identifier for the transaction. This value is displayed inside GiroCockpit as part of the transaction details (and soon export) and a search for it is also supported there.
hash yes yes yes String HMAC MD5 hash (see hash generation)

Through the info parameter you can display additional information on the payment form of the bank. There are up to info 5 elements possible. One info element consists of one label and one infotext.

Example
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

Reply

The reply includes a JSON encoded string. The field rc contains the response code. If it is 0 the transaction was successfully initialised. The response also includes a transaction id and a redirect URL to the online banking account of the buyer's bank.

Parameter
name mandatory type description
rc yes Integer response code
msg yes String additional information about the response code
reference optional String unique GiroCheckout transaction ID
redirect optional String redirect URL to the buyer's online banking account
HEADER parameter
hash yes String HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : f56b5f91094cd22ace93b76ef250aa62 

{"reference":"9ce6c641-4082-4f75-ae54-333309febcc5","redirect":"https://giropay.starfinanz.de/ftg/a/go/07i2j1k00pp0u109biywcswh;jsessionid=B1D575F122ED8D4B4B4EB0F83E85897F","rc":"0","msg":""}
Example in case of error

hash : baf3c9b7217f362c29dd5cf6f098320c 

{"reference":null,"redirect":null,"rc":5033,"msg":"Währung ungütig"}

Notification about the payment result

The result of a initialised transaction will be submitted to the prior in the urlNotify parameter specified URL. This notification should be used to update the payment status in the merchant's system.

The result of a giropay payment is contained in the field gcResultPayment. If a giropay-ID or giropay-ID + giropay transaction was initialised the result of the age verification can be found in the field gcResultAVS.

Due to the internal giropay process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click.

Request

URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout

GET parameter
name mandatory type description
giropaygiropay-IDgiropay+giropay-ID
gcReference yes yes yes String unique GiroCheckout transaction ID
gcMerchantTxId yes yes yes String merchant transaction ID
gcBackendTxId yes yes yes String payment processor transaction ID
gcAmount yes yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny
gcCurrency yes yes String currency
gcResultPayment yes yes Integer payment result codes
gcResultAVS yes yes Integer age verification result codes
gcObvName optional optional String Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID)
gcHash yes yes yes String HMAC MD5 hash (see hash generation)

Reply

As a reply to the GET request, one of the following HTTP status codes is expected.

HTTP status code description
200 (OK) The notification was processed correctly.
400 (Bad Request) The merchant did not process the notification and does not wish to be notified again.
all others The notification is repeated no more than 10 times every 30 minutes until the merchant returns the status code 200 or 400.

Redirection of the customer to merchant

After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.

Request

URL: redirectUrl of the prior init transaction call
Provided by: merchant
Called by: GiroCheckout

GET parameter
name mandatory type description
giropaygiropay-IDgiropay+giropay-ID
gcReference yes yes yes String unique GiroCheckout transaction ID
gcMerchantTxId yes yes yes String merchant transaction ID
gcBackendTxId yes yes yes String payment processor transaction ID
gcAmount yes yes Integer if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny
gcCurrency yes yes String currency
gcResultPayment yes yes Integer payment result codes
gcResultAVS yes yes Integer age verification result codes
gcObvName optional optional String Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID)
gcHash yes yes yes String HMAC MD5 hash (see hash generation)

Retrieve sender information

This service allows the retrieval of the information associated to the sender of a completed transaction. As a response to the given reference number, the account holder, IBAN and BIC of the customer are returned. This information may be used for a refund to the original payer.

API call

URL: https://payment.girosolution.de/girocheckout/api/v2/giropay/senderinfo
Provided by: GiroCheckout
Called by: Merchant

POST Parameters
Name Mandatory Type Description
merchantId Yes Integer merchant ID of a giropay project
projectId Yes Integer project ID of a giropay project
reference Yes String(36)GiroCheckout transaction ID
hash Yes String(32)HMAC MD5 hash of the full JSON string. (see api call reply)
Example
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

Response

The response is a JSON object. The rc field returns an error code. If rc = 0 is returned, the corresponding fields contain the sender information.

JSON Parameters
Name Mandatory Type Description
rc yes Integer response code
msg yes String additional information about the response code in case of error
accountholder Optional String Account holder of the sender account
iban Optional String IBAN of the sender account
bic Optional String BIC of the sender account
HEADER parameter
hash yes String HMAC MD5 hash of the full JSON string. (see api call reply)
Example in case of success

hash : cde71b6b98e8dae709fdc1e17aef885f 

{"accountholder":"Max Mustermann","iban":"DE87123456781234567890","bic":"TESTDETT421","rc":0,"msg":""}
Example in case of error

hash : f1d186103b8c4cb59c54ae7b987a9d4c 

{"accountholder":null,"iban":null,"bic":null,"rc":5034,"msg":"Transaktion nicht vorhanden"}