Integration and API security - khpos/Payment-gateway_EN GitHub Wiki

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 (Merchant ID is vPOS Terminal ID / Gateway ID. (eg. M1TEST1234)) 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:

img/en_HU/keys-concept-en.png

Test key generation Tools for test key generation are available at the Test environment key generation tool and the key generation process is described in detail here: Key generation. The generator wizard will perform the following steps:

  1. It will request the payer to enter the merchantID (Merchant ID is vPOS Terminal ID / Gateway ID. (eg. M1TEST1234)) 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://api.sandbox.khpos.hu/.

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 does a series of prescribed tests and notifies the K&H Payment services, who verify the integration quality, If the integration works properly, 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 PROD environment key generator tool and the key generation process is described in detail here: Key generation, 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 K&H POS 24 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.