Overview of Header Types

Types	Description
Authorization	The `Authorization` header is used to send authentication credentials, typically in the form of a `Bearer` token. This is used to authenticate the requester by including a token that identifies the user or application (e.g., `Authorization: Bearer "token"`).
x-hmac-signature	The `x-hmac-signature` is a custom header used to send an HMAC (Hash-based Message Authentication Code) signature. It ensures the integrity and authenticity of the request by verifying that it has not been altered.
x-hmac-timestampb	The `x-hmac-timestampb` header includes a timestamp to prevent replay attacks. It ensures that the request is fresh and valid within a specific time window.
x-api-secret	The `x-api-secret` is a custom header containing a secret key used for authentication, often paired with the HMAC signature to verify the authenticity of the request.

📘
Expiration of API Key and Token
The secret key generated and placed in the x-api-secret header has an expiration time of 5 minutes, just like the authentication token placed in the Authorization header. After this period, a new key or token will need to be generated.

How to Generate and Locate Header Content

Authorization

To create the token required in this header, you will need to use the loginendpoint provided in the documentation. You will be asked to provide a username and password. If the credentials are correct, the response will include several data fields, one of which will be the token. This token is mandatory and must be included in the Authorization: Bearer header.

Login - endpoint

x-hmac-signature and x-hmac-timestampb

To create the HMAC headers (x-hmac-signature and x-hmac-timestamp), you need to obtain the secret, which can be retrieved from the secret endpoint. This secret will serve as the key for generating the HMAC signature. Once you have the secret, you will need to capture the body of the request and the current timestamp. The HMAC signature is generated by hashing the request body together with the timestamp and the secret. This signature, along with the timestamp, will then be added to the request headers.

Secret - endpoint

Exemples

const { randomUUID } = require("crypto");
const crypto = require("crypto");
require("dotenv").config();

function generateHMAC(secret, body, timestamp) {
  const message = `${timestamp}:${JSON.stringify(body)}`;
  return crypto.createHmac("sha256", secret).update(message).digest("hex");
}

const secret = process.env.HMACK_KEY; 
const body = {
  "transaction_amount": 10000,
  "notification_urls": ["https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"],
  "external_reference": randomUUID(),
  "dueDate": "1600"
};
const timestamp = Math.floor(Date.now() / 1000); 
const hmac = generateHMAC(secret, body, timestamp);

console.log("Generated HMAC:", hmac);
console.log("Body:", body);
console.log("Timestamp:", timestamp);

import * as crypto from 'crypto';
import * as dotenv from 'dotenv';
import { v4 as uuidv4 } from 'uuid';

dotenv.config();

function generateHMAC(secret: string, body: any, timestamp: number): string {
  const message = `${timestamp}:${JSON.stringify(body)}`;
  return crypto.createHmac('sha256', secret).update(message).digest('hex');
}

const secret: string = process.env.HMACK_KEY || '';
const body = {
  transaction_amount: 10000,
  notification_urls: ["https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"],
  external_reference: uuidv4(),
  dueDate: "1600"
};
const timestamp: number = Math.floor(Date.now() / 1000);
const hmac: string = generateHMAC(secret, body, timestamp);

console.log("Generated HMAC:", hmac);
console.log("Body:", body);
console.log("Timestamp:", timestamp);

import hashlib
import hmac
import json
import os
import uuid
import time
from dotenv import load_dotenv

load_dotenv()

def generate_hmac(secret, body, timestamp):
    message = f"{timestamp}:{json.dumps(body)}"
    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()

secret = os.getenv("HMACK_KEY")
body = {
    "transaction_amount": 10000,
    "notification_urls": ["https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"],
    "external_reference": str(uuid.uuid4()),
    "dueDate": "1600"
}
timestamp = int(time.time())
hmac_result = generate_hmac(secret, body, timestamp)

print("Generated HMAC:", hmac_result)
print("Body:", body)
print("Timestamp:", timestamp)

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/json"
	"fmt"
	"os"
	"strconv"
	"time"
	"github.com/google/uuid"
)

func generateHMAC(secret string, body map[string]interface{}, timestamp int64) string {
	message := fmt.Sprintf("%d:%s", timestamp, body)
	h := hmac.New(sha256.New, []byte(secret))
	h.Write([]byte(message))
	return fmt.Sprintf("%x", h.Sum(nil))
}

func main() {
	secret := os.Getenv("HMACK_KEY")
	body := map[string]interface{}{
		"transaction_amount": 10000,
		"notification_urls":  []string{"https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"},
		"external_reference": uuid.New().String(),
		"dueDate":            "1600",
	}
	timestamp := time.Now().Unix()
	hmacResult := generateHMAC(secret, body, timestamp)

	fmt.Println("Generated HMAC:", hmacResult)
	fmt.Println("Body:", body)
	fmt.Println("Timestamp:", timestamp)
}

require 'openssl'
require 'json'
require 'securerandom'
require 'dotenv'

Dotenv.load

def generate_hmac(secret, body, timestamp)
  message = "#{timestamp}:#{JSON.generate(body)}"
  OpenSSL::HMAC.hexdigest('sha256', secret, message)
end

secret = ENV['HMACK_KEY']
body = {
  "transaction_amount" => 10000,
  "notification_urls" => ["https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"],
  "external_reference" => SecureRandom.uuid,
  "dueDate" => "1600"
}
timestamp = Time.now.to_i
hmac_result = generate_hmac(secret, body, timestamp)

puts "Generated HMAC: #{hmac_result}"
puts "Body: #{body}"
puts "Timestamp: #{timestamp}"

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import java.util.UUID;
import org.json.JSONObject;

public class HMACExample {
    public static void main(String[] args) throws Exception {
        String secret = System.getenv("HMACK_KEY");
        JSONObject body = new JSONObject();
        body.put("transaction_amount", 10000);
        body.put("notification_urls", new String[]{"https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"});
        body.put("external_reference", UUID.randomUUID().toString());
        body.put("dueDate", "1600");

        long timestamp = System.currentTimeMillis() / 1000;
        String hmacResult = generateHMAC(secret, body, timestamp);

        System.out.println("Generated HMAC: " + hmacResult);
        System.out.println("Body: " + body.toString());
        System.out.println("Timestamp: " + timestamp);
    }

    public static String generateHMAC(String secret, JSONObject body, long timestamp) throws Exception {
        String message = timestamp + ":" + body.toString();
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        mac.init(secretKeySpec);
        byte[] hmacBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
        return bytesToHex(hmacBytes);
    }

    public static String bytesToHex(byte[] bytes) {
        StringBuilder hexString = new StringBuilder();
        for (byte b : bytes) {
            hexString.append(String.format("%02x", b));
        }
        return hexString.toString();
    }
}

<?php
require 'vendor/autoload.php';
use Dotenv\Dotenv;

Dotenv::load();

function generateHMAC($secret, $body, $timestamp) {
    $message = $timestamp . ":" . json_encode($body);
    return hash_hmac('sha256', $message, $secret);
}

$secret = getenv('HMACK_KEY');
$body = [
    "transaction_amount" => 10000,
    "notification_urls" => ["https://webhook.site/1b9680c8-dc19-46cc-be33-cef714c534b7"],
    "external_reference" => uniqid(),
    "dueDate" => "1600"
];
$timestamp = time();
$hmacResult = generateHMAC($secret, $body, $timestamp);

echo "Generated HMAC: " . $hmacResult . "\n";
echo "Body: " . json_encode($body) . "\n";
echo "Timestamp: " . $timestamp . "\n";
?>

Here is a detailed of what the script does:

Obtain the Secret Key: The secret key (HMACK_KEY) must be obtained from the secret route, which will be used to generate the HMAC signature.
Generate the HMAC Signature: The HMAC is generated by combining the request body and timestamp with the secret key. The result is a unique signature that guarantees the integrity and authenticity of the data.

x-api-secret

To obtain the secret, the process is simple. First, use the login route mentioned earlier to get the token by providing your credentials. Then, include this token in the Authorization header as a Bearer token. Next, make a request to the secret route with the Authorization header. The response will return a secret parameter, which contains the content for the x-api-secret header. Please note that this secret has an expiration time, as mentioned previously.

Login - endpoint

Secret - endpoint