Security

Checksum introduction

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.
To authenticate the message and verify the integrity of the message, a checksum is sent as an HTTP header. A custom checksum algorithm using HMACSHA256 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.

This checksum is sent on each request in an HTTP header. In addition to the checksum, the userid (als known as ContractProfileId) must be sent as an header.

For response messages the same calculation is used and the checksum based on the response message is returned as a header. It is always advisable to use the literal value from the USERID response header to calculate the checksum to prevent any issues with differences in casing, particularly when calculating the checksum of a Postback.

HMAC authentication is also used for postbacks and redirect requests. Merchant needs to verify these requests to make sure the message is securely transferred from ICEPAY.

Below you can see how to calculate checksum for requests and payment feedbacks.


Calculate the checksum

The implementation may vary between the language that the merchant backend supports. Please refer to this page for sample codes for hash functions.

The calculation of the checksum is a base64 encoded HMACSHA256-hash of a concatenated string of the URL, request method, userId (ContractProfileId) and JSON request, using the base64 decoded secret.

{{CalculatedChecksum}} = hash(“HMACSHA256”, stringToHash, secret.toBase64Decoded())

Please see below how to build this string for requests and payment feedbacks.


Transaction/Authorisation headers

All contract requests defined in the api reference expect the following authentication request headers.

Authentication Request Headers

KeyValueDescription
USERID{{UserId}}Also known as ContractProfileId
CHECKSUM{{CalculatedChecksum}}Calculated checksum value

Concatenate the request url, http method, json payload and user id.

stringToHash = ${Url}${HttpMethod}${UserId}${Payload}

e.g : https://interconnect.icepay.com/api/contract/authorisationPOST793bf9d0-6985-418d-a838-cfd1f6d20d3d{“key”:”value”}

Url : Full path to the ICEPAY endpoint. All the endpoints are https
Method : Upper case http method (POST, GET)
UserId : User id that is provided by ICEPAY account manager
Payload : All post requests are using JSON format. Get requests will skip this value (empty)


Redirect

Redirect request from ICEPAY to merchants contain query string parameters (which are listed in the api reference) together with the checksum. Merchants need to verify redirect requests by calculating the checksum in their backend and compare it with the one in the query string.

Concatenate the following parameters with a pipe(|) character.

stringToHash = ContractProfileId|StatusCode|StatusDetails|Reference|TransactionId|ProviderTransactionId|PaymentMethod|Issuer|AmountInCents|CurrencyCode

e.g : 3956a57f-607b-4bd8-98e6-1c10cc1d92f1|Completed|Finished|ref123|a956a57f-607b-4bd8-98e6-1c10cc1d92ff|providerid|IDEAL|ING|190|EUR


Postback

ICEPAY notifies merchants when there is a status change in transaction or authorisation. This is a POST request with a JSON payload. The request also contains the checksum value in the header. Merchant needs to verify this checksum in their back end services to verify this message is indeed sent by ICEPAY.

Calculating the checksum for the postback is the same as calculating the contract request checksums mentioned above.

Concatanate the request url, http method, json payload and user id.

stringToHash = ${Url}${HttpMethod}${UserId}${Payload}

Url is the NotificationUrl stated in contract request under Postback object. HttpMethod is always POST