Methods for ČSOB Payment Button - csob/paymentgateway GitHub Wiki

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