Signed Payload for Transfer Requests.

This feature adds additional layer of security to Requests made to our Transfer API. If enabled, all requests made must have a signature passed as a header.

Feature Affected: Transfer

Endpoint for Transfer

Endpoint: {{baseUrl}}/transaction/transfer

Authentication Technique: HMAC

Hash Algorithm: sha256

Header Param: x-request-id

How this works:

1. SignKey Generation: You can generate your signKey from the Startbutton dashboard, and it will be unique to your account.

2. Payload Signing: Once the feature is enabled, you’ll need to use your signKey to sign the payload of any API Transfer request you make.

3. Signature Header: The signature(hash) is passed as a header param.

4. Verification: Upon receiving the request, Startbutton verifies the signature to ensure that the payload is authentic and hasn’t been tampered with during transit.

NOTE: month, day, hour, and minute should allow leading zeros when they are less than 10

so if minute = 2, it should be 02

Here is a sample code on how to generate the x-request-id:

JavaScript

var crypto = require('crypto');
var signKey = process.env.SIGN_KEY;

var samplePayload = {
    "amount": 1000,
    "currency": "KES",
    "country": "Kenya",
    "MNO": "MTN",
    "msisdn": "0707xx75xx"
}
var year = "yyyy"; //2024
var month = "mm"; //10
var day = "dd"; //22
var hour = "hh"; //18
var minutes = "min"; //07

var requestTime = `${year}${month}${day}${hours}${minutes}`;
var signature = crypto.createHmac('sha256', signKey)
    .update(`${requestTime}${samplePayload}`)
    .digest('hex');

Python

PHP