Query API Integration
Overview¶
This document explains the technical details of ICS Transaction query REST API provided to merchants. It can be used to retrieve information about transactions, chargebacks and fraud.
1. Base URL¶
Base URL for all v1 ICS Portal API calls is:
https://portal.icsaccess.com/portal_api/v1
2. HTTP headers¶
Each request (except the request for authentication) should contain the following HTTP headers:
| Header name | Example header value | Description |
|---|---|---|
| Authorization | ApiKey username:xxx | API key can be generated by using the authentication endpoint described below. Note that the this header must be in the following format: ApiKey {username}:{api_key}. Use /authentication endpoint to retrieve API key. |
| Accept | application/json | This header determines the format of responses that will be returned by the API. Possible values are application/json or application/xml. Default is application/json if this header is not present. |
3. Common GET parameters¶
Some requests (not the request for authentication) can receive and will respond to the following GET parameters:
| Parameter name | Possible values | Description |
|---|---|---|
| limit | 1 - 200 | Max number of records per page of results. |
| offset | 0 - max records | Records to skip. |
| order_by | see Endpoints section | Field by which the results should be ordered by. Default sort order is ascending. Append '-' before field name to sort in descending order. |
4. Endpoints¶
All endpoints allow only GET HTTP verb. Endpoint URL paths below have optional path parts indicated by curly braces '{}'.
Sending a request to /currency will return a list of all available currencies with default paging values. Sending a request to /currency/{currency_id} will return details about the currency with the given currency id. Same logic applies to all other endpoints as indicated in the table below.
Authentication - /authentication¶
Retrieve the API key that has to be sent with each request to other API endpoints.
-
Headers
Accept
-
Get parameters
username, password
-
Throttling
Maximum 10 requests every 20 seconds.
Currency - /currency/{currency_id}¶
Retrieve information about currencies.
-
Headers
Accept, Authorization
-
Get parameters
limit, offset
-
Throttling
Maximum 10 requests every 20 seconds.
Card type - /cardtype/{card_type_id}¶
Retrieve information about card types.
-
Headers
Accept, Authorization
-
Get parameters
limit, offset
-
Throttling
Maximum 10 requests every 20 seconds.
Merchant - /merchant/{merchant_id}¶
Retrieve information about merchants.
-
Headers
Accept, Authorization
-
Get parameters
limit, offset
-
Throttling
Maximum 10 requests every 20 seconds.
Merchant group - /merchantgroup/{merchant_group_id}¶
Retrieve information about merchant groups. Each merchant belongs to a single merchant group.
-
Headers
Accept, Authorization
-
Get parameters
limit, offset
-
Throttling
Maximum 10 requests every 20 seconds.
Transaction - /transaction/{transaction_id}¶
Retrieve information about transactions.
-
Example
https://portal.icsaccess.com/api/v1/transaction?q=ewogICAgImFtb3VudF9mcm9tIjogMC4wMCwKICAgICJhbW91bnRfdG8iOiAxM...
-
Headers
Accept, Authorization
-
Get parameters
q
Transaction API endpoint query string parameters should be passed as a base64 encoded JSON UTF-8 string named 'q'. When received the value is decoded back to json and validated against the json schema given below.
Example JSON query string before base64 encoding
{ "amount_from": 0.0, "amount_to": 10.0, "bin": "123456", "card_types": [1, 2, 3, 4, 5, 6, 7], "currencies": [ 149, 49, 150, 151], "cvv": true, "first_name": "John", "last4": "1111", "last_name": "Smith", "email": "john.smith@example.com", "merchants": [1, 2, 3], "message": "A really long message. A really long message.", "order_number": "123456789", "auth_code": "123456789", "recurring": false, "timestamp_from": "2018-01-01 00:00:00", "timestamp_to": "2018-01-15 23:45:00", "tracking_id": "07804ae706e94659abf9c8e60936a172", "transaction_statuses": [1, 2, 3], "transaction_types": [1, 2, 3, 4, 5, 6, 7], "subscriptions": ["subscription_tracking_id1", "subscription_tracking_id2"] }Transaction request query string validation schema
The transaction API endpoint base64 encoded json is defined with the following JSON schema and should validate against it.
Note that timestamp_from and timestamp_to are mandatory fields{ "$schema": "http://json-schema.org/draft-06/schema#", "title": "Transaction query string", "description": "Transaction query string definition. This defines the fields and format of the JSON that need to be sent (base 64 encoded) to the /transaction portal API endpoint. ", "type": "object", "properties": { "amount_from": { "description": "Smallest transaction amount to appear in results", "type": "number", "minimum": 0 }, "amount_to": { "description": "Largest transaction amount to appear in results", "type": "number", "minimum": 0 }, "bin": { "description": "Search for exact BIN", "type": "string", "minLength": 1, "maxLength": 25 }, "card_types": { "description": "Card type ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "currencies": { "description": "Currency ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "cvv": { "description": "Search for transaction where cvv present/not present", "type": "boolean" }, "timestamp_from": { "description": "Transaction search start date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "timestamp_to": { "description": "Transaction search end date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "first_name": { "description": "Search for transactions where cardholder first name starts with this string", "type": "string", "minLength": 1, "maxLength": 50 }, "last4": { "description": "Search for exact last 4", "type": "string", "minLength": 4, "maxLength": 4 }, "last_name": { "description": "Search for transactions where cardholder last name starts with this string", "type": "string", "minLength": 1, "maxLength": 50 }, "email": { "description": "Search for transactions where cardholder email starts with this string", "type": "string", "minLength": 3, "maxLength": 50 }, "merchants": { "description": "Merchant ids to include in search", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "message": { "description": "Search for transactions where message starts with this string", "type": "string", "minLength": 1, "maxLength": 255 }, "order_number": { "description": "Search for exact order number", "type": "string", "minLength": 1, "maxLength": 50 }, "auth_code": { "description": "Search for exact authorization code", "type": "string", "minLength": 1, "maxLength": 50 }, "recurring": { "description": "Search for transaction where recurring flag is present/not present", "type": "boolean" }, "tracking_id": { "description": "Search for exact tracking id", "type": "string", "minLength": 16, "maxLength": 32 }, "transaction_statuses": { "description": "Transaction status ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "transaction_types": { "description": "Transaction type ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "subscriptions": { "description": "Subscription tracking ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 32 } } }, "required": ["timestamp_from", "timestamp_to"], "additionalProperties": false } -
Ordering
Ordering of transaction search results is possible by the following fields:
- id
- amount
- bin_and_last4
- cvv2
- order_number
- first_name
- last_name
- message
- card_type
- transaction_type
- currency
- transaction_status
- subscription
-
Throttling
Maximum 10 requests every 20 seconds.
Cancel a subscription - /subscription_cancellation/{subscription_tracking_id}¶
Retrieve information about merchant groups. Each merchant belongs to a single merchant group.
-
Example
https://portal.icsaccess.com/api/v1/subscription_cancellation?subscription_tracking_id=29c87680f31f4cdb8d0bb5a70ff4d83e
-
Headers
Accept, Authorization
-
Get parameters
subscription_tracking_id
-
Throttling
Maximum 10 requests every 20 seconds.
Chargeback - /chargeback/{chargeback_id}¶
Retrieve information about chargebacks.
-
Example
https://portal.icsaccess.com/api/v1/chargeback?q=ewogICAgImFtb3VudF9mcm9tIjogMC4wMCwKICAgICJhbW91bnRfdG8iOiAxM...
-
Headers
Accept, Authorization
-
Get parameters
q
Chargeback API endpoint query string parameters should be passed as a base64 encoded JSON UTF-8 string named 'q'. When received the value is decoded back to json and validated against the json schema given below.
Example JSON query string before base64 encoding
{ "amount_from": 0.0, "amount_to": 10.0, "currencies": [149, 49, 150, 151], "chargeback_date_from": "2018-01-01", "chargeback_date_to": "2018-01-15", "transaction_timestamp_from": "2018-01-01 00:00:00", "transaction_timestamp_to": "2018-01-15 23:45:00", "merchants": [1, 2, 3], "order_number": "123456789" }Charegback request query string validation schema
The chargeback API endpoint base64 encoded json is defined with the following JSON schema and should validate against it.
Note that chargeback_date_from and chargeback_date_to are mandatory fields{ "$schema": "http://json-schema.org/draft-06/schema#", "title": "Chargeback query string", "description": "Chargeback query string definition. This defines the fields and format of the JSON that need to be sent (base 64 encoded) to the /chargeback portal API endpoint. ", "type": "object", "properties": { "amount_from": { "description": "Smallest transaction amount to appear in results", "type": "number", "minimum": 0 }, "amount_to": { "description": "Largest transaction amount to appear in results", "type": "number", "minimum": 0 }, "currencies": { "description": "Currency ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "chargeback_date_from": { "description": "Chargeback search start date. Format: YYYY-MM-DD", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "chargeback_date_to": { "description": "Chargeback search end date and time. Format: YYYY-MM-DD", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "transaction_timestamp_from": { "description": "Chargeback search start date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "transaction_timestamp_to": { "description": "Chargeback search end date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "merchants": { "description": "Merchant ids to include in search", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "order_number": { "description": "Search for exact order number", "type": "string", "minLength": 1, "maxLength": 50 } }, "required": ["chargeback_date_from", "chargeback_date_to"], "additionalProperties": false } -
Throttling
Maximum 10 requests every 20 seconds.
Fraud - /fraud/{fraud_id}¶
Retrieve information about frauds.
-
Example
https://portal.icsaccess.com/api/v1/fraud?q=ewogICAgImFtb3VudF9mcm9tIjogMC4wMCwKICAgICJhbW91bnRfdG8iOiAxM...
-
Headers
Accept, Authorization
-
Get parameters
q
Fraud API endpoint query string parameters should be passed as a base64 encoded JSON UTF-8 string named 'q'. When received the value is decoded back to json and validated against the json schema given below.
Example JSON query string before base64 encoding
{ "amount_from": 0.0, "amount_to": 10.0, "currencies": [149, 49, 150, 151], "fraud_date_from": "2018-01-01", "fraud_date_to": "2018-01-15", "transaction_timestamp_from": "2018-01-01 00:00:00", "transaction_timestamp_to": "2018-01-15 23:45:00", "merchants": [1, 2, 3], "order_number": "123456789" }Charegback request query string validation schema
The chargeback API endpoint base64 encoded json is defined with the following JSON schema and should validate against it.
Note that fraud_date_from and fraud_date_to are mandatory fields{ "$schema": "http://json-schema.org/draft-06/schema#", "title": "Chargeback query string", "description": "Fraud query string definition. This defines the fields and format of the JSON that need to be sent (base 64 encoded) to the /fraud portal API endpoint. ", "type": "object", "properties": { "amount_from": { "description": "Smallest transaction amount to appear in results", "type": "number", "minimum": 0 }, "amount_to": { "description": "Largest transaction amount to appear in results", "type": "number", "minimum": 0 }, "currencies": { "description": "Currency ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "fraud_types": { "description": "Fraud type ids to look for", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "fraud_date_from": { "description": "Chargeback search start date. Format: YYYY-MM-DD", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "fraud_date_to": { "description": "Chargeback search end date and time. Format: YYYY-MM-DD", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "transaction_timestamp_from": { "description": "Chargeback search start date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "transaction_timestamp_to": { "description": "Chargeback search end date and time. Timezone UTC. Format: YYYY-MM-DD HH:MM:SS", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$" }, "merchants": { "description": "Merchant ids to include in search", "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "number" } }, "order_number": { "description": "Search for exact order number", "type": "string", "minLength": 1, "maxLength": 50 } }, "required": ["fraud_date_from", "fraud_date_to"], "additionalProperties": false } -
Throttling
Maximum 10 requests every 20 seconds.
Credit request - /credit_request/¶
Submit a credit request for a previously approved transaction
-
Headers
Accept, Authorization
-
Get parameters
- tracking_id (required) - Tracking id of the original transaction that is being credited,
- merchant_id (required) - Id of the merchant from the original transaction,
- amount (required) - Amount to be credited.
-
Throttling
Maximum 10 requests every 20 seconds.