Loader

Signature Checksum Calculation

Note: The Signature Checksum Calculation is not enabled by default and should be requested if required.

 

The .Core REST API uses two layers of security to ensure two-way authentication of sender and receiver and to prevent interception of messages and tampering:

  1. SSL is used for transport security. All calls to the .Core REST API must be done over HTTPS, ensuring end-to-end encryption of messages and authentication of Clickatell as the recipient of the requests.
  2. To authenticate the message and verify the integrity of the message, a checksum can be sent as an HTTP header in all requests. Using the pre-shared secret code, the algorithm provides data integrity to ensure that the messages are not tampered with while in transit and authenticates the sender of the requests. This is described in more detail below.

Inclusions:

Exclusions:

  • Currently there is no implementation for responses.
  • Only implemented on the Transact, Reserve and Transact, Fund Reservation and Transact Result APIs, not available on the other public APIs.
  • Do not include Microsoft new line characters in the request payload. These are represented as two characters and will result in a different checksum being calculated on the back-end.

Checksum calculation

To verify the integrity of the message, a checksum is sent as an HTTP header as “Signature”. The calculation of the checksum is a base64 encoded HMACSHA256 hash of the payload.

Note: the implementation may vary depending on the language that the client’s back-end system supports.

Calculation

  • Payload must be in UTF-8 encoding
  • Shared secret value must be in UTF-8 encoding
  • Algorithm used is HmacSHA256
  • The calculated signature must be base64encoded and then UTF-8 encoded

Clients must request the key/signature from Clickatell. Clients can also generate their own key and share it with Clickatell.

Example

Payload

{

“accountIdentifier”:”3745******0762″,

“purchaseAmount”:10000,

“authCode”:”1234″,

“channelId”:”2″,

“channelName”:”InternetBanking”,

“channelSessionId”:”144974973281″,

“clientId”:”200″,

“clientTxnRef”:”seo8w3-3wsf8c-ffdd34-f58l”,

“productId”:100,

“reserveFundsTxnRef”:”aab1b2-3ccd4d-eeff56-a789″,

“sourceIdentifier”:”2348012345678″,

“targetIdentifier”:”2348012345555″,

“timestamp”:”2017-06-2916:39:42.735Z”,

“feeAmount”:0

}

Base64 HMAC-SHA2-256

Calculated HMAC value with HMAC-SHA2-256 functions.

Possible Value:

gizdzIhmrrB2Z+/kHtEonmqLp/Tdhz23c7Ldl6Qve54=

 

Sample HMAC-SHA2-256 Procedure


public class SignatureUtils {
    private static final String CHARACTER_ENCODING = "UTF-8";
    private final static String ALGORITHM = "HmacSHA256";
    public static String sign(String data, String secretKey)
         throws NoSuchAlgorithmException, InvalidKeyException, IllegalStateException, UnsupportedEncodingException {
      Mac mac = Mac.getInstance(ALGORITHM);
      mac.init(new SecretKeySpec(secretKey.getBytes(CHARACTER_ENCODING), ALGORITHM));
      byte[] signature = mac.doFinal(data.getBytes(CHARACTER_ENCODING));
      String signatureBase64 = new String(Base64.encodeBase64(signature), CHARACTER_ENCODING);
      return signatureBase64;
   }
}

Did you find this information informative?

Other Resources

Ask the Community

Visit Stack Overflow to join our community of developers and find the answer you need

Contact Support

Contact our support team and one of our agents will be in touch with you to answer any questions you have