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:
- 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.
- 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:
- Available on all versions of the Transact, Reserve and Transact, Fund Reservation and Transact Result APIs
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; } }
Channels
Find the most up-to-date information about the channels available to communicate with your clients.
SMS
Enable any application, website or system to facilitate local or international one- or two-way SMS communication via an easy one-step integration with our HTTP API.
Documentation
One API
Communicate with your mobile customers via multiple communication channels with a single integration. You can send and receive messages on both WhatsApp and SMS without the overhead of programming individual channels.
Documentation
As an authorized WhatsApp Business Solution Provider, we assist you in applying for a WhatsApp Business account and number. Integrate with other powerful features available on our platform via our One API.
Documentation
Products
Find the most up-to-date information about the products we offer and how to elevate your engagement with customers.
Chat 2 Pay
Send payment requests to customers via chat for secure, contactless payment experiences.
Documentation
Chat Desk
An easy-to-use web-based application that enables real-time communication with your customers via a single web interface.
Documentation
Chat Flow
A web-based application that allows you to quickly and collaboratively design and deploy conversational experiences across multiple chat applications and connect it to your organization's core functional APIs.
Documentation
Campaign Manager
An online tool that allows you to create a custom SMS campaign within minutes - no coding or developers required.
Documentation
Marketplace
Find the most up-to-date information about Clickatell's Marketplace and how you can utilize it for the distribution and payment acceptance of digital products.
Bank Interfaces API
An explanation of the way Clickatell and banks interact with one another when dealing with purchases.
Documentation
Transact Result API
Initiates the delivery of the transaction result for a purchase that was made through Clickatell after Clickatell facilitated the dispensing of the product.
Documentation
Reserve and Transact API
Initiates a purchase and fund reservation request to Clickatell.
Documentation
Security Service API
Request authentication tokens to use in all other Clickatell API calls.
Documentation
Transact
A cloud-based platform that allows for the distribution and payment acceptance of multiple digital products.
Documentation
In-Flight Transaction Check API
Used prior to a purchase instruction to confirm that no similar transaction is in progress.
Documentation
User Transaction Lookup API
Identify if a new transaction is similar to one of the user's recent transactions so the response details can be used to pre-emptively complete the current transaction details.
Documentation
Customer Account Validation API
Validate a customer's bill payment account number prior to submitting the bill payment purchase request to the vendor.
Documentation
MNO Lookup API
Derive the specific mobile network operator (MNO) for the specified MSISDN.
Documentation
Token Lookup API
Look up tokens/vouchers to present back to the buyer/customer who purchased token-related products via Clickatell's platform.
Documentation
Notifications API
Send notifications to buyer/recipient using different channels.
Documentation
Transaction Lookup API
Used after a purchase to confirm the transaction status.
Documentation
Financial Terms Lookup API
Display the correct fee and settlement amounts as per the contractual agreement for the SKU being purchased.
Documentation
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