Girocheckout API

User Tools

Site Tools

Trace:
en:girocheckout:eps:start

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
en:girocheckout:eps:start [2014/07/12 21:19]
jeromejung created 		en:girocheckout:eps:start [2023/05/05 03:29] (current)
michaelheumann
Line 1: Line 1:
-====== EPS ======+====== eps ======
  
-Information about EPS can be found under https://www.girosolution.de/girocheckout/bezahlverfahren.html. +**eps can only process EURO payments.**
  
 ===== test data ===== ===== test data =====
 {{page>en:testdata:eps&noheader&nofooter}} {{page>en:testdata:eps&noheader&nofooter}}
 +
 ===== workflow ===== ===== workflow =====
  
Line 10: Line 11:
 hide footbox hide footbox
  
-participant "buyer" as buyer+participant "buyer/ customer" as buyer
 participant "merchant" as shop participant "merchant" as shop
 participant "GiroCheckout" as girocheckout participant "GiroCheckout" as girocheckout
-participant "EPS" as eps+participant "eps" as eps
 participant "online banking" as bank participant "online banking" as bank
  
Line 19: Line 20:
  
 buyer -> shop:  buyer -> shop: 
-shop -> girocheckout:  
-girocheckout -> shop:  
 shop -> girocheckout: shop -> girocheckout:
 girocheckout -> eps:  girocheckout -> eps: 
Line 26: Line 25:
 girocheckout -> shop:  girocheckout -> shop: 
 shop -> buyer:  shop -> buyer: 
-buyer -> bank:+buyer -> eps: 
 +eps -> bank:
 bank -> buyer:  bank -> buyer: 
 buyer -> bank: buyer -> bank:
Line 42: Line 42:
 </uml> </uml>
  
-  - buyer chooses EPS payment method +  - buyer/ customer chooses eps and enters his bank's BIC 
-  - merchant requests the available banks ([[en:girocheckout:eps:start#eps_issuer_bank_request|bank request]]) +  - merchant initialises eps ([[en:girocheckout:eps:start#initialise_eps_payment|initialise eps payment]]) 
-  - merchant gets a reply of all issuer banks, that support EPS +  - GiroCheckout initialises request at eps 
-  - buyer selects Bank and merchant initialises EPS payment ([[en:girocheckout:eps:start#initialise_eps_payment|initialise EPS payment]]) +  - eps submits response to GiroCheckout
-  - GiroCheckout initialises transaction at EPS +
-  - EPS submits response to GiroCheckout+
   - merchant gets response about initialisation (if an issue occurs the transaction is finished)   - merchant gets response about initialisation (if an issue occurs the transaction is finished)
-  - merchant sends redirect URL to buyer +  - merchant sends redirect URL to buyer/ customer 
-  - the buyer's browser redirects buyer to his online banking account+  - the buyer's/ customer's browser redirects to eps where the bank is selected (optional, only if bank is not already stored in browser) 
 +  - eps redirects to the customer's online banking
   - bank shows login page   - bank shows login page
-  - buyer authorises payment +  - buyer/ customer authorises eps payment 
-  - bank processes payment +  - bank processes reqest 
-  - bank submits payment result to EPS +  - bank submits result to eps 
-  - EPS submits result to GiroCheckout +  - eps submits result to GiroCheckout 
-  - GiroCheckout notifies merchant about the transaction result ([[en:girocheckout:eps:start#notification_about_the_payment_result|payment result notification]])+  - GiroCheckout notifies merchant about the result ([[en:girocheckout:eps:start#notification_about_the_payment_result|payment result notification]])
   - merchant processes result   - merchant processes result
   - merchant sends HTTP Statuscode to GiroCheckout   - merchant sends HTTP Statuscode to GiroCheckout
-  - GiroCheckout sends merchants redirect page to EPS +  - GiroCheckout sends merchants redirect page to eps 
-  - buyer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:eps:start#redirection_of_the_customer_to_merchant|buyer redirection]])+  - buyer/customer clicks "Zurück zum Shop" and gets redirected to the merchant ([[en:girocheckout:eps:start#redirection_of_the_customer_to_merchant|buyer redirection]])
  
 ===== API functions ===== ===== API functions =====
  
-==== overview =====+==== Overview =====
  
-As shown in the workflow there are different API calls during an EPS transaction.+As shown in the workflow there are different API calls during an eps transaction.
  
-  - EPS issuer bank request+  - check bankstatus
   - initialise transaction   - initialise transaction
   - payment result notification to merchant    - payment result notification to merchant 
Line 74: Line 73:
  
  
-==== EPS issuer bank request ==== +==== check bankstatus ==== 
-Returns a list which contains all supported EPS issuer banks. The buyer has to choose his one.+**This call should not be used anymore. All eps transactions now use an external bank selection form!** 
 + 
 +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| 
 +|hash           |yes       |String(32)|HMAC MD5 hash over all API call params (see [[en:girocheckout:general:start#hash generation|hash generation]])| 
 + 
 +== example == 
 +{{page>codesamples:eps#bankstatus.request&noheader&nofooter}} 
 + 
 +=== 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     |[[en:girocheckout:errorcodes|error codes]] | 
 +|msg            |yes       |String(255) |additional informationen about the response code | 
 +|bic            |yes       |String(11)  |BIC | 
 +|bankname       |yes       |String(100) |name of the bank | 
 +|eps            |yes       |Integer     |0 = eps payment is not supported \\ 1 = eps payment is supported| 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32)  |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | 
 + 
 +== example == 
 +{{page>codesamples:eps#bankstatus.response&noheader&nofooter}} 
 + 
 + 
 +==== eps issuer bank request ==== 
 +**This call should not be used anymore. All eps transactions now use an external bank selection form!** 
 + 
 +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 \\ **URL:** https://payment.girosolution.de/girocheckout/api/v2/eps/issuer \\
Line 95: Line 133:
 == JSON parameter == == JSON parameter ==
 ^name           ^mandatory  ^type      ^description   ^ ^name           ^mandatory  ^type      ^description   ^
-|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|error codes]] | +|rc             |yes       |Integer     |[[en:girocheckout:errorcodes|error codes]] | 
-|msg            |yes       |String    |additional informationen about the response code | +|msg            |yes       |String(255) |additional informationen about the response code | 
-|issuer         |optional  |Mixed     |list of all supported issuer banks |+|issuer         |optional  |Mixed       |list of all supported issuer banks containing bic as key and name|
  
 == Beispiel == == Beispiel ==
 {{page>codesamples:eps#issuer.response&noheader&nofooter}} {{page>codesamples:eps#issuer.response&noheader&nofooter}}
  
 +==== Initialize eps payment ====
 +The initialisation of an eps can be processed in different ways. This will be distinguished just by the project id. 
  
-==== initialise EPS payment ==== 
 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. 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.
  
Line 109: Line 148:
 **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\ **URL:** https://payment.girosolution.de/girocheckout/api/v2/transaction/start \\
 **provided by:** GiroCheckout \\ **provided by:** GiroCheckout \\
-**called by:** Händler+**called by:** merchant
  
 == POST parameter == == POST parameter ==
 ^name           ^mandatory  ^type        ^description   ^ ^name           ^mandatory  ^type        ^description   ^
-|merchantId     |yes       |Integer     |merchant ID of an EPS project | +|merchantId     |yes              |Integer     |merchant ID of an eps project | 
-|projectId      |yes       |integer     |project ID of an EPS project | +|projectId      |yes              |integer     |project ID of an eps project | 
-|merchantTxId   |yes       |String(255) |unique transaction id of the merchant | +|merchantTxId   |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       |Integer     |if a decimal currency is used, the amount has to be in the smallest unit of value, eg. cent, penny | +|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| +|currency       |yes              |String(3)   |currency\\ EUR = Euro| 
-|purpose        |yes       |String(27)  |purpose | +|purpose        |yes              |String(27)  |purpose | 
-|issuer         |yes       |String      |EPS Issuer Bank | +|bic            |**deprecated**   |String(11)  |**This parameter must not be used anymore. All eps transactions now use an external bank selection form!** BIC (8 or 11-digits)| 
-|urlRedirect    |yes       |String      |URL, where the buyer has to be sent after payment | +|urlRedirect    |yes              |String(2048)|URL, where the buyer has to be sent after payment | 
-|urlNotify      |yes       |String      |URL, where the notification has to be sent after payment | +|urlNotify      |yes              |String(2048)|URL, where the notification has to be sent after payment | 
-|hash           |yes       |String      |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+|kassenzeichen  |optional         |String(255) |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. Characters must comply with the UTF-8 character set. | 
 +|hash           |yes              |String(32)  |HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) | 
 + 
  
 == example == == example ==
Line 134: Line 176:
 == Parameter == == Parameter ==
 ^name           ^mandatory  ^type      ^description   ^ ^name           ^mandatory  ^type      ^description   ^
-|rc             |yes       |Integer   |[[en:girocheckout:errorcodes|response code]] | +|rc             |yes      |Integer     |[[en:girocheckout:errorcodes|response code]] | 
-|msg            |yes       |String    |additional information about the response code | +|msg            |yes      |String(255) |additional information about the response code | 
-|reference      |optional |String    |unique GiroCheckout transaction ID | +|reference      |optional |String(36)  |unique GiroCheckout transaction ID | 
-|redirect       |optional |String    |redirect URL to the buyer's online banking account|+|redirect       |optional |String(2048)|redirect URL to the buyer's online banking account|
 ^HEADER parameter^^^^ ^HEADER parameter^^^^
-|hash           |yes       |String    |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |+|hash           |yes       |String(32) |HMAC MD5 hash overall the JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) |
  
 == example in case of success == == example in case of success ==
Line 146: Line 188:
 == example in case of error == == example in case of error ==
 {{page>codesamples:eps#transactionstart.response.false&noheader&nofooter}} {{page>codesamples:eps#transactionstart.response.false&noheader&nofooter}}
- 
  
 ==== notification about the payment result ==== ==== 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//. +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. +Due to the internal eps process, a redirection of the customer to urlRedirect is not done automatically but only after a customer click. 
  
  
Line 161: Line 204:
  
 == GET parameter == == GET parameter ==
-^name             ^mandatory    ^  type        ^description   ^ +^name             ^mandatory  ^  type        ^description   ^ 
-|gcReference      |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes              |String(36)  | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes              |String(255) | merchant transaction ID | 
-|gcBackendTxId    |yes       |String      | payment processor transaction ID | +|gcBackendTxId    |yes              |String(10)  | 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 | +|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 | +|gcCurrency       |yes              |String(3)   | currency | 
-|gcResultPayment  |optional |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| +|gcResultPayment  |yes              |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| 
-|gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+|gcHash           |yes              |String(32)  | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |
  
 === reply === === reply ===
Line 187: Line 230:
  
 == GET parameter == == GET parameter ==
-^name             ^mandatory    ^  type        ^description   ^ +^name             ^ mandatory  ^  type        ^description   ^ 
-|gcReference      |yes       |String      | unique GiroCheckout transaction ID | +|gcReference      |yes      |String(36)  | unique GiroCheckout transaction ID | 
-|gcMerchantTxId   |yes       | String     | merchant transaction ID | +|gcMerchantTxId   |yes      |String(255) | merchant transaction ID | 
-|gcBackendTxId    |yes       |String      | payment processor transaction ID | +|gcBackendTxId    |yes      |String(10)  | 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 | +|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 | +|gcCurrency       |yes      |String(3)   | currency | 
-|gcResultPayment  |optional |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| +|gcResultPayment  |yes      |Integer     | [[en:girocheckout:resultcodes#zahlungsausgang|payment result codes]]| 
-|gcHash           |yes       |String      | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|hash generation]]) |+|gcHash           |yes      |String(32)  | HMAC MD5 hash (see [[en:girocheckout:general:start#hash_generation|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/eps/senderinfo \\ 
 +**Provided by:** GiroCheckout \\ 
 +**Called by:** Merchant 
 + 
 +== POST Parameters == 
 +^Name           ^Mandatory  ^Type      ^Description   ^ 
 +|merchantId     |Yes       |Integer   |merchant ID of a eps project | 
 +|projectId      |Yes       |Integer   |project ID of a eps project  | 
 +|reference      |Yes       |String(36)|GiroCheckout transaction ID | 
 +|hash           |Yes       |String(32)|HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]])| 
 + 
 +== Example == 
 +{{page>codesamples:eps#senderinfo.request&noheader&nofooter}} 
 + 
 +=== 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   |[[en:girocheckout:errorcodes|response code]] | 
 +|msg            |yes      |String(255) |additional information about the response code in case of error| 
 +|accountholder  |Optional |String(255) |Account holder of the sender account| 
 +|iban           |Optional |String(36)  |IBAN of the sender account | 
 +|bic            |Optional |String(11)  |BIC of the sender account | 
 +^HEADER parameter^^^^ 
 +|hash           |yes       |String(32) |HMAC MD5 hash of the full JSON string. (see [[en:girocheckout:general:start#api_call_reply_to_the_merchant|api call reply]]) | 
 + 
 +== Example in case of success == 
 +{{page>codesamples:eps#senderinfo.response.true&noheader&nofooter}} 
 + 
 +== Example in case of error == 
 +{{page>codesamples:eps#senderinfo.response.false&noheader&nofooter}} 
  
en/girocheckout/eps/start.1405192756.txt.gz · Last modified: 2021/04/12 14:32

Page Tools