Checksum

ICEPAY uses HMAC authentication to make sure the messages between merchant and ICEPAY are not tampered. Merchant encrypts the requests with their secret and attaches a checksum field in request headers. When the request is received by ICEPAY the checksum is validated. If validation fails then the service returns 401 with a specific message.

ICEPAY responses could also be verified by the checksum value in response header with same way as the request messages signed.

HMAC authentication is also used for postback and redirect requests that are sent from ICEPAY to merchant. Merchant needs to verify these requests to make sure the message is securely transferred from ICEPAY.

HMACSHA256 algorithm is used for HMAC checksum calculation.

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

To calculate the checksum, a string is built and hashed with a secret.

This built string then hashed by user secret to produce checksum. User secret is passed as base64 decoded.

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

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

Transaction/Authorisation

All contract requests defined in api reference expects authentication request headers.

Authentication Request Headers

Concatanate 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 merchant contains query string parameters listed in api reference together with checksum. Merchant needs to verify redirect requests by calculating the checksum in their backend and compare with the one in query string.

Concatanate the 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 merchant when there is a status change in transaction or authorisation. This is a POST request with a JSON payload. The request also contains checksum value in header. Merchant needs to verify this checksum in back end services to verify this message is securely sent from ICEPAY.

Calculating checksum for 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.