Skip to content

Technical FAQ

Jump to bottom
Daniel Marek edited this page Jul 23, 2024 · 27 revisions

I am getting http status 400 (Bad request) or 401 (Unauthorized) when calling the eAPI

In most of the cases, the reason is a wrong signature. The most common mistakes are:

  • the string for calculation of the signature is incorrect or the signature calculation algorithm is wrong. For more detailes please visit the section describing signing in eAPI specification
  • an incorrect private key is used for the request signature (i.e. integration and production environment key mismatch)
  • In case of the operation ‘payment/init’ specifically the parameter ‘closePayment’ the normally allowed values ‘true’ or ‘false’ are not used but instead (for php) value ‘1’ or ‘0’ is applied

Note. In case of the API 1.0 - 1.8 when invalid signature is used the response code ‘400 Bad request’ is returned. However, from the version eAPI 1.9 in case of an invalid signature the http response code ‘401 Unauthorized’ is returned, including also a detailed description of the error. Further detail can be found on page API Integration.

What algorithm do I need to create and verify the signature?

To create and verify signature it is required to use an algorithm based on SHA-1 (for eAPI v1.7 or older) or SHA-256 (for eAPI v1.8 or higher). For example, in Java for initiation of class java.security.Signature apply the algorithm "SHA256withRSA", in PHP apply "OPENSSL_ALGO_SHA256" algorithm for openssl_sign() and openssl_verify() functions.

Example of crypto operations in Java

Example of crypto operations in .NET

How many items can be included in the cart?

The eAPI v1, v1.5, v1.6, v1.7, v1.8 and v1.9 requires at least one (e.g.”credit top-up) and maximum two cart (e.g. “mobile phone” and “shipping costs”) items. Future versions will introduce a new cart with broader options.

I am receiving response code 900 when calling payment/init operation

Please pay attention to using the correct format of the cart items. The payment gateway expects a list of items for the parameter cart, i.e. the items must be enclosed in [ and ], even if the cart contains only a single item.

correct format:

"cart":[ { "name":"Reservation", "quantity":1, "amount":10000 } ]

Incorrect format:

"cart": { "name":"Reservation", "quantity":1, "amount":10000 }

Please also pay attention to the formatting of the parameter "extensions" used for the ECR. It is required to format this parameter also as a field and not as an object. This is illustrated below.

"extensions":[ { "extension": "eetV3", "dttm": "20170125131559", "data": { "premiseId": 181, "cashRegisterId": "00/2535/CN58", "totalPrice": 17896.00 }, "signature": "base64-encoded-extension-signature" } ]

How to load the public key in PEM format?

The public key of the payment gateway is distributed in the text PEM format. Please use the following examples for initiation:

JAVA

String publicKeyFileName = "test.pub";
String content = FileUtils.readFileToString(new File(publicKeyFileName));
content = StringUtils.remove(content, "-----BEGIN PUBLIC KEY-----");
content = StringUtils.remove(content, "-----END PUBLIC KEY-----");
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.decodeBase64(content));
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
PublicKey publicKey = keyFactory.generatePublic(keySpec);

PHP

$publicKeyFileName = "test.pub";
$fp = fopen ($publicKeyFileName, "r" );
if (! $fp) {
    throw new Exception ( "Public key " . $publicKeyFileName . " not found" );
}
$content = fread ($fp, filesize ( $publicKeyFileName ) );
fclose ( $fp );
$publicKey = openssl_get_publickey ( $content );

.NET

Example of sign() and verify() operations in this snippet.

The payment/process call returns http status 404, not found

Operation payment/process is called using the GET method. Please make sure that the last portion of the URL - signature parameter - is "URL encoded". The signature is transmitted to the gateway as Base64 encoded, therefore it can contain the / character. The payment gateway will not accept an incorrectly formatted request (as it can not load the signature).

What time zone should be used for dttm parameter?

Please use CET/CEST timezone. The same settings are used in responses sent from the payment gateway. The main benefit for the merchant is easier tracking of sent requests. This parameter is primarily used for signature computing.

What encoding should be used in JSON requests?

Please use UTF-8 encoding in JSON requests in eAPI calls.

The payment configuration is not successful due to a SSL error?

It is possible, that you are using unsupported/old version of openssl or possibly cryptographic protocols SSL v2/v3, TLS v1.0 or TLS v1.1. If you encounter the SSL error then it is recommended that you update the OpenSSL version with support of TLS v1.2.

reason: error:14077410:SSL routines:SSL23 _GET_SERVER_HELLO:sslv3 alert handshake failure

Integration - TLS v1.2 required from 12/2017

Production - TLS v1.2 required from 07/2018

The payment configuration is not successful due to an untrusted certificate used in communication with API.

The merchant server, where the merchant shop runs, communicates with eAPI via URL address https://api.platebnibrana.csob.cz. This site is secured via the https protocol. For the integration the merchant on the e-shop side only needs to specify the payment gateway address, however, dependent on the technology used (for example Java), an additional configuration has to be applied by adding certificates, which are provided for https://api.platebnibrana.csob.cz into so called truststore file. This ensures that on the e-shop side, during the establishment of the secure connection with https://api.platebnibrana.csob.cz the e-shop should be trusting this server. The implementation of the trusted certificates is decided by the programmer of the third party application. Our recommendation is to use this integration for security reasons. Certificate for https://api.platebnibrana.csob.cz is generated for a limited time period. The certificate validity and exchange process is described in the next section Certificate exchange.

In case of any problems with connectivity with https://api.platebnibrana.csob.cz is is required to download a new certificate from https://api.platebnibrana.csob.cz including all CA certificates, which are used for signing of the new certificate. This new certificate including the CA certificates then has to be added to the truststore file (for example, Java).

The requirement for adding one or more certificates into the truststore is determined by the specific configuration of each system, on which the merchant’s e-shop runs. It is possible that the system that operates the merchant’s e-shop uses, in case of Java technology, default cacerts file, where the root certificates are stored during the installation of the Java package. In this case there might not be any modifications required (the new certificate for https://api.platebnibrana.csob.cz is already signed using the certificate of the certification authority, which is signed by the root certificate already saved in the cacerts file. The root certificate for both the original and also the new certificate for https://api.platebnibrana.csob.cz is the same). It is required though to have the updated JAVA package, which contains the current CA certificates.

Certificate exchange https://api.platebnibrana.csob.cz

This is relevant for customers who have implemented verification of the trusted certificates on https://api.platebnibrana.csob.cz.

The validity date of the server certificate expires on June 28, 2025. A month ahead of this date the deadline for the server certificate exchange will be published. Please note that with the new certificates all superior CA certificates are also changed.

The current certificate can be found on https://api.platebnibrana.csob.cz.

Transaction made with ČSOB payment button is paid from the client’s account, in POS Merchant this is displayed as authorised, however, in the e-shop the transaction is declined

The transaction made by the payment button has one specific characteristic in its life cycle - authorised transaction is immediately moved into state 8. It is therefore possible that your e-shop validates the transaction as “paid” only states 4 and 7. In this case it is necessary to make a small modification to the e-shop integration.

Generated key cannot be downloaded in Safari browser

Generated key from keygen application is not automatically downloaded in older versions of Safari browser. The key is only displayed in the browser. Should you be unable to update Safari, we recommend storing the key manually using ⌘+S.

The 3DS SDK throws an error with the Error Code 1310, and Error Message "Failed verification of certificate chain from acsSignedContent" on the sandbox environment

To successfuly test the authentication using 3DS SDK on the sandbox (integration) environment it’s necessary to configure the following test Monet+ CA certificate within 3DS SDK. This certificate is used on the sandbox environment on the „issuer“ simulator side, the same certificate (for VISA and also for MasterCard cards) has to be used within 3DS SDK. The certificate serves to protect the exchanged data.

MIIDRTCCAi2gAwIBAgIJAJLLxUToqEONMA0GCSqGSIb3DQEBBQUAMDkxCzAJBgNVBAMMAmNhMQ4wDAY
DVQQKDAVNb25ldDENMAsGA1UEBwwEWmxpbjELMAkGA1UECAwCQ1owHhcNMTkwNTAyMTA1MDI4WhcNMz
kwNDI3MTA1MDI4WjA5MQswCQYDVQQDDAJjYTEOMAwGA1UECgwFTW9uZXQxDTALBgNVBAcMBFpsaW4xC
zAJBgNVBAgMAkNaMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApdbbhP/jFppHzJlvwAfs
3OJwf6aE4KHtQNX9OxZQEYU9oIaka1skt6cDdYPgnBq0V/NZyT6QhELQH0Jz1ODO7k54uDfHPKVa6q2
SCMHgtWzS1MnATTIs4Tk1MZmaUffcq0i8FZCkDUaTMvw3zjNXKNK63CTmzbZn780X5DsrOLe7PZhjY0
Oh3/xHmkPJxv6VyrQZrwS7sLVnHRNehubpcdRbSjTQ6vKvJijHFVLWWOaMCNF1mCpNNlx2ryhI2B28/
hjUoiWZOkuXENe2Zd6uGiyq4L3G6u5xQtb3agKYScly/Wsf4Um6WX/Fxq9rjvGFiuF8Taoat3UsC2WI
RiweswIDAQABo1AwTjAdBgNVHQ4EFgQUetOWxknkAOSnbLkRKuaCrEnTEAMwHwYDVR0jBBgwFoAUetO
WxknkAOSnbLkRKuaCrEnTEAMwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAiobsm/gVej
bD+bskg62Gg/X6dqn7TcixKT5EqseyIf32f+sUn2qG5UiK7L31wWzhhY5hvCrgDw0pHdVKNxC0Hm6DC
bnEExHUxXJWZi3F51xj4VHlrn6ZcVbTG79S30fxe4X2XNlXpdIGuTmPY4pl9p7YnB8edDJXpaP5BltJ
xTVhVIjwf7zxFemhW1ADOCg+Rv5SuakQjlR7Q2hKk0d7S/4urcEWRJABf4b4RsWJ/p7KJlBHRYSIX2z
DOKfsBRly5VIJhSgU9+gqztybhmTaBkapilSLSBNR0tTAeDZWlHz4Lbfx0IqF9FE4AukC4Lyqj6n/xg
Nvs8PfBjNaTLluIw==

Device fingerprint and its usage

There are two occurrences of fingerprint structure in the API, the merchant has to use it in the following way:

  • in case of a browser payment and if the issuer requires device fingerprint to be processed the fingerprint structure is returned in a response of a init call (data is returned in actions.fingerprint.browserInit). In case of app payment (with integrated SDK) the fingerprint structure is returned in a response of a init call (actions.fingerprint.sdkInit) in order to initialize SDK.
  • the fingerprint structure is sent in a request of a process call. It contains additional data for payment authentication (either browser parameters or SDK parameters needed for a payment authentication). If clientInitiated parameter is set to true in oneclick/init operation, the fingerprint structure in oneclick/process is mandatory. It is always mandatory for applepay/process and googlepay/process calls.

In case of payment via browser it is up to card issuer if browser fingerprint is required (the merchant is obliged to process browser fingerprint if actions.fingerprint.browserInit is returned in a response of a init call). Although browser fingerprint is not required by the issuer, the merchant has to send all required parameters for 3DS authentication in a request of process call. The merchant has to collect additional data for payment authentication (see documentation) on the eshop side, all parameters then fill in into fingerprint.browser structure and send in a process call).

💳 Payment gateway

  1. Payment lifecycle
  2. Integration and API security
  3. Activation of the production environment
  4. Test cards and credentials
  5. API Sunset

💰 Payments

  1. Payment Authentication
  2. Basic Payment
  3. OneClick Payment
  4. Custom Payment
  5. Apple Pay
  6. Google Pay
  7. Collecting partial card payment
  8. ČSOB Payment Button
  9. Payment Skip Pay

🔬 eAPI 1.9

  1. API Integration
  2. Request Signing and Response Signature Validation
  3. API Methods Overview
  4. Basic Methods
  5. Methods for OneClick Payment
  6. Methods for Apple Pay
  7. Methods for Google Pay
  8. Methods for ČSOB Payment Button
  9. Methods for Skip Pay
  10. Purchase metadata

📐 Tools & how-to

  1. Payment method presentation
  2. Merchant Logo
  3. Colour scheme

📟 API extensions

  1. Extensions concept
  2. Exact date and time of transaction authorization
  3. Card data for OneClick Payment
  4. Card data for Basic Payment
  5. Tokenization
  6. Customer validation code

🔧 Frequently Asked Questions

  1. Payment methods and processing FAQ
  2. Technical FAQ
Clone this wiki locally