Transaction API Integration

Overview¶

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

Gateway endpoint URL¶

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

https://secure.icsaccess.com/api

Merchant Authentication¶

Merchants have to authenticate using three 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

All three parameters will be issued on a per merchant basis during merchant on-boarding. These three parameters are required for all transactions sent to ICS Connectx Gateway.

Content Type Header¶

ICS Connectx Gateway endpoint supports the following request/response formats which are defined by setting the Content-Type header:

URLQS (application/x-www-form-urlencoded)
XML (application/xml)
JSON (application/json)

In order to use specific format it's necessary to set a Content-Type header.

URLQS is used as default when no Content-Type is being specified in headers.

ICS Connectx Gateway will always reply using the same Content-Type that was used in the request.

Transaction types¶

The following section lists all available transaction types, required and optional fields that should be sent as well as responses from ICS Connectx Gateway. ICS Connectx Gateway has the flexibility to accommodate custom fields in both requests and responses and can modify transaction processing logic based on the values of those fields. There is currently no limit to the number of custom fields that can be sent to ICS Connectx Gateway.

Custom fields are processed and returned only after their role has been approved by ICS technical team.

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

1. Sale and Preauthorization¶

Transaction types indicators that should be sent as the value of transtype field:

sale - NA
preauthorization - AO

Required request fields

icsid - ICS authentication parameter.
userid - ICS authentication parameter.
storeid - ICS authentication parameter.
account - Credit card number.
transtype - Sale or Preauthorization transaction type indicator.
cvvcode – Credit card CVV code. Cvvcode should be omitted for recurring transactions. Recurring flag should be set to 1 with CVV omitted on recurring transactions.
expdate – Credit card expiration date in MMYY format (1019 for card that expires in October of 2019).
amount – Transaction amount. Two decimal places allowed. Dot as decimal separator (9.29, 0.99, 122.50).

Optional request fields

firstname - Card holder first name.
lastname - Card holder last name.
address - Card holder address. This field will be used in address verification if enabled for the merchant and supported by the acquirer. Example format for address verification (Spachbrücker Str. 21, 64354 Reinheim | 1 Elm Street, Valley Stream, NY 1151) - max Length 49
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 reuqired.
currency - Currency code. USD if omitted. ISO 4217 currency code or number. See ISO 4217 currency codes for details.
invoice - Will be used as internal ICS order number if provided. It will be returned as ordernumber field in the transaction response. If this field is not present ICS
trackingid - Will be used along recurring flag set to 1.
Connectx Gateway will generate a pseudo-random order number based on the current merchant group transaction count and tracking id.
ip - External IP of transaction origin.
eci - 3DS field
cavv - 3DS field
xid - 3DS field
ucaf - 3DS field
sli - 3DS field
useragent - field required for some acquirers. example: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36
browseragent - field required for some acquirers. Specifies content type. example: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,/;q=0.8
{custom} - Custom field name and value

Response fields

resultstatus - Approved, Declined, Processing, Error - see ICS Connectx Gateway Responses for a complete list.
resulttext - Approved, Declined, Processing, Error or custom description - see ICS Connectx Gateway Responses for a complete list.
resultcode - One of ICS result codes - see ICS Connectx Gateway Responses for a complete list.
status - 1, 2 or 3 - 1 for Processing, 2 for Approved, 3 for Declined or Error - see ICS Connectx Gateway Responses for a complete list.
version - ICS Connectx Gateway version that processed the transaction
timestamp - date and time transaction was received (EST timezone)
timestamp_utc - date and time transaction was received (UTC timezone)
ordernumber - transaction order number
currency - transaction currency
transtype=NA - Sale transaction type
trackingid - ICS Connectx Gateway id that uniquely identifies the transaction
authcode - Approved transaction authentication code. May be omitted depending on acquirer.
avs_result - Address verificiation result if supported by acquirer and if enabled for the merchant. Values possible [exact_match, no_match, unavailable, ]
{custom} - Returning custom field name and value that was sent with the transaction.

Example sale request and responses

URLQS

Request:

curl -i -H "Content-Type: application/json" -d '{
icsid=111111
&userid=111111
&storeid=111111
&transtype=transaction type indicator
&amount=84.90
&currency=USD
&version=3.0&
firstname=John
&lastname=Doe
&account=4111***1111
&expdate=***
&cvvcode=***
&invoice=custom_order_number
&ip=104.50.234.210
&address=155+Test+Street
&city=Charleston
&state=SC
&zip=29403
&phone=1112221112
&email=john.doe@example.comt
&country=US
&my_custom_field=some_value } https://secure.icsaccess.com/api

¶

Response when approved:

resulttext=Approved
&resultstatus=approved
&version=3.00
&timestamp=2016-10-06+06:58:13
&trackingid=746fcb64b3409d9e
&authcode=19466
&transtype=transaction type indicator
&resultcode=00
&custom_field=some_value
&timestamp_utc=2016-10-06+06:58:13
&ordernumber=custom_order_number

¶

Response when declined:

resulttext=Declined
&resultstatus=declined+Do+not+Honor(Not+Accepted)
&version=3.00
&timestamp=2016-106+06:58:13
&trackingid=746fcb64b3409d9e
&authcode=19466
&transtype=transaction type indicator
&resultcode=99
&timestamp_utc=2016-10-06+06:58:13
&ordernumber=custom_order_number

JSON

Request:

Example curl:

curl -i -H "Content-Type: application/json" -d '{
    "icsid": "111111",
    "userid": "111111",
    "storeid": "111111",
    "transtype": "transaction type indicator",
    "amount": "1.01",
    "currency": "USD",
    "invoice": "custom_order_number",
    "version": "3.0",
    "firstname": "Tester",
    "lastname": "Tester",
    "account": "4111111111111111",
    "expdate": "0619",
    "cvvcode": "123",
    "address": "test_address",
    "city": "Charleston",
    "state": "SC",
    "zip": "85284",
    "phone": "123123123",
    "email": "tester@example.com",
    "country": "USA",
    "ip": "104.50.234.210" } https://secure.icsaccess.com/api

Response when approved:

{
    "cardtype": "CC",
    "transtype": "transaction type indicator",
    "status": 2,
    "trackingid": "347f5bbe1f294998a4d7409772546d7f",
    "resulttext": "Approved",
    "resultstatus": "Approved",
    "version": "3.00",
    "resultcode": "00",
    "timestamp": "2017-08-24 03:54:51",
    "authcode": "UU05JXUGFQ",
    "timestamp_utc": "2016-10-06+06:58:3",
    "ordernumber": "custom_order_number"
}

Response when declined:

{
    "cardtype": "CC",
    "transtype": "transaction type indicator",
    "status": 3,
    "trackingid": "347f5bbe1f294998a4d7409772546d7f",
    "resulttext": "Declined",
    "resultstatus": "Declined",
    "version": "3.00",
    "resultcode": "00",
    "timestamp": "2017-08-24 03:54:51",
    "timestamp_utc": "2016-10-06+06:58:3",
    "ordernumber": "custom_order_number"
}

XML

Request:

Example curl:

    curl -i -H "Content-Type: application/xml" -d'
    <?xml version="1.0" encoding="UTF-8" ?>
    <request>
        <icsid>111111</icsid>
        <userid>111111</userid>
        <storeid>111111</storeid>
        <transtype>transaction type indicator</transtype>
        <amount>1.01</amount>
        <currency>USD</currency>
        <invoice>custom_order_number</invoice>
        <version>3.0</version>
        <firstname>Tester</firstname>
        <lastname>Tester</lastname>
        <account>4111111111111111</account>
        <expdate>0619</expdate>
        <cvvcode>123</cvvcode>
        <address>test_address</address>
        <city>Charleston</city>
        <state>SC</state>
        <zip>85284</zip>
        <phone>123123123</phone>
        <email>tester@example.com</email>
        <country>USA</country>
    </request>
    ' https://secure.icsaccess.com/api

Response when approved:

<response>
    <resulttext>Approved</resulttext>
    <resultstatus>Approved</resultstatus>
    <authcode>YFW5YCB8MN</authcode>
    <status>2</status>
    <version>3.00</version>
    <timestamp>2017-08-24 04:31:39</timestamp>
    <trackingid>313b81c4ed1b4146b14ddc5d0a323b41</trackingid>
    <resultcode>00</resultcode>
    <cardtype>CC</cardtype>
    <transtype>transaction type indicator</transtype>
    <timestamp_utc>016-10-06+06:58:3</timestamp_utc>
    <ordernumber>custom_order_number</ordernumber>
</response>

Response when declined:

<response>
    <resulttext>Do Not Honor</resulttext>
    <resultstatus>Declined</resultstatus>
    <status>3</status>
    <version>3.00</version>
    <timestamp>2017-08-24 04:31:39</timestamp>
    <trackingid>313b81c4ed1b4146b14ddc5d0a323b41</trackingid>
    <resultcode>00</resultcode>
    <cardtype>CC</cardtype>
    <transtype>transaction type indicator</transtype>
    <timestamp_utc>016-10-06+06:58:3</timestamp_utc>
    <ordernumber>custom_order_number</ordernumber>
</response>

2. Credit, Capture and Void¶

Transaction types indicators that should be sent as the value of transtype field:

credit - CR
capture - PA
void - VD

Order number of Credit, Capture and Void transactions will always be the same as the order number of the parent transaction they are referring to.

Required request fields

icsid - ICS authentication parameter.
userid - ICS authentication parameter.
storeid - ICS authentication parameter.
transtype - Credit, Capture or Void transaction type indicator.
trackingid – Tracking id of the previous parent transaction that is being acted upon

Optional request fields

If optional fields are not present values from parent transaction will be used

firstname - Card holder first name.
lastname - Card holder last name.
amount – Transaction amount. Two decimal places allowed. Dot as decimal separator (9.29, 0.99, 122.50). Full credit/capture/void will be attempted if amount is not provided.
currency - Currency code. USD if omitted. ISO 4217 currency code or number. See ISO 4217 currency codes for details.
{custom} - Custom field name and value

Response fields

resultstatus - 1, 2 or 3 - see section ICS Responses for a complete list
resulttext - Approved, Declined, Processing, Error - see section ICS Responses for a complete list
resultcode - One of ICS result codes - see section ICS Responses for a complete list
version - ICS Connectx Gateway version that processed the transaction
timestamp - date and time transaction was received (EST timezone)
timestamp_utc - date and time transaction was received (UTC timezone)
ordernumber - transaction order number
currency - transaction currency
transtype=NA - Sale transaction type
trackingid - ICS Connectx Gateway id that uniquely identifies the transaction
authcode - Approved transaction authentication code. May be omitted depending on acquirer.
{custom} - Returning custom field name and value that was sent with the transaction.

Example sale request and responses

URLQS

Request:

curl -i -H "Content-Type: application/json" -d '{
icsid=111111
&userid=111111
&storeid=111111
&transtype=transaction type indicator
&amount=84.90
&currency=USD
&trackingid=313b81c4ed1b4146b14ddc5d0a323b41
} https://secure.icsaccess.com/api

¶

Response when approved:

resulttext=Approved
&resultstatus=approved
&status=2
&version=3.00
&timestamp=2016-10-06+06:58:13
&trackingid=746fcb64b3409d9e
&authcode=19466
&transtype=transaction type indicator
&resultcode=00
&custom_field=some_value
&timestamp_utc=2016-10-06+06:58:13
&ordernumber=custom_order_number

¶

Response when declined:

resulttext=Declined
&resultstatus=declined+Do+not+Honor(Not+Accepted)
&status=3
&version=3.00
&timestamp=2016-106+06:58:13
&trackingid=746fcb64b3409d9e
&authcode=19466
&transtype=transaction type indicator
&resultcode=99
&timestamp_utc=2016-10-06+06:58:13
&ordernumber=custom_order_number

JSON

Request:

Example curl:

curl -i -H "Content-Type: application/json" -d '{
    "icsid": "111111",
    "userid": "111111",
    "storeid": "111111",
    "transtype": "transaction type indicator",
    "amount": "1.01",
    "currency": "USD",
    "trackingid": "313b81c4ed1b4146b14ddc5d0a323b41" }' https://secure.icsaccess.com/api

Response when approved:

{
    "cardtype": "CC",
    "transtype": "transaction type indicator",
    "status": 2,
    "trackingid": "347f5bbe1f294998a4d7409772546d7f",
    "resulttext": "Approved",
    "resultstatus": "Approved",
    "version": "3.00",
    "resultcode": "00",
    "timestamp": "2017-08-24 03:54:51",
    "authcode": "UU05JXUGFQ",
    "timestamp_utc": "2016-10-06+06:58:3",
    "ordernumber": "custom_order_number"
}

Response when declined:

{
    "cardtype": "CC",
    "transtype": "transaction type indicator",
    "status": 3,
    "trackingid": "347f5bbe1f294998a4d7409772546d7f",
    "resulttext": "Declined",
    "resultstatus": "Declined",
    "version": "3.00",
    "resultcode": "00",
    "timestamp": "2017-08-24 03:54:51",
    "timestamp_utc": "2016-10-06+06:58:3",
    "ordernumber": "custom_order_number"
}

XML

Request:

Example curl:

    curl -i -H "Content-Type: application/xml" -d'
    <?xml version="1.0" encoding="UTF-8" ?>
    <request>
        <icsid>111111</icsid>
        <userid>111111</userid>
        <storeid>111111</storeid>
        <transtype>transaction type indicator</transtype>
        <amount>1.01</amount>
        <currency>USD</currency>
        <trackingid>313b81c4ed1b4146b14ddc5d0a323b41</trackingid>
    </request>
    ' https://secure.icsaccess.com/api

Response when approved:

<response>
    <resulttext>Approved</resulttext>
    <resultstatus>Approved</resultstatus>
    <status>2</status>
    <authcode>YFW5YCB8MN</authcode>
    <status>2</status>
    <version>3.00</version>
    <timestamp>2017-08-24 04:31:39</timestamp>
    <trackingid>313b81c4ed1b4146b14ddc5d0a323b41</trackingid>
    <resultcode>00</resultcode>
    <cardtype>CC</cardtype>
    <transtype>transaction type indicator</transtype>
    <timestamp_utc>016-10-06+06:58:3</timestamp_utc>
    <ordernumber>custom_order_number</ordernumber>
</response>

Response when declined:

<response>
    <resulttext>Do Not Honor</resulttext>
    <resultstatus>Declined</resultstatus>
    <status>3</status>
    <version>3.00</version>
    <timestamp>2017-08-24 04:31:39</timestamp>
    <trackingid>313b81c4ed1b4146b14ddc5d0a323b41</trackingid>
    <resultcode>00</resultcode>
    <cardtype>CC</cardtype>
    <transtype>transaction type indicator</transtype>
    <timestamp_utc>016-10-06+06:58:3</timestamp_utc>
    <ordernumber>custom_order_number</ordernumber>
</response>

Subscriptions¶

Subscriptions are a method of creating recurring payments where only the initial request is made by the merchant and all subsequent payments are handled by ICS Connectx gateway.

To create a subscription you must send the following parameters: init_recurring – flag to create subscription, recurring_days or recurring_month – period of subscription, init_amount - amount charged for the initial transaction. When you send these parameters, we set up a subscription for you that automatically sends a new transaction in periods defined by ‘recurring_days' or 'recurring_months’. Our technical team will need to enable subscriptions for each MID and the following is only applicable to MIDs if recurring subscriptions are enabled.

Example JSON request:

{
 "amount": "15.00",
 "firstname": "Test",
 "lastname": "Card",
 "currency": "EUR", 
 "order_number": "2",
 "init_recurring": "1", 
 "recurring_days": "14", 
 "init_amount": "10.00"
}

Subscription priced at 10€ for the first period and 15€ thereafter. So we create a subscription for 14 days for 10€. Then every 14 days a new transaction for 15€ will be created automatically.

Cancel subscription¶

This endpoint cancels a running recurring subscription. Endpoint documented here: https://portal.icsaccess.com/docs/query_api_integration/#cancel-a-subscription-subscription_cancellationsubscription_tracking_id