Skip to content


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 Contract Profile Id 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 CONTRACTPROFILEID 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, 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

Key Value Description
CONTRACTPROFILEID {{ContractProfileId}} Contract Profile Id is generated from the ICEPAY portal.
CHECKSUM {{CalculatedChecksum}} Calculated checksum value

Concatenate the request url, http method, json payload and Contract Profile Id.

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

e.g :{“key”:”value”}

Url : Full path to the ICEPAY endpoint. All the endpoints are https Method : Upper case http method (POST, GET) ContractProfileId : Contract Profile id that is generated from your Contract Profile in the ICEPAY portal Payload : All post requests are using JSON format. Get requests will skip this value (empty)


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


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.

Concatenate the request url, http method, json payload and Contract Profile Id.

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

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

Sample Code


function generateHMAC($url, $method, $request, $userId, $secret) {
    $data = $url.$method.$userid.$request;
    $hash = hash_hmac("sha256", $data, base64_decode($secret), true);
    return base64_encode($hash)

//If using curl don't forget to set the headers
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "CHECKSUM: $hash",
    "USERID: $userid"


private string CalculateChecksum(string url, string method, string rawRequest, string contractProfileId, string hmacKey)
    StringBuilder checksumSource = new StringBuilder();
    using (var hmacsha256 = new HMACSHA256(Convert.FromBase64String(hmacKey)))
        var encoding = new UTF8Encoding();
        byte[] hash = hmacsha256.ComputeHash(encoding.GetBytes(checksumSource.ToString()));
        var checksum = System.Convert.ToBase64String(hash);
        return checksum;