Methods for ČSOB Payment Button

A brief overview

Method	Description
button/init	Initiation of the payment button payment (pt@shop).

The parameters in bold are mandatory for the calls.

---

button/init method  

POST https://api.platebnibrana.csob.cz/api/v1.9/button/init

This method initialises a payment with the payment button (pt@shop) and prepares parameters for redirecting the user from the e-shop to electronic banking. From electronic banking, the user is redirected back to the merchant's e-shop via the payment gateway, which displays the authorization result.

Item	Type	Description
merchantId	String	Merchant ID assigned by the payment gateway.
orderNo	String	The reference number of the order used for matching payments, which will also be stated on the bank statement. Numeric value, maximum length is 10 digits.
dttm	String	Date and time the request was sent in the format YYYYMMDDHHMMSS.
clientIp	String	IP address of the customer (the browser IP) accessing the merchant's e-shop, ipv4 or ipv6 format.
totalAmount	Number	Total price in hundredths of the base currency. This value will be displayed on the payment gateway as the total amount to be paid.
currency	String	Currency code. Allowed values: CZK.
returnUrl	String	URL address to which the client will be redirected back to the e-shop. The maximum length is 300 characters. When redirecting back to the e-shop, the same parameter set is passed as in the case of returning from the payment gateway when paying by card.
returnMethod	String	The method of returning to the e-shop URL. Allowed values POST, GET. The recommended method is POST.
brand	String	The payment button that the customer has chosen, allowed value is csob. This item is optional from the version 1.9, default value csob.
merchantData	String	Any auxiliary data that the merchant passes to the gateway, must be BASE64 encoded. The maximum length after encoding is 255 characters. In case of the "Marketplace" business model, the merchant must identify his retailer using the ID company number. This identifier must be enclosed in square brackets [] and can be placed arbitrarily within the merchantData item. If several retailers participate in the purchase, the ID number values are separated by a comma - e.g. [12345678,87654321].
language	String	Preferred language version, which is displayed to the customer at the payment gateway (the payment gateway is displayed when returning from electronic banking back to the e-shop, displaying the result of the authorization). Allowed values: cs,en,de,fr,hu,it,ja,pl,pt,ro,ru,sk,es,tr,vi,hr,sl,sv.
signature	String	Request signature, encoded in BASE64.

---

Example of request

{
  "merchantId":"M1MIPS0000",
  "orderNo":"11345325",
  "dttm":"20220125131559",
  "clientIp":"193.1.2.3",
  "totalAmount":12300,
  "currency":"CZK",
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"cs",
  "signature":"base64-encoded-signature-of-payment-request"
}

Return values  

Item	Type	Description
payId	String	Unique payment ID (assigned by the payment gateway in the init operation, contains a 15-character string).
dttm	String	Date and time of the response in the format YYYYMMDDHHMMSS.
resultCode	Number	The result of the operation, see list.
resultMessage	String	Text description of the operation result.
paymentStatus	Number	Payment status, see payment lifecycle.
redirect	Object	Structure containing the necessary parameters for redirection to electronic banking.
signature	String	Response signature, encoded in BASE64.

---

redirect - redirection parameters

Item	Type	Description
method	String	HTTP method type, allowed values are GET, POST.
url	String	Redirection URL.
params	Map	Completed only in case of redirection using POST, a map containing key-value values, only "value" values (without keys) are inserted into the response signature verification string in the order in which these arrive in the response.

Example of return values

{
  "payId":"54de9577040c@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus":1,
  "redirect": {
    "method":"GET",
    "url":"https://platebnibrana.csob.cz/pay/example.com/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob"
  },
  "signature":"base64-encoded-response-signature"
 }

Example of a response signature verification string:

54de9577040c@HA|20220125131601|0|OK|1|GET|https://platebnibrana.csob.cz/pay/example.com/2c72d818-9788-45a1-878a-9db2a706edc5/pt-detect/csob