Integration and API security

eCommerce is operated in the open internet; data travelling between the e-shop system and the payment gateway must be secured against external attacks. The communication channel is secured by the SSL protocol. To verify the merchant’s authenticity, all the requests sent to the payment gateway are signed by the merchant’s private key.

The payment gateway knows the public key, which can be used to verify whether the request was generated by this particular merchant. In order to function correctly, the private key + public key pair must be generated, the private key must be forwarded to the merchant’s system (e-shop, backoffice, etc.) and the public key must be forwarded to the payment gateway, i.e. the bank. This process is part of the merchant and gateway integration.

Phase One of the integration follows after the eCommerce service is approved by the bank. The bank assigned the merchantID and the merchant notified the bank about the e-mail address for communication purposes. At this moment, the merchant’s identity exists in the payment gateway system. Further steps are to take place, as follows:

Test key generation Tools for test key generation are available at the bank's website. The merchant downloads a JavaScript application containing the key generator to the merchant’s website. The generator wizard will perform the following steps:

1. It will request the payer to enter the merchantID and registered e-mail address;
2. It will check on the payment gateway whether the merchant is registered and in which phase the registration is;
3. It will offer only the option to generate test keys;
4. It locally generates a pair of test keys (private key/public key);
5. The private key is stored in the merchant’s computer;
6. The public key is forwarded to the payment gateway through a secure channel.

Integration - At this moment, the merchant may launch its solution (e-shop) integration with the payment gateway. The private key is forwarded to development; it can be developed and tested on the public iGateway. The key is automatically implemented there after having been generated.

Integration environment (for testing)

For testing and integration of the e-shop to the payment gateway eAPI the merchant should use the integration environment (sandbox) available at https://iapi.iplatebnibrana.csob.cz.

3DS authentication and payment authorization are processed against a simulator, the rest of payment gateway functionality including eAPI and user interface is identical to the production environment. The merchant can test redirecting from the e-shop to the payment gateway and back (parameters exchange) as well as checking a user interface of the payment gateway - merchant's logo, contact details, cart content or custom colour scheme.

Approval - After the integration process has been completed, the merchant notifies the bank and does a series of prescribed tests. The bank will verify their result against the records of the test iGateway. If the answer is affirmative, the merchant is activated.

Live key generation - At this moment, the merchant may generate new, live keys which will be used for the operating environment. The merchant uses the production key generator available at the online, which works as follows:

1. It will request the payer to enter the merchantID and a registered e-mail address;
2. It will check on the payment gateway whether the merchant is registered and in which phase the registration is;
3. It will find out that the merchant has been activated and the integration tests have been fulfilled;
4. It locally generates a pair of live keys (private key/public key);
5. The private key is stored in the merchant’s computer;
6. The public key is forwarded to the payment gateway through a secure channel;
7. The payment gateway sends an activation code to the merchant’s registered address.

Confirmation of a live key by the merchant To increase security, but also if the merchant needs to exchange the key on the fly, there is one more step compared with the test environment:

The merchant has access to the ČSOB POS Merchant system where the newly generated key appears in the eCommerce section. This is the point where the merchant confirms and activates the key. To perform this operation, the merchant must have a one-time activation code, which the gateway sent to the merchant’s e-mail address after the gateway had received the public key. After this activation, the key is forwarded to the payment gateway and it starts to use it straight away. This step provides double security of the key forwarding and the merchant also decides when the key is implemented on the gateway.

Public sandbox

The system enables API interface and preparation for the e-shop integration before visiting the bank and without any obligations. This process is referred to as the “anonymous development”. This means that it is possible to involve the development first, to verify the functionality of the connection and then proceed to Phase One, visit the bank and connect to the test environment with the merchantID obtained from the bank.

In reality, everything is done in the same way as Phase One. The merchant chooses the Anonymous development option in the key generation wizard on the website https://iplatebnibrana.csob.cz/keygen (no merchantID or e-mail address details are filled in) and the wizard requests the gateway to assign a development merchantID. The merchant then generates keys on his computer for such merchantID, the public key is forwarded to the payment gateway and the private one is stored in a file.

The test access for anonymous development is valid for one month, as the test keys. Accesses using anonymous development are monitored and in case they do not correspond to development and testing purposes, such services may be limited for this merchantID.