Skip to content

Hosted Payment Form Integration

1. Overview

This document gives technical details required for using ICS Connectx hosted payment form. It specifies required and optional fields sent with transactions, and it describes possible responses returned by ICS gateway. Documents intended readers are merchant's technical teams in charge of ICS Gateway integration.

When using this options the merchant will have to provide additional details to ICS during on-boarding. Specifically, the merchant will have to provide:

  • 'payment success URL' where the end user will be redirected if the transaction is approved.
  • 'payment fail URL' where the end user will be redirected if the transaction is declined.

The merchant will receive a tracking id as a GET parameter to the URLs defined above allowing transactions identification.

Authentication credentials required to use hosted payment form: * icsid - random alphanumeric string * userid - random alphanumeric string * storeid - pseudorandom alphanumeric string usually containing full or partial merchant name * auth_token - random alphanumeric string

2. Initial form request

In order to show the payment form a POST request must be done. It must contain following fields:

  • auth_token – authorization token that identifies you as the merchant.
  • digest – a security SHA-256 hash built by concatenating and hashing the following values: icsid + userid + storeid + auth_token + order_number + amount + currency. The correct hash is populated in the attached form.
  • transtype - should be FR (Form Request)
  • firstname – first name of the cardholder used to pre-populate the form
  • lastname – last name of the cardholder used to pre-populate the form
  • currency – three letter currency code used to pre-populate the form
  • amount – transaction amount
  • order_number – merchant's order number

Additional fields may be required in this initial POST request based on acquirer requirements or merchant needs. Merchants have to implement this post request in their website and redirect the user to the response which will be the payment form. Fields listed here will be used to pre-populate the payment form. Response to this POST request will be the payment form with pre-populated values.

3. Cardholder interacts with the payment form

Once cardholder enters their card number, expiry and cvv and hits Submit the form will be submitted to our API. If 3DS is enabled the cardholder may be required to complete 3DS steps.

4. Cardholder redirection back to merchants website

After transaction processing is finished the cardholder will be redirected to the success or fail URLs provided by the merchant. Tracking id of the transactions will be sent as a GET parameter allowing the merchant to identify the transaction. Our query API may be used to fetch additional transaction details.