Security and Checksums

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 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.

To authenticate the message and verify the integrity of the message, a checksum is sent as an HTTP header.

In addition to the checksum, the userid (als known as ContractProfileId) must be send as an HTTP header.

For response messages the same calculation is used. 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.

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

User identity value to specify in headers (also known as ContractProfileId)
Example value: 87407ae9-cbfa-4459-bb98-63860a090dad
Secret for the contract profile
Example value: Dk0d+pNVTgNtkuu9GSr6AbV8BIWJGaCgx0KEqfEN7ag=

Example value:

    "Contract": {
        "ContractProfileId": "87407ae9-cbfa-4459-bb98-63860a090dad",
        "AmountInCents": 1000,
        "CurrencyCode": "EUR",
        "Reference": "12345"
    "Fulfilment": {
        "PaymentMethod": "AFTERPAY",
        "IssuerCode": "AFTERPAY",
        "AmountInCents": 1000,
        "CurrencyCode": "EUR",
        "Reference": null,
        "Consumer": {
            "Reference": null,
            "Address": {
                "CountryCode": "NL",
                "Street": "Dorpstraat",
                "HouseNumber": "1",
                "HouseNumberExtension": null,
                "PostalCode": "1111AA",
                "City": "Amsterdam"
            "Category": "Person",
            "FirstName": "Luke",
            "LastName": "Skywalker",
            "Email": "",
            "Phone": "+31620342122",
            "BirthDate": "1996-04-23T00:00:00Z",
            "Gender": "Male",
            "LanguageCode": "NL",
            "IPAddress": null
        "Order": {
            "OrderNumber": "12345",
            "CurrencyCode": "EUR",
            "TotalGrossAmountCents": 1000,
            "TotalNetAmountCents": 1000,
            "DiscountAmountCents": 0,
            "OrderItems": [{
                "ProductId": "12345-0",
                "ProductName": "Some product",
                "Quantity": 1,
                "GrossUnitPriceCents": 1000,
                "NetUnitPriceCents": 1000,
                "VatCategory": null
        "Timestamp": "2018-04-23T14:22:05.49949Z",
        "LanguageCode": "NL"
Concatenated string
Concating all values in payload and headers.
Calculation: `${Url}${Method}${UserId}${Payload}`
Base64 HMAC
Calculated HMAC value with below functions.
Possible Value: gizdzIhmrrB2Z+/kHtEonmqLp/Tdhz23c7Ldl6Qve54=

Sample Code - PHP

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"

Sample Code - C#

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;