Skip to content

Basic Methods

Daniel Marek edited this page May 15, 2024 · 6 revisions

A brief overview

Method Description
payment/init Payment initialisation on the payment gateway.
payment/status Get the payment status.
payment/process Redirection to the payment gateway after the previous payment initialisation.
payment/reverse The operation reverses an already authorised payment (cancels prior to sending into balancing).
payment/close This operation inserts authorised uncharged payment into settlement.
payment/refund This operation requests full or partial refund for the buyer.
echo Operations to verify the availability of the payment gateway or to verify the signature of the message for easier integration.
echo/customer Operation to retrieve stored customer information.

The following diagram shows the course of payment by card at the gateway:

The customer makes an order payment on the e-shop. After selecting the card payment, the e-shop initiates a payment at the payment gateway using the payment/init operation. In response the payment identification payId (1) is received. After payment initialization, the customer is redirected from the e-shop to the payment gateway using the payment/process (2) operation.

After entering the data for payment by card (card number, expiration, CVC), the payment gateway performs the so-called (Device) Fingerprint (3) for some cards. This sends data from the customer's browser to the card issuer, who will use this data for subsequent payment authentication (4). After completing the payment, the customer is redirected back to the e-shop.

The merchant continuously checks the status of the payment by calling the operation payment/status (5).

The parameters in bold are mandatory for calls.


payment/init method  

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

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 10 digits.
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
payOperation String Type of payment operation. Allowed values: payment, oneclickPayment, customPayment. Optional parameter since version 1.9, default value: payment.
payMethod String The type of implicit payment method to be offered to the customer. Allowed values: card = card payment, card#LVP = card payment with low value payment. Optional parameter since version 1.9, default value: card.
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. The amount must correspond with the total value of the individual items in the cart (if the cart contains two items, the sum of the amounts must be the same as the total price).
currency String Currency code. Allowed values: CZK, EUR, USD, GBP, HUF, PLN, RON, NOK, SEK.
closePayment Boolean Indicates whether the payment should be automatically included in the closing and paid. Allowed values: true / false. Optional parameter from version 1.9, default value: true.
returnUrl String URL address to which the client will be redirected back to the e-shop after payment. Maximum length 300 characters. Specification of return values see below.
returnMethod String The method of returning to the e-shop URL. Allowed values POST, GET. The recommended method is POST.
cart Object The list of purchase items that will be displayed on the payment gateway. Contains Item items, item description see below.
customer Object Additional customer purchase data. See detailed description of the structure customer.
order Object Additional purchase data related to the order. See detailed description of the structure order.
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].
customerId String Unique customer ID assigned by the e-shop. Maximum length 50 characters. It is used when saving the card and its subsequent use during the next visit to this e-shop.
language String Preferred language version to be displayed to the customer at the payment gateway. Mandatory parameter since version 1.6, allowed values: cs,en,de,fr,hu,it,ja,pl,pt,ro,ru,sk,es,tr,vi,hr,sl,sv.
ttlSec Number payment life setting, in seconds, min. allowed value 300, max. allowed value 1800 (5-30 min). Payment lifetime is calculated from the moment of payment/init call. If the payment type payOperation is set to customPayment, this payment life ttlSec is ignored and the customer is able to complete the payment for up to 60 days, set in the customExpiry parameter.
logoVersion Number The version of the approved merchant logo that will be displayed for the payment. If it is a logo that has not yet been approved, the active merchant logo will be used. If this is not the case, the default payment gateway logo will be used.
colorSchemeVersion Number The version of the merchant's approved colour scheme that will be displayed for the payment. If it is a colour scheme that has not yet been approved, the active colour scheme of the merchant will be displayed, if not, the default colour scheme of the payment gateway will be displayed.
customExpiry String Custom payment expiration, format YYYYMMDDHHMMSS (an optional parameter that is checked only if payOperation is set to customPayment). The value entered must not be in the past. The maximum allowed validity of a custom-made payment is 60 days. If customExpiry is not specified, the custom payment validity is set to 60 days.
signature String Request signature, encoded in BASE64.

Note: if payOperation is set to oneclickPayment or to customPayment, the passed customerId parameter is ignored. When processing the payment template only a new card can be entered in the payment gateway interface, it is not possible to pay with a previously saved card. Similarly for custom payment - the previously saved cards cannot be used for payment.


item - Cart item (object cart)  

Items are listed line by line. Each shopping cart line has the name of the item, the number of items, the total price for the specified number of items and an optional description.

Item Type Description
name String Product name, maximum length 20 characters.
quantity Number Amount, must be >=1, integer.
amount Number The total price for the stated number of items in hundredths of a currency; the currency will be automatically taken from the currency item of the entire request.
description String Cart item description, maximum length 40 characters.

Note: if amount=0, the display of the contents of the basket on the payment gateway shows the text FREE

CAUTION: As of version v1, there must be at least one item in the cart (for example, "credit recharge") and a maximum of two items, such as "purchase at ..." and "shipping"). The restriction is given by the graphic design of the payment gateway and in the next version the limit of items will be significantly shifted.


Example for payment/init request with one item in the cart, without filling in additional purchase data:

{
  "merchantId":"M1MIPS0000",
  "orderNo":"5547",
  "dttm":"20220125131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":123400,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Wireless headphones",
      "quantity": 1,
      "amount": 123400
    }
  ],
  "merchantData":"some-base64-encoded-merchant-data",
  "language":"cs",
  "signature":"base64-encoded-signature-of-payment-request"
}

Example for payment/init request with two items in the cart, including completed additional purchase data:

{
  "merchantId":"M1MIPS0000",
  "orderNo":"5547",
  "dttm":"20220125131559",
  "payOperation":"payment",
  "payMethod":"card",
  "totalAmount":123400,
  "currency":"CZK",
  "closePayment": true,
  "returnUrl":"https://shop.example.com/return",
  "returnMethod":"POST",
  "cart":[
    {
      "name": "Wireless headphones",
      "quantity": 1,
      "amount": 123400
    },
    {
      "name": "Shipping",
      "quantity": 1,
      "amount": 0,
      "description": "DPL"
    }
  ],
  "customer": {
    "name":"Jan Novák",
    "email":"jan.novak@example.com",
    "mobilePhone":"+420.800300300",
    "account": {
      "createdAt":"2022-01-12T12:10:37+01:00",
      "changedAt":"2022-01-15T15:10:12+01:00"
    },
    "login": {
      "auth":"account",
      "authAt":"2022-01-25T13:10:03+01:00"
    }
  },
  "order": {
    "type":"purchase",
    "availability":"now",
    "delivery":"shipping",
    "deliveryMode": "1",
    "addressMatch":true,
    "billing": {
      "address1":"Karlova 1",
      "city":"Praha",
      "zip":"11000",
      "country":"CZE",
    }
  },
  "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 reply 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.
customerCode String Custom payment code for delivery to the customer. Returns only in the response for payOperation set to customPayment and only if the payment is in the Payment created (1) state.
statusDetail String The detailed status of the payment contains, for example, the reason for the payment being rejected, see description.
signature String Response signature, encoded in BASE64.

Example for return values for the payment/init operation -- successfully created payment:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "signature":"base64-encoded-response-signature"
 }

Example for return values for the payment/init operation -- a successful custom-made payment:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 1,
  "customerCode": "E61EC8",
  "signature":"base64-encoded-response-signature"
 }

In the event of an invalid request, the payment gateway returns a response containing a description of the error. A detailed description is given on the page API-integration.


payment/process method  

The request contains items directly in the URL. Parameter values must be "URL encoded". GET https://api.platebnibrana.csob.cz/api/v1.9/payment/process/{merchantId}/{payId}/{dttm}/{signature}

Redirection to the payment gateway after the previous payment initialisation. Unlike other eAPI operations (which can be sent using any http client from the merchant's system and return JSON returns), this operation must send a GET request from the payer's browser, resulting in the customer being redirected to the payment gateway page.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
payId String Unique payment ID (assigned by the payment gateway in the payment/init operace).
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
signature String Request signature, encoded in BASE64.

In the case of custom-made payment the payment/process operation cannot be used to switch to the payment gateway, the payment gateway will only allow the payment to be completed via the address https://platebnibrana.csob.cz/zaplat/{customerCode} containing the assigned customerCode. The address https://iplatebnibrana.csob.cz/zaplat/{customerCode} applies to the integration environment.


Example of call:

curl -v -X GET https://api.platebnibrana.csob.cz/api/v1.9/payment/process/M1MIPS0000/ff41e84b7e33%40HA/20220125131559/base64-encoded-request-signature

The server returns a redirect to the payment gateway page to display the result of the request processing ...

HTTP/1.1 303 See Other
Location: https://platebnibrana.csob.cz/pay/example.com/1a813383-2483-47b7-aa19-81a8e9c77850/

In case of correct processing, the payment gateway page will be displayed for entering the necessary data for payment, in case of processing error (invalid parameters, incorrect request signature, payment does not exist, etc.) the payment gateway page will be displayed with error description.

Return URL - return to e-shop  

At this point, it is appropriate to specify what parameters will be included in the redirection from the payment gateway back to the e-shop.

Parameters transmitted as part of the return to the e-shop:

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.
authCode String Payment authorisation code. It is returned only if the payment is in the Payment confirmed (4) status or in the Waiting for settlement (7) state or in the Payment settled (8) state.
merchantData String Data received from the merchant in a payment/init operation. They can be used, for example, to maintain the continuity of the process on the e-shop, coded in BASE64. Maximum length after encoding 255 characters.
statusDetail String Detailed status of payment, it includes, for example, the reason for the declined payment, see description.
signature String Response signature, encoded in BASE64.

The parameters are passed to the return address of the e-shop (parameter returnUrl obtained in payment/init) via the payer's browser using the POST or GET method (parameter returnMethod).

Note: e-shop must support processing of return values using the GET and POST methods from v1.5 (the payment gateway performs redirect according to the returnMethod parameter, for some actions - e.g. cancellation of payment by the user —- however, it always performs redirect using GET methods).

Example of return values when redirecting from the payment gateway to the e-shop using the POST method:

Http-Method: POST
Address: https://store.example.com/return
Payload:
payId=ff41e84b7e33%40HA&dttm=20220125131610&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Note: the parameters are passed as Form URL Encoded data sent in the body of the POST request.

Example of return values when redirecting from the payment gateway to the e-shop using the GET method:

Http-Method: GET
Address: https://store.example.com/return?payId=ff41e84b7e33%40HA&dttm=20220125131610&resultCode=0&resultMessage=OK&paymentStatus=4
&authCode=F7A23E&merchantData=base64-encoded-merchant-data&signature=base64-encoded-response-signature

Note: parameter values are "URL encoded".


payment/status method  

The request contains items directly in the URL. Parameter values must be "URL encoded".

GET https://api.platebnibrana.csob.cz/api/v1.9/payment/status/{merchantId}/{payId}/{dttm}/{signature}

Payment status operations.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
payId String Unique payment ID (assigned by the payment gateway in the init operation).
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
signature String Request signature, encoded in BASE64.

Example of call:

curl -v -X GET https://api.platebnibrana.csob.cz/api/v1.9/payment/status/M1MIPS0000/ff41e84b7e33%40HA/20220125131559/base64-encoded-request-signature

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.
authCode String Payment authorisation code. It is returned only if the payment is in the Payment confirmed (4), Waiting for settlement (7) , Payment settled (8), Refund processing (9) or in Payment returned (10) state.
statusDetail String Detailed status of payment, it includes, for example, the reason for the declined payment, see description.
actions Object Structure for transmitting the necessary data for execution confirmation within payment confirmation, relevant for oneclick@shop, applepay@shop a googlepay@shop payment methods. See structure actions.
signature String Response signature, encoded in BASE64.

Example of return values for payment/status operation:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125131601",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 4,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

payment/reverse method  

PUT https://api.platebnibrana.csob.cz/api/v1.9/payment/reverse

The reversal of an already authorised payment (cancelled prior to sending into balancing). An error is returned when calling this function on a payment that has already been sent by the settlement. In this case, a refund request must be submitted to cancel the payment.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
payId String Unique payment ID (assigned by the payment gateway in the init operation).
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
signature String Request signature, encoded in BASE64.

Example of request:

{
  "merchantId":"M1MIPS0000",
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125132015",
  "signature":"base64-encoded-request-signature"
}

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.
statusDetail String Detailed status of payment, it contains the reason for the rejection to pay, see description.
signature String Response signature, encoded in BASE64.

Example of return values for payment/reverse operation:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125132018",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 5,
  "signature":"base64-encoded-response-signature"
 }

payment/close method  

PUT https://api.platebnibrana.csob.cz/api/v1.9/payment/close

Operation inserts payments into settlement.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
payId String Unique payment ID (assigned by the payment gateway in the init operation).
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
totalAmount Number Total final price in hundredths of the base currency; the value must be positive and at the same time less than or equal to the original amount (see the totalAmount parameter in the payment/init operation).
signature String Request signature, encoded in BASE64.

Example of request:

{
  "merchantId":"M1MIPS0000",
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125132015",
  "signature":"base64-encoded-request-signature"
}

Example of request: (accounting for a smaller amount)

{
  "merchantId":"M1MIPS0000",
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125132015",
  "totalAmount":10000,
  "signature":"base64-encoded-request-signature"
}

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.
authCode String Payment authorisation code. It is returned only if the payment is in the Payment confirmed (4) status or in the Waiting for settlement (7) state or in the Payment settled (8) state.
statusDetail String Detailed status of payment, it contains the reason for the rejection to pay, see description.
signature String Response signature, encoded in BASE64.

Example of return values for payment/close operation:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125132018",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 7,
  "authCode":"F7A23E",
  "signature":"base64-encoded-response-signature"
 }

payment/refund method  

PUT https://api.platebnibrana.csob.cz/api/v1.9/payment/refund


By calling this operation, it is requested that the funds are returned back to the buyer. Applied to already processed payments.

As of eAPI v1.5, a so-called partial refund can be made by filling in the optional parameter amount. A partial refund can be made repeatedly, provided that the amount in the amount parameter must be less than the difference between the original authorised amount and the amount of partial refunds made (approved) so far.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
payId String Unique payment ID (assigned by the payment gateway in the init operation).
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
amount Number Required amount for a partial refund in hundredths of the base currency.
signature String Request signature, encoded in BASE64.

Example of request:

{
  "merchantId":"M1MIPS0000",
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125133015",
  "signature":"base64-encoded-request-signature"
}

Example of request: (including filling in the amount)

{
  "merchantId":"M1MIPS0000",
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125133015",
  "amount": 1000,
  "signature":"base64-encoded-request-signature"
}

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.
authCode String Payment authorisation code. It is returned only if the payment is in the Payment settled (8), Refund processing (9) or in Payment returned (10) state.
statusDetail String Detailed status of payment, contains reason for the payment decline, see description.
signature String Response signature, encoded in BASE64.

Processing for this operation is asynchronous, the paymentStatus parameter in the return values therefore contains the current status of the payment request (Payment settled), the status of the payment request can be monitored via payment/status.

Example of return values for payment/refund operation:

{
  "payId":"ff41e84b7e33@HA",
  "dttm":"20220125133016",
  "resultCode": 0,
  "resultMessage":"OK",
  "paymentStatus": 8,
  "authCode": "F7A23E",
  "signature":"base64-encoded-response-signature"
 }

echo method  

An auxiliary operation that is used to verify the correctness of the compiled signature request and the validation of the signature response for the application development phase. The operation can be called using the POST method (parameters sent in the body of the request in JSON format) or using the GET method - the request contains items directly in the URL: https://api.platebnibrana.csob.cz/api/v1.9/echo/{merchantId}/{dttm}/{signature}

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
signature String Request signature, encoded in BASE64.

Example of a call using the POST method:

curl -v -X POST https://api.platebnibrana.csob.cz/api/v1.9/echo \
-H "Content-Type:application/json" \
-d '{
  "merchantId":"M1MIPS0000",
  "dttm":"20220125133015",
  "signature":"base64-encoded-request-signature"
}'

Example of a call using the GET method:

curl -v -X GET https://api.platebnibrana.csob.cz/api/v1.9/echo/M1MIPS0000/20220125133015/base64-encoded-request-signature

Note: parameter values must be "URL encoded".

Return values  

Item Type Description
dttm String Date and time of request, in format YYYYMMDDHHMMSS.
resultCode Number The result of the operation, see list.
resultMessage String Text description of the operation result.
signature String Request signature, encoded in BASE64.

Example of return values for echo operation:

{
  "dttm":"20220125133016",
  "resultCode": 0,
  "resultMessage":"OK",
  "signature":"base64-encoded-response-signature"
 }

echo/customer method  

POST https://api.platebnibrana.csob.cz/api/v1.9/echo/customer

Operation to retrieve saved customer information.

Item Type Description
merchantId String Merchant ID assigned by the payment gateway.
customerId String Customer ID assigned in the e-shop, maximum length 50 characters.
dttm String Date and time the request was sent in the format YYYYMMDDHHMMSS.
signature String Request signature, encoded in BASE64.

Example of request:

{
  "merchantId":"M1MIPS0000",
  "customerId":"customer@example.com",
  "dttm":"20220125133015",
  "signature":"base64-encoded-request-signature"
}

Return values  

Item Type Description
customerId String Customer ID assigned in the e-shop.
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.
signature String Request signature, encoded in BASE64.

Example of return values:

{
  "customerId":"customer@example.com",
  "dttm":"20220125133015",
  "resultCode": 800,
  "resultMessage":"Customer not found",
  "signature":"base64-encoded-response-signature",
 }
Clone this wiki locally