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.

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.

POST https://test-interconnect.icepay.com/api/contract/authorisation
UserId
string
User identity value to specify in headers (also known as ContractProfileId)
Example value: 87407ae9-cbfa-4459-bb98-63860a090dad
Secret
string
Secret for the contract profile
Example value: Dk0d+pNVTgNtkuu9GSr6AbV8BIWJGaCgx0KEqfEN7ag=
Payload
object

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": "luke@starwars.com",
            "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
string
Concating all values in payload and headers.
Calculation: `${Url}${Method}${UserId}${Payload}`
Base64 HMAC
string
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();
    checksumSource.Append(url);
    checksumSource.Append(method);
    checksumSource.Append(userID);
    checksumSource.Append(rawRequest);
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; } }