-
Notifications
You must be signed in to change notification settings - Fork 67
Basic Methods
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.
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 tooneclickPayment
or tocustomPayment
, the passedcustomerId
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.
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":"[email protected]",
"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"
}
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.
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.
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".
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
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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
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".
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"
}
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":"[email protected]",
"dttm":"20220125133015",
"signature":"base64-encoded-request-signature"
}
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":"[email protected]",
"dttm":"20220125133015",
"resultCode": 800,
"resultMessage":"Customer not found",
"signature":"base64-encoded-response-signature",
}
- Payment lifecycle
- Integration and API security
- Activation of the production environment
- Test cards and credentials
- API Sunset
- Payment Authentication
- Basic Payment
- OneClick Payment
- Custom Payment
- Apple Pay
- Google Pay
- Collecting partial card payment
- ČSOB Payment Button
- Payment Skip Pay
- API Integration
- Request Signing and Response Signature Validation
- API Methods Overview
- Basic Methods
- Methods for OneClick Payment
- Methods for Apple Pay
- Methods for Google Pay
- Methods for ČSOB Payment Button
- Methods for Skip Pay
- Purchase metadata