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!
Information about eps can be found under https://www.girosolution.de/girocheckout/bezahlverfahren.html.
eps can only process EURO payments.
field | value |
---|---|
BIC | HYPTAT22XXX |
Verfügernummer/-name und PIN | no input needed, click Login |
mobile TAN | any or empty |
transaction result
result code | answer | description |
---|---|---|
4000 | successful transaction | After submission of the form by using the data above you create a successful transaction. |
4900 | unsuccessful transaction | After clicking the button Zahlung abbrechen you create an unsuccessful transaction. |
As shown in the workflow there are different API calls during an eps transaction.
This API call checks, if a bank supports the eps payment method. Therefore the BIC of the buyer's account has to be submitted. The response shows if the bank provides eps. It is recommended to do this prior to an initial payment, to make sure that the buyer's bank supports eps.
URL: https://payment.girosolution.de/girocheckout/api/v2/eps/bankstatus
provided by: GiroCheckout
called by: merchant
parameter | mandatory | type | description |
---|---|---|---|
merchantId | yes | Integer | Merchant ID of an eps project |
projectId | yes | Integer | Project ID of an eps project |
bic | yes | String(11) | the buyer's bank account BIC (8 or 11-digits), which schould be checked (determined by Bankstatus Widget) |
hash | yes | String(32) | HMAC MD5 hash over all API call params (see hash generation) |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "bic=HYPTAT22" \ -d "hash=818a60dde0fbaeb5e7f5affe7c2a28a7" \ https://payment.girosolution.de/girocheckout/api/v2/eps/bankstatus
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 eps. If eps is supported, additional information can be found in the eps parameter. Additional information about the bank will also be returned, if they are known.
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 |
eps | optional | Integer | 0 = eps payment is not supported 1 = eps payment is supported |
HEADER parameter | |||
hash | yes | String | HMAC MD5 hash overall the JSON string. (see api call reply) |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "bic=HYPTAT22" \ -d "hash=818a60dde0fbaeb5e7f5affe7c2a28a7" \ https://payment.girosolution.de/girocheckout/api/v2/eps/bankstatus
hash : 9c26067e25e2d273c6da1fb2be35999a
{"bankcode":"57000","bic":"HYPTAT22XXX","bankname":"HYPO TIROL BANK AG","eps":"1","rc":0,"msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "bic=HYPTAT22" \ -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \ -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \ -d "hash=0399f30dab1a1c296703bb571a790fb2" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/start
hash : b9d6a1e619ddb6a232274213885f5bb0
{"reference":"189d3a91-a760-4d3e-af7d-1fa7c57e1d2e","redirect":"https:\/\/www.banking.co.at\/appl\/ebp-vorproduktion\/logout\/so\/loginPrepare\/eps.html?resource=2\u0026cai=%2Bj8PpBHwCEBITWwYdtds2zIMtbNm7jfX4DOX1AQA1HdJ-","rc":"0","msg":""}
hash : 98d9d8b133acf97eb92601fa72d804a0
{"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "hash=02f123fdb8b2056596abc0e6ebb1a8c3" \ https://payment.girosolution.de/girocheckout/api/v2/eps/issuer
hash : 68fef295c525df124fe47760fcf12396
{"issuer":{"BAWAATWWXXX":"BAWAG P.S.K. Bank für Arbeit und Wirtschaft und Österreich", "OBKLAT2LXXX":"Oberbank AG","BTVAAT22XXX":"Bank für Tirol und Vorarlberg AG", [...]},"rc":0,"msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \ -d "hash=246d1fa2ed97ecff895de974c560f9ec" \ https://payment.girosolution.de/girocheckout/api/v2/eps/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 "bic=HYPTAT22" \ -d "hash=818a60dde0fbaeb5e7f5affe7c2a28a7" \ https://payment.girosolution.de/girocheckout/api/v2/eps/bankstatus
hash : 9c26067e25e2d273c6da1fb2be35999a
{"bankcode":"57000","bic":"HYPTAT22XXX","bankname":"HYPO TIROL BANK AG","eps":"1","rc":0,"msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "bic=HYPTAT22" \ -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \ -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \ -d "hash=0399f30dab1a1c296703bb571a790fb2" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/start
hash : b9d6a1e619ddb6a232274213885f5bb0
{"reference":"189d3a91-a760-4d3e-af7d-1fa7c57e1d2e","redirect":"https:\/\/www.banking.co.at\/appl\/ebp-vorproduktion\/logout\/so\/loginPrepare\/eps.html?resource=2\u0026cai=%2Bj8PpBHwCEBITWwYdtds2zIMtbNm7jfX4DOX1AQA1HdJ-","rc":"0","msg":""}
hash : 98d9d8b133acf97eb92601fa72d804a0
{"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "hash=02f123fdb8b2056596abc0e6ebb1a8c3" \ https://payment.girosolution.de/girocheckout/api/v2/eps/issuer
hash : 68fef295c525df124fe47760fcf12396
{"issuer":{"BAWAATWWXXX":"BAWAG P.S.K. Bank für Arbeit und Wirtschaft und Österreich", "OBKLAT2LXXX":"Oberbank AG","BTVAAT22XXX":"Bank für Tirol und Vorarlberg AG", [...]},"rc":0,"msg":""}
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "reference=9ce6c641-4082-4f75-ae54-333309febcc5" \ -d "hash=246d1fa2ed97ecff895de974c560f9ec" \ https://payment.girosolution.de/girocheckout/api/v2/eps/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"}
The initialisation of an eps can be processed in different ways. This will be distinguished just by the project id.
Torwards a successful initialisation 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.
URL: https://payment.girosolution.de/girocheckout/api/v2/transaction/start
provided by: GiroCheckout
called by: merchant
name | mandatory | type | description |
---|---|---|---|
merchantId | yes | Integer | merchant ID of an eps project |
projectId | yes | integer | project ID of an eps project |
merchantTxId | yes | String(255) | unique transaction id of the merchant |
amount | yes | Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. Cent, Penny |
currency | yes | String(3) | currency EUR = Euro |
purpose | yes | String(27) | purpose |
bic | yes | String(11) | BIC (8 or 11-digits), (determined by Bankstatus Widget) |
urlRedirect | yes | String | URL, where the buyer has to be sent after payment |
urlNotify | yes | String | URL, where the notification has to be sent after payment |
hash | yes | String | HMAC MD5 hash (see hash generation) |
curl -d "merchantId=1234567" \ -d "projectId=1234" \ -d "merchantTxId=1234567890" \ -d "amount=100" \ -d "currency=EUR" \ -d "purpose=Beispieltransaktion" \ -d "bic=HYPTAT22" \ -d "urlRedirect=http://www.my-domain.de/girocheckout/redirect" \ -d "urlNotify=http://www.my-domain.de/girocheckout/notify" \ -d "hash=0399f30dab1a1c296703bb571a790fb2" \ https://payment.girosolution.de/girocheckout/api/v2/transaction/start
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.
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 overall the JSON string. (see api call reply) |
hash : b9d6a1e619ddb6a232274213885f5bb0
{"reference":"189d3a91-a760-4d3e-af7d-1fa7c57e1d2e","redirect":"https:\/\/www.banking.co.at\/appl\/ebp-vorproduktion\/logout\/so\/loginPrepare\/eps.html?resource=2\u0026cai=%2Bj8PpBHwCEBITWwYdtds2zIMtbNm7jfX4DOX1AQA1HdJ-","rc":"0","msg":""}
hash : 98d9d8b133acf97eb92601fa72d804a0
{"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":""}
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 an eps payment is contained in the field gcResultPayment.
Due to the internal eps process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click.
URL: notifyUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout
name | mandatory | type | description |
---|---|---|---|
gcReference | yes | String | unique GiroCheckout transaction ID |
gcMerchantTxId | yes | String | merchant transaction ID |
gcBackendTxId | yes | String | payment processor transaction ID |
gcAmount | yes | Integer | if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny |
gcCurrency | yes | String | currency |
gcResultPayment | yes | Integer | payment result codes |
gcHash | yes | String | HMAC MD5 hash (see hash generation) |
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. |
After completing the payment, the customer may return to the merchant through a link. This return is not done automatically.
URL: redirectUrl of the prior init transaction call
provided by: merchant
called by: GiroCheckout
name | mandatory | type | description | ||
---|---|---|---|---|---|
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 | |
gcHash | yes | yes | yes | String | HMAC MD5 hash (see hash generation) |