Home
➡️ Please use the navigation on the right
The basic 3D Secure 2 support (available on the payment gateway since 2020) is now significantly extended to support purchase metadata that improves payment authentication. Providing more metadata about the purchase has a direct positive impact on the payment experience - the more data the e-shop provides, the higher is the probability of payment processing without confirmation by the customer.
The most important changes are related to the OneClick payment. Checkouts must be flagged as customer-initiated (customer is present in the checkout flow; the stored card is used only for convenience) or merchant-initiated (customer is not present; the transaction is e.g. a subscription payment). The e-shop must be ready to perform customer authentication without redirecting the customer to the payment gateway. The resulting API changes have a significant impact on the OneClick payment process.
Please plan the transition to API 1.9 depending on the payment methods that you are using.
Basic payment (with redirect to the payment gateway)
- We strongly recommend the provision of the purchase metadata to the payment gateway. The card issuer is very likely to authenticate the payment without confirmation by the customer (based on the metadata) and the payment will be faster and more convenient.
- Use of Apple Pay initiated from the payment gateway UI does not require any additional changes.
OneClick payment
- The payment context must be recognized by the e-shop and indicated to the payment gateway. Customer initiated and merchant initiated transactions are handled differently.
- API methods for OneClick payment are significantly changed to support the full 3D Secure authentication of OneClick payments directly in the e-shop, without the need to redirect the customer to the payment gateway. Please check out carefully the new set of API methods for OneClick payment.
Apple Pay in your e-shop or mobile app
- If you are using Apple Pay integration directly in your e-shop or mobile application, you will need to switch to the new Apple Pay processing method that works with the purchase metadata (Apple Pay payment initiation). The subsequent payment processing logic is able to authenticate the payment in the e-shop (just in case the card issuer requests full 3D Secure 2 authentication).
- The new API methods use the same processing logic for OneClick payment, Apple Pay and Google Pay. We recommend the implementation of all these three comfortable payment methods.
Changes in payment authentication have no impact on Skip Pay payment and the ČSOB payment button.
We have stepped up the security also for Apple Pay in a way that prevents the need for 3D Secure authentication for Apple Pay while achieving the level of payment authentication required by the law and Visa / Mastercard. The high payment comfort of Apple Pay is further ensured - there is no change for the customers (Apple Pay authentication is performed on the device using Face ID or Touch ID). E-shop must send the same purchase metadata as for basic card transactions. The related changes are described in the technical documentation. The payment process for Apple Pay and the newly added Google Pay is unified. We recommend implementing both wallets at the same time.
Payment gateway API supports Google Pay integration directly in e-shops and native Android mobile apps. Customers can use cards in their Android phones as well as cards stored in their Google Accounts. Payment with Android is very similar to Apple Pay (authentication is performed by the phone). Payment using a card stored in the Google Account requires full authentication using 3D Secure 2. Please refer to the detailed description of Google Pay set-up as well as the API documentation for Google Pay.
In accordance with the decision of the Czech Republic government to cancel the ESR service, the ESR functionality on our payment gateway was fully restricted by 12/31/2022. The ESR extension (in API 1.6, 1.7 and 1.8) is no longer supported.
The new eAPI is the present and the future of the communication between the merchant and the payment gateway. Before integrating the payment gateway into your e-shop or eAPI mobile application, please see the complete eAPI documentation between the e-shop and the payment gateway, see how to simulate different transaction states and what test cards to use.
Supported versions are currently 1.0, 1.5, 1.6, 1.7, 1.8 and 1.9. We recommend always using the latest version. Termination of older versions is described on API Sunset page.
| eAPI version | Introduced | Not recommended | Termination date | New features and changes |
|---|---|---|---|---|
| 1.0 | 06/2015 | 10/2018 | 3/1/2023 | Default version when a new payment gateway starts. |
| 1.5 | 10/2015 | 10/2019 | 4/1/2023 | A recurring payment (registration and subsequent execution) added, partial transaction refunds allowed. From 2/1/2023 Oneclick payment is allowed only in eAPI 1.9. |
| 1.6 | 04/2016 | 10/2019 | 4/1/2023 | A posting date (extension) added, this allows you to set transaction lifetime at the payment gateway and multibranding option on one merchantID (multiple colour schemes, logotypes). |
| 1.7 | 01/2017 | 10/2019 | 5/1/2023 | This version adds support for MasterPass (already discontinued in 2020) and ČSOB and ERA payment buttons (to replace PaySec). In parallel, the ESR support was available in eAPI 1.6, 1.7 and 1.8 (in eAPI 1.9 no longer supported, the ESR functionality was terminated by 12/31/2022). |
| 1.8 | 10/2019 | 04/2022 | n/a | This version adds support for Apple Pay, mallpay, Custom payments, changes the signature algorithm to SHA-256, and adds the obligation to forward a client IP address for OneClick payment. In a payment/init operation a description parameter has been cancelled (it changes the signature calculation too). From 2/1/2023 Apple Pay payment is allowed only in eAPI 1.9. |
| 1.9 | 04/2022 | n/a | n/a | This version adds support for Google Pay and extends support for authentication of card transactions using 3D Secure 2. Revenue reporting to ESR is no longer supported. |
For a new implementation, we recommend that you always choose the latest available API version.
| Function | Call | 1.0 | 1.5 | 1.6 | 1.7 | 1.8 | 1.9 |
|---|---|---|---|---|---|---|---|
| Basic payment | payment/init |
✔️ 1 | ✔️ 1 | ✔️ | ✔️ | ✔️ | ✔️ |
| Recurring payment | payment/recurrent |
– | ❌8 | – | – | – | – |
| OneClick payment | payment/oneclick |
– | – | ❌ 2,8 | ❌ 2,8 | ❌8 | ✔️ |
| Apple Pay | applepay/init |
– | – | – | – | ❌9 | ✔️ |
| Google Pay | googlepay/init |
– | – | – | – | – | ✔️ |
| Custom payment | payment/init |
– | – | – | – | ✔️ | ✔️ |
| mallpay (Skip Pay) | mallpay/init |
– | – | – | – | ✔️ | ✔️ |
| ČSOB payment button | button/init |
– | – | – | ✔️ 3 | ✔️ | ✔️ |
| Check payment status | payment/status |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Reverse the transaction | payment/reverse |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Include transactions to clearing | payment/close |
✔️ 4 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Request for refund transaction | payment/refund |
✔️ 5 | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Checking the gate | echo |
✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
| Checking the customer | echo/customer |
✔️ 6 | ✔️ 6 | ✔️ 6 | ✔️ 6 | ✔️ | ✔️ |
| Reporting ESR revenue | extension | – | – | ❌ | ❌ | ❌ | –7 |
1) does not allow to set transaction lifetime (default 30 min only), does not support multibranding
2) in eAPI 1.8 the operation payment/oneclick/init was renamed to oneclick/init
3) in eAPI 1.8 the operation payment/button was renamed to button/init
4) eAPI 1.0 allows posting only in full, version eAPI 1.5 and higher support also the partial payment collection
5) eAPI 1.0 supports only refunds of full amount; version eAPI 1.5 and higher support also a partial refund, including repeated partial refunds up to the amount of the original transaction
6) in eAPI 1.8 the operation customer/info was renamed to echo/customer
7) ESR support is no longer available in eAPI 1.9. The ESR functionality was terminated in eAPI 1.6, 1.7 and 1.8 by 12/31/2022.
8) Sunset of OneClick payments for eAPI 1.8 and below (all OneClick templates created in older eAPI versions can be used in eAPI 1.9).
9) Sunset of the Apple Pay payment method integrated directly into the merchant's e-shop (applepay@shop) for eAPI 1.8 and below.
To integrate and test the connection of the e-shop to the eAPI payment gateway, an integration environment (called iGateway) running at https://iapi.iplatebnibrana.csob.cz is available for the merchant. iGateway is nothing more than an open sandbox to play - no contract and no complications. You can find the documentation and the encryption key generation tool here on Git and try our payment gateway now.
In this environment, 3DS authentication and payment authorization are performed against the simulator (so, please use these cards). However, the functionality of the payment gateway, including eAPI and the user interface, is identical to the production environment. You can test not only the transition from the e-shop to the payment gateway and back (passing parameters using the API) but also the final appearance of the payment gateway - display the merchant's logo and contact details, display cart and colour scheme.