Calculating the Signature

Learn how to calculate and send the Signature header value to verify requests integrity

Calculating the Signature

All the calls to our Deposits APIs will contain an Authorization field on the header used to ensure request integrity and to authenticate yourself since you will use your own secret key (API Signature) to generate and encrypt a hash.

It has to be created using HMAC-SHA-256 (RFC 2104) encoding and the payload must include the following details:

X-Date + X-Login + JSONPayload

Use your API Signature to generate the Authorization value

The Authorization field on the header of the requests will contain the string "D24 " plus the hash generated, in the following format:

Authorization: "D24 " + HMAC256(X-Date + X-Login + JSONPayload)

Example:

Authorization: D24 223a9dd4784726f1536c926da7dc69155a57612c5c3c1e1b429c367a5eee67cf

Notes

The X-Login is your login API Key, it can be retrieved from the Merchant Panel by going to Settings -> API Access -> Deposit credentials -> API Key.

The X-Date is the date in ISO8601 Datetime with Timezone. Format expected: ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ. E.g.: 2020-06-21T12:33:20Z.

The Authorization value is case sensitive and must include all the above mentioned values.

The JSONPayload is the exact same JSON you sent in the body of the request.

In case the JSONPayload value is empty (for example in the status or payment methods endpoints), use an empty string ("") instead.

The JSONPayload should be converted to UTF-8 before hashing it to prevent Invalid Signature error when sending characters with different encodings.

Examples

Check the examples in the different languages on how to properly calculate the Signature.

You can also check the code of our SDKs in Java and PHP to see how it is calculated.

Java

import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public static final String D24_AUTHORIZATION_SCHEME = "D24 ";

private static final String HMAC_SHA256 = "HmacSHA256";

public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String JSONPayload)
      throws NoSuchAlgorithmException, InvalidKeyException, IOException {
   byte[] hmacSha256 = null;
   Mac mac = Mac.getInstance(HMAC_SHA256);
   SecretKeySpec secretKeySpec = new SecretKeySpec(apiSignature.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
   mac.init(secretKeySpec);
   hmacSha256 = mac.doFinal(buildByteArray(xDate, apiKey, JSONPayload));
   return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256);
}

private static byte[] buildByteArray(String xDate, String apiKey, String JSONPayload) throws IOException {
   ByteArrayOutputStream bos = new ByteArrayOutputStream();
   bos.write(xDate.getBytes(StandardCharsets.UTF_8));
   bos.write(apiKey.getBytes(StandardCharsets.UTF_8));
   if (JSONPayload != null) {
      bos.write(payload.getBytes(StandardCharsets.UTF_8));
   }
   return bos.toByteArray();
}

private static String toHexString(byte[] bytes) {
   Formatter formatter = new Formatter();
   for (byte b : bytes) {
      formatter.format("%02x", b);
   }
   return formatter.toString();
}

C#

using System;
using System.Text;
using System.IO;
using System.Security.Cryptography;

namespace Application 
{

    class Directa24Example 
    {
    
        public readonly static string D24_AUTHORIZATION_SCHEME = "D24 ";
        
        private readonly static string HMAC_SHA256 = "HmacSHA256";
        
        public static String buildDepositKeySignature(String apiSignature, String xDate, String depositKey, String jsonPayload)
        {
            byte[] hmacSha256 = null;
            var apiSignatureEncod = Encoding.UTF8.GetBytes(apiSignature);
            var hash = new HMACSHA256(apiSignatureEncod);
            hmacSha256 = hash.ComputeHash(buildByteArray(xDate, depositKey, jsonPayload));  
            return D24_AUTHORIZATION_SCHEME + toHexString(hmacSha256).ToLower();
        }
        
        private static byte[] buildByteArray(String xDate, String apiKey, String jsonPayload)
        {
            try
            {
                MemoryStream stream = new MemoryStream();
                var xDateEncod = Encoding.UTF8.GetBytes(xDate);
                var apiKeyEncod = Encoding.UTF8.GetBytes(apiKey);
                stream.Write(xDateEncod, 0, xDateEncod.Length);
                stream.Write(apiKeyEncod, 0, apiKeyEncod.Length);
                if (!string.IsNullOrWhiteSpace(jsonPayload))
                {
                    var jsonPayloadEncod = Encoding.UTF8.GetBytes(jsonPayload);
                    stream.Write(jsonPayloadEncod, 0, jsonPayloadEncod.Length);
                }
                return stream.ToArray();
            }
            catch (Exception ex)
            {
                throw ex;
            }
        }
        
        private static string toHexString(byte[] bytes)
        {
            return BitConverter.ToString(bytes).Replace("-", string.Empty);
        }
    }
}

PHP

<?php

class Directa24Example {
 
	const D24_AUTHORIZATION_SCHEME = "D24 ";
	const HMAC_SHA256 = 'sha256';
	
	
	public static function build_deposit_key_signature($api_signature, $x_date, $deposits_api_key, $json_payload) {
		
		// Concatenate the content of the header X-Date, your deposits API Key (X-Login) and 
		// the whole JSON payload of the body of the request
		$string = $x_date . $deposits_api_key . $json_payload;
		
		// Generate the HASH by using yur own deposits API Signature and 
		// concatenate "D24 " in front of the hash
		return  self::D24_AUTHORIZATION_SCHEME . hash_hmac(self::HMAC_SHA256, $string, $api_signature);
	
	}

}