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

Both sides previous revision Previous revision
Next revision 		Previous revision
en:girocheckout:eps:start [2019/09/03 18:05]
michaelheumann 		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/fuer-haendler/|https://www.girosolution.de/girocheckout/fuer-haendler/]]. 
  
 **eps can only process EURO payments.** **eps can only process EURO payments.**
Line 21: Line 20:
  
 buyer -> shop:  buyer -> shop: 
-shop -> girocheckout:  
-girocheckout -> shop:  
 shop -> girocheckout: shop -> girocheckout:
 girocheckout -> eps:  girocheckout -> eps: 
Line 28: 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 45: Line 43:
  
   - buyer/ customer chooses eps and enters his bank's BIC   - buyer/ customer chooses eps and enters his bank's BIC
-  - merchant checks the bankstatus ([[en:girocheckout:eps:start#check_bankstatus|check bankstatus]]) 
-  - merchant receives a reply, if bank supports eps 
   - merchant initialises eps ([[en:girocheckout:eps:start#initialise_eps_payment|initialise eps payment]])   - merchant initialises eps ([[en:girocheckout:eps:start#initialise_eps_payment|initialise eps payment]])
   - GiroCheckout initialises request at eps   - GiroCheckout initialises request at eps
Line 52: Line 48:
   - 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/ customer   - merchant sends redirect URL to buyer/ customer
-  - the buyer's/ customer's browser redirects to buyer's/ customer's 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/ customer authorises eps payment   - buyer/ customer authorises eps payment
Line 101: Line 98:
 == 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 | 
-|bic            |yes       |String    |BIC | +|bic            |yes       |String(11)  |BIC | 
-|bankname       |yes       |String    |name of the bank | +|bankname       |yes       |String(100) |name of the bank | 
-|eps            |yes       |Integer   |0 = eps payment is not supported \\ 1 = eps payment is supported|+|eps            |yes       |Integer     |0 = eps payment is not supported \\ 1 = eps payment is supported|
 ^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 == == example ==
Line 136: 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 containing bic as key and name|+|issuer         |optional  |Mixed       |list of all supported issuer banks containing bic as key and name|
  
 == Beispiel == == Beispiel ==
Line 157: Line 154:
 |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 |
-|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)| +|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]]) |
  
  
Line 178: 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 190: 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 ====
Line 208: Line 205:
 == 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  |yes              |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 234: Line 231:
 == 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  |yes       |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.1567526749.txt.gz · Last modified: 2021/04/12 14:32

Page Tools