Skip to content

Pay By Link Integration

Overview

This document describes how to use the 'pay_by_link' feature of the Connectx gateway.

Gateway endpoint URL

All incoming transactions must be sent over SSL/HTTPS to URL:

Merchant Authentication

Merchants have to authenticate using parameters required by ICS Connectx Gateway:

  • icsid - random alphanumeric string
  • userid - random alphanumeric string
  • storeid - pseudorandom alphanumeric string usually containing full or partial merchant name
  • auth_token - random alphanumeric string specifically used with the hosted payment form

All parameters will be issued on a per merchant basis during merchant on-boarding. A combination of these parameters are required for all transactions sent to ICS Connectx Gateway depending on integration type.

Merchant makes a POST request to https://secure.icsaccess.com/payment_form with the following parameters:

Required request fields

Note that some additional fields may be required depending on the acquirer.

  • authtoken - ICS authentication parameter.
  • digest - ICS authentication parameter. It is calculated by creating an SHA256 hash of string made of the following parameters in this exact order: icsid + userid + storeid + auth_token + order_number
  • transtype - must be 'FR' (Form Request)
  • amount – Transaction amount. Two decimal places allowed. Dot as decimal separator (9.29, 0.99, 122.50).
  • currency - Currency code. USD if omitted. ISO 4217 currency code or number. See ISO 4217 currency codes for details.
  • order_number - Merchant defined order number.
  • pay_by_link_init - Send '1' to indicate that this is a request for a payment form link
  • content_type - Send 'application/json'

Optional request fields

  • firstname - Card holder first name.
  • lastname - Card holder last name.
  • address - Card holder address.
  • city - Card holder city.
  • state - Card holder state.
  • zip - Card holder zip code.
  • country - Card holder country code. ISO 3166-1 alpha-2, alpha-3 or numeric code. See ISO 3166 country code for details.
  • phone - Card holder phone number.
  • email - Card holder email address.
  • recurring - Recurring flag. Possible values are 1 or 0. Set recurring flag to 1 with CVV to initiate recurring. Set recurring flag to 1 without CVV on recurring transactions. Depending on the acquirer trackingid might be required.
  • trackingid - Trackingid of the original transaction when recurring was initated. Send when recurring flag is set to 1.
  • ip - External IP of transaction origin.
  • initial_transaction_type - indicates the type of transactions that will be attempted on the payment form. Defaults to a regular sale.
  • {custom} - Custom field name and value depending on the acquirer

Response fields Response will be JSON with the following fields:

Note that the payment link can only be used once. If a transaction is created using the payment link no future transactions will be possible using the same link.

  • pay_by_link_url - URL customer must go to open the payment form prepopulated with the data from the original request
  • pay_by_link_tracking_id - Tracking id used to uniquely identify this link.
  • expires_at_utc - UTC date and time after which the link is no longer valid (YYYY-MM-DD HH:MM:SS format). Defaults to 60 minutes but can be adjusted based on business requirements.

Example form request init pay bay link request and responses

  • Request:

Example curl:

 curl --request POST \
--url http://secure.icsaccess.com/payment_form \
--header 'Content-Type: application/json' \
--data '{
  "auth_token": "test_token",
  "digest": "8ffae2d13dc33a7884777a889272204f196eae8b67b91ec62782b7808c73899ff",
  "transtype": "FR",
  "amount": "200.01",
  "firstname": "Test",
  "lastname": "Card",
  "currency": "EUR",
  "address": "Address 15",
  "city": "SaltLake",
  "state": "Arizona",
  "zip": "60623",
  "country": "USA",
  "phone": "123456789",
  "email": "josh@example.com",
  "order_number": "123456",
  "content_type": "application/json",
  "initial_transaction_type": "NA",
  "pay_by_link_init": "1"

}'

  • Response:
{
    "pay_by_link_url": "http://secure.icsaccess.com/payment_form?q=007df738bceb439ba194d5817e7b29ad&pbl=1",
    "pay_by_link_tracking_id": "007df738bceb439ba194d5817e7b29ad",
    "expires_at_utc": "2022-07-05 08:50:03"
}

2. User interaction with the payment form and redirection to merchant website

User enters their card data into the payment form and clicks on 'submit'. Transaction is processed by the acquirer and the user is redirected to either:

  • success URL - URL defined b the merchant when the transaction is approved.
  • fail URL - URL defined by the merchant when the transaction is declined.

ICS Connectx gateway will attach additional transaction info as GET query parameters to the success and fail URLs to provide information about the transaction to the merchant.