User Tools

Site Tools


Translations of this page:
en:girocheckout:eps:start

eps

Information about eps can be found under https://www.girosolution.de/girocheckout/fuer-haendler/.

eps can only process EURO payments.

test data

field value
BIC VBOEATWWAPO
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.

workflow

PlantUML Graph

  1. buyer/ customer chooses eps and enters his bank's BIC
  2. merchant checks the bankstatus (check bankstatus)
  3. merchant receives a reply, if bank supports eps
  4. merchant initialises eps (initialise eps payment)
  5. GiroCheckout initialises request at eps
  6. eps submits response to GiroCheckout
  7. merchant gets response about initialisation (if an issue occurs the transaction is finished)
  8. merchant sends redirect URL to buyer/ customer
  9. the buyer's/ customer's browser redirects to buyer's/ customer's online banking account
  10. bank shows login page
  11. buyer/ customer authorises eps payment
  12. bank processes reqest
  13. bank submits result to eps
  14. eps submits result to GiroCheckout
  15. GiroCheckout notifies merchant about the result (payment result notification)
  16. merchant processes result
  17. merchant sends HTTP Statuscode to GiroCheckout
  18. GiroCheckout sends merchants redirect page to eps
  19. 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 an eps transaction.

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

check bankstatus

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.

API call

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

POST parameter
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)
example
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

reply

The reply contains an encoded JSON string. A 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.

JSON parameter
name mandatory type description
rc yes Integer error codes
msg yes String additional informationen about the response code
bic yes String BIC
bankname yes String name of the bank
eps yes 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)
example

hash : 9c26067e25e2d273c6da1fb2be35999a

{"bankcode":"57000","bic":"HYPTAT22XXX","bankname":"HYPO TIROL BANK AG","eps":"1","rc":0,"msg":""}

eps issuer bank request

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

URL: https://payment.girosolution.de/girocheckout/api/v2/eps/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
curl -d "merchantId=1234567" \
     -d "projectId=1234" \
     -d "hash=02f123fdb8b2056596abc0e6ebb1a8c3" \
     https://payment.girosolution.de/girocheckout/api/v2/eps/issuer

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
Beispiel

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":""}

initialise eps payment

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.

request

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

POST parameter
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)
example
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

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 overall the JSON string. (see api call reply)
example in case of success

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":""}
example in case of error

hash : 98d9d8b133acf97eb92601fa72d804a0

 {"reference":"f84e606f-817d-439f-ada1-d37e85cb6314","redirect":"","rc":"5100","msg":""}

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 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.

request

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

GET parameter
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)

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
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)

Bank selection widget

The bank selection widget may be used to implement an autocomplete functionality for a BIC or bank number form field.

Demo page

Integration

Native Javascript Widget (pure JS)

This widget was implemented in pure JS and does not require third-party libraries. Thus, no conflicts with other products will occur.

Including the required files:

  • Line 1: Includes stylesheet
  • Lines 2: Includes Widget Script
 1 <link rel="stylesheet" href="https://bankauswahl.giropay.de/widget/v2/style.css" />
 2 <script src="https://bankauswahl.giropay.de/widget/v2/girocheckoutwidget.js"></script>
 

Event “onkeyup” for giropay BIC field:

 1 <input type="text" id="giropay_bic" name="giropay_bic" value="" onkeyup="girocheckout_widget(this, event, 'bic', '0')">

Event “onkeyup” for eps BIC field:

 1 <input type="text" id="eps_bic" name="eps_bic" value="" onkeyup="girocheckout_widget(this, event, 'bic', '3')">

The widget may be configured through several parameters (parameters 3 and 4 of the girocheckout_widget call):

Parameter Type Value Description
return String blz
bic
Defines whether the BIC or the bank code (BLZ) is to be displayed in the field once the bank has been selected. You should usually put 'bic' here.
kind integer 0 = All banks are available for selection
1 = Only banks that support giropay
2 = Only banks that support giropay-ID
Defines which banks are available for selection.

That is all!

en/girocheckout/eps/start.txt · Last modified: 2016/06/13 16:41 by michaelheumann

Page Tools