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

import hmac
import hashlib
import os
from datetime import datetime


def generate_hash(key, message):
    return hmac.new(key.encode('utf-8'), message.encode('utf-8'),
                    hashlib.sha256).hexdigest()


def main():
    current_datetime = datetime.now()
    year = 'yyyy'  # 2024
    month = 'mm'  # 10
    day = 'dd'  # 23
    hour = 'hh'  # 11
    minute = 'min'  # 05

    requestTime = str(year) + str(month).zfill(2) + str(hour).zfill(2) \
        + str(minute).zfill(2)

    sample_payload = {
        'amount': 1000,
        'currency': 'KES',
        'country': 'Kenya',
        'MNO': 'MTN',
        'msisdn': '0707xx75xx',
        }
    secret_key = os.environ('SIGN_KEY')
    final_payload = str(requestTime) + str(sample_payload)
    content = final_payload
    signature = generate_hash(secret_key, content)

PHP

$date = new DateTime();
$year = "yyyy"; //2024;
$month = "mm"; //10
$day = "dd"; //22
$hour = "hh"; //18
$minutes = "min"; //07

$signKey = getenv("SIGN_KEY");
$requestTime = $year . $month . $day . $hour . $minutes;

$sample_payload = (object) array(
"amount" => 1000,
"currency" => "KES",
"country" => "Kenya",
"MNO" => "MTN",
"msisdn" => "0707xx75xx"
);

$encoded_payload = json_encode($sample_payload);
$final_payload = $requestTime . $encoded_payload;
$signature = hash_hmac('sha256', $final_payload, $signKey)