REST API

The base URL for the API is: https://connect.icepay.com/webservice/api/v1/

The service and operation name follow on after the base URL. 

A full API URL would have the following format:

https://connect.icepay.com/webservice/api/v1//payment/checkout

REST and JSON

REST (REpresentational State Transfer) is a web service architectural style. In general it means that aspects of the HTTP protocol are used to retrieve or manipulate data from a remote system. As in HTTP, a RESTful API is called with the combination of a URL and a verb. The verb POST is used by all operations on the ICEPAY REST API.

JSON (JavaScript Object Notation) is a notation style to represent complex object structures in a serialized manner (i.e. transferable over the internet). It has the same role as XML, but is much less verbose and therefore faster.

Apiary

THE REST API is fully documented on Apiary. The Apiary site allows you to get sample code for webservice calls for many programming languages and platforms: RAW, cURL, Java, JavaScript, Node.js, Perl, Python, PHP, Ruby, Go, C#, Visual Basic, Groovy, Objective-C and Swift. 

You can also send requests directly from the Apiary site and inspect the response!

Security

The ICEPAY REST API uses two layers of security to ensure two-way authentication of sender and receiver, and to prevent interception of messages and tampering.

SSL is used for transport security. All calls to the REST API must be done over HTTPS, ensuring end-to-end encryption of the message and authentication of ICEPAY as the recipient of your requests. A custom checksum algorithm using SHA256 is used to sign requests and responses. Using a pre-shared secret code, this algorithm authenticates the sender of requests and ensures that any response you receive really came from ICEPAY.

To authenticate the message, two values are sent as HTTP headers.

The header MerchantID identifies the beneficiary of the payment.

The header Checksum verifies that the merchant mentioned in the header MerchantID is also the sender of the message.

Header nameDescription
ChecksumYour calculated checksum which verifies you as the sender of the message.
MerchantIDYour 5-digit MerchantID (not to be confused with the CompanyID)

How to calculate the Checksum

The checksum calculation for the REST API uses the full JSON body which ensures all fields in the request are safe from tampering. With the exception of postbacks and the reporting service the following steps apply to all communication with the REST API:

  1. Concatenate the full URL of the request, the HTTP verb used (POST or GET), your Merchant ID, the shared secret code and the raw JSON request.
    1. Example: https://connect.icepay.com/webservice/api/v1/payment/checkout/POST12345AbCdEfGhIjKlMnOpQrStUvWxYz1234567890AbCd{"Timestamp" : "2015-01-01T00:00:00", ...}
  2. Ensure the base string is UTF-8 encoded
  3. Calculate a SHA256 hash over the string and format the output as hexadecimal. Note: use a regular SHA256 hash, not an HMAC.
    1. Example:4c8b79bf77d6162df3305b32c698de20c8b79b38ac23b515826134dc311624e29364eb

With these steps you should have a 64-character, hex encoded string to be used as the checksum.