API Integration

For the development and integration of the solution, a test payment gateway for merchants is available at https://iapi.iplatebnibrana.csob.cz/.

Migration to the production environment (after approval of the solution by the bank) can be achieved by replacement of the test keys with the production keys and redirecting api to https://api.platebnibrana.csob.cz/.

Authorisation restrictions in the integration environment

In order to avoid unintentional confusion between the integration and production environment, successful payment authorization in the integration environment is limited to Test cards and credentials. In the integration environment, payment authorisation is performed against the simulator, real "live" payment cards cannot be used. The payment rejection simulation in the authorisation, according to the CVC code, remains unchanged.

This restriction minimises any potential damage caused in the event that the "live e-shop" accidentally switches from the production environment back to integration.

eAPI is based on REST API principles, is available via HTTPS protocol and the data is sent in JSON format. The individual operations are implemented using the following HTTP methods:

Method	Description
POST	payment initiation
GET	obtain the current status of the payment
PUT	payment status change

The following HTTP status codes are used in eAPI operation call responses:

Value	Meaning	Description
200	OK	the request has been processed
400	Bad Request	the request cannot be processed
401	Unauthorized	the request could not be authenticated
403	Forbidden	access denied
404	Not Found	source not found
405	Method Not Allowed	the requested method is not supported
429	Too Many Requests	too many requests
500	Internal Server Error	internal payment gateway error
503	Service Unavailable	the service is temporarily down

The payment gateway differentiates between two basic types of responses:

HTTP response code 200 in the response indicates a successfully processed request, the Content-Type application/json is returned in the response and all mandatory parameters specified in the specification of the operation are filled in. The response is always signed for this type.

Example of response of operation payment/init (mandatory parameters for this operation are payId, dttm, resultCode, resultMessage a signature)

HTTP/1.1 200 OK
Content-Type: application/json

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

All other responses with an HTTP response code other than 200 indicate error responses. The Content-Type application/json is returned, while only the parameters resultCode (see list) and resultMessage (specifying text describing the given error, the text may differ from the default text given in the code list of return codes). A response with an HTTP response code other than 200 is not signed.

The HTTP response code that is returned is dependant on the type of error:

In case of missing or invalid parameters of merchantId, signature the http status code 401 Unauthorized is returned.

Examples of response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ 
  "resultCode": 100,
  "resultMessage": "Missing parameter merchantId"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter signature"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid parameter merchantId M1MIPS0000"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Merchant key not found for merchantId M1MIPS0000"
}

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Wrong signature"
}

In case of missing or invalid parameter dttm or in case the merchant is deactivated on the bank's systems or does not have the given operation enabled, the http status code 403 Forbidden is returned.

Examples of response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter dttm"
}

The format of the dttm parameter is yyyyMMddHHmmss. In case of an invalid format, the payment gateway returns the response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid format of dttm parameter"
}

 

For the request, always fill in the current date and time corresponding to the CET / CEST time zone, the payment gateway checks the transmitted value and tolerates a certain divergence (in the order of minutes) compared with the current time synchronised on the payment gateway servers. In case of an incorrect value, the following response is returned:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid dttm, accepting only current, received 20211229101112"
}

If the merchant is deactivated in the bank's systems, the response is returned:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 120,
  "resultMessage":"Merchant blocked"
}

If the merchant does not have the given operation allowed, the response is returned:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "resultCode": 180,
  "resultMessage": "Operation not allowed"
}

In case of missing or invalid parameters, the http status code 400 Bad request is returned. In this case, the payment gateway validates other parameters from the request (this is a validation of the remaining parameters in addition to the above mentioned "basic" parameters merchantId, dttm and signature).

Examples of response:

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "resultCode": 100,
  "resultMessage": "Missing parameter totalAmount"
}

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "resultCode": 110,
  "resultMessage": "Invalid parameter totalAmount, received -100"
}

In case of an internal error occurring during the request processing, the http status code 500 Internal Server Error is returned.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "resultCode": 900,
  "resultMessage": "Internal error"
}

In case of unavailability (e.g. within the planned outage) the http status code 503 Service Unavailable is returned.

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "resultCode": 900,
  "resultMessage": "Request rejected"
}

A rule is applied for the init methods that the payment can be within the init declined. After the validation of the request parameters is successfully completed and the payment is created (the payId is assigned and returned), follow-up checks are performed, which are commonly related to the merchant's settings or the availability of external systems. If this process cannot be completed, the status of the payment will change to 6 - Payment declined. In this case, HTTP response code 200 is returned, the response is signed, all mandatory parameters for the given operation are filled in and the returned parameters resultCode and resultMessage contain the reason for the rejection:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "payId":"7624c5e60252@HA",
  "dttm":"20220125131601",
  "resultCode": 110,
  "resultMessage":"Currency parameter USD not allowed",
  "paymentStatus": 6,
  "signature":"base64-encoded-response-signature"
 }

Return code list  

resultCode	resultMessage
0	OK (the operation was processed correctly, a transaction created, status updated, etc.)
100	Missing parameter {name} (missing mandatory parameter)
110	Invalid parameter {name} (invalid parameter format)
120	Merchant blocked (the merchant is not allowed payments)
130	Session expired (the request has expired)
140	Payment not found (payment not found)
150	Payment not in valid state (incorrect payment status, the operation cannot be performed)
160	Payment method disabled (the operation is not allowed, the merchant must contractually request the settings)
170	Payment method unavailable (unavailability of the method provider, the service is not available at this time)
180	Operation not allowed (unauthorised operation)
190	Payment method error (processing error at method provider)
200	Duplicate purchaseId (duplicate purchaseId for NEJsplátku)
230	Merchant not onboarded for MasterPass (the merchant is not registered in MasterPass), deprecated
240	MasterPass request token already initialised (MasterPass token has already been initialised), deprecated
250	MasterPass request token does not exist (MasterPass token not found, unable to complete payment using MasterPass), deprecated
270	MasterPass cancelled by user (the customer has not completed the card/address selection in the MasterPass wallet), deprecated
500	EET Rejected (EET call was rejected by FS)
600	mallpay payment declined in precheck (the mallpay/init operation cannot be completed due to a mallpay request rejection)
700	Oneclick template not found (OneClick template has not been found)
710	Oneclick template payment expired (OneClick the template has not been used for more than 12 months, the payment has expired)
720	Oneclick template card expired (the card for the OneClick template has expired)
730	Oneclick template customer rejected (the OneClick template was cancelled at the customer's request)
740	Oneclick template payment reversed (OneClick template has been reversed)
750	Cardholder account closed (OneClick template was cancelled due to the closed cardholder account)
800	Customer not found (customer identified by customerId not found)
810	Customer found, no saved card(s) (the customer identified using the customerId was found but has no previously stored cards at the payment gateway)
820	Customer found, found saved card(s) (the customer identified using customerId was found and has cards stored on the payment gateway)
900	Internal error (internal request processing error)