HMAC Signing

HTTP requests flowing in both directions between Tola and the Merchant can optionally be signed by a Message Authentication Code (MAC) where an additional layer of security is required between the Merchant and Tola. See HMAC Signing for more details. The Merchant should request that HMAC be enabled and will be provided with a pre-shared key.

When the feature is enabled every request issued by Tola or the Merchant platform will include two additional headers:

API-Timestamp: <timestamp>
API-Signature: <computed-hmac>

If these headers are not included the request will be rejected.

timestamp

Should be the Unix Epoch Time.

Warning

Tola will reject requests where the timestamp is older than 300 seconds. The Merchant should not trust requests it receives from Tola where the timestamp is older than 300 seconds.

computed HMAC

Is calculated as follows:

HMAC-SHA256(<pre-shared key>, <timestamp> + ":" + <message body>)

Where message body is the full POST body for this request.

Flow

Signing works in both directions — the Merchant signs requests to Tola, and Tola signs callbacks to the Merchant.

Examples

Request to the Tola Wallet

POST /walletapi/samplerelay HTTP/1.1
Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxx
User-Agent: curl/7.29.0
Host: sample.tolamobile.com
Accept: */*
Content-Type: application/json
API-Timestamp: 1643280073
API-Signature: e592c8d92833560e045d52dd42cfc4f519d4271a37ddfe8dc2f513e99eb3be40
Content-Length: 205

{
  "channel": "TANZANIA.TIGO",
  "msisdn": "255000000002",
  "target": "000001",
  "amount": "1",
  "currency": "TZS",
  "type": "charge",
  "sourcereference": "1643278355"
}

Sample Code

The following Python 3 code will produce a compliant HMAC:

import hmac
import hashlib

pre_shared_key = "test"

payload = '''1643280073:{
  "channel": "TANZANIA.TIGO",
  "msisdn": "255000000002",
  "target": "000001",
  "amount": "1",
  "currency": "TZS",
  "type": "charge",
  "sourcereference": "1643278355"
}'''

print(hmac.new(pre_shared_key.encode(), payload.encode(), hashlib.sha256).hexdigest())

Onboarding Guide

Managed Disbursements