How to Create the Signature

Overview

Niobi supports two methods for generating request signatures:

In Code (Custom Implementation): Run our deterministic SHA-256 signing algorithm directly on your backend server. Recommended for production.
Via the Niobi Signature Generation API (POST /api/niobi-signature): Call Niobi’s helper endpoint to automatically compute and return the signed payload.

Important: params contains whatever the destination endpoint requires
In both methods, the inner "params": { ... } object is dynamic. It is not limited to a fixed set of fields; it must contain whatever specific parameters are required by the target API endpoint you are invoking (e.g., Collections parameters for collections or Payout parameters for disbursements).

Method 1: The Request Signing Algorithm (In Code)

For production environments where you want to minimize network latency and generate signatures entirely within your backend infrastructure, implement the following 10-step algorithm:

Obtain Credentials: Log into your Niobi Dashboard, navigate to Workspace -> Integrations, and create an integration entity. Note your client_id, sender (integration title), and senderKey (Secret Key).

Assemble the Pre-Signing Object: Create a JSON object containing your target endpoint parameters inside a nested params object, along with your metadata fields:

Field	Requirement	Description
`client_id`	Required	Your integration Client ID from the dashboard.
`sender`	Required	Your exact integration title from the dashboard.
`senderKey`	Required for signing only	Your private Secret Key (must be deleted before HTTP transmission).
`timestamp`	Required	The UNIX timestamp (in seconds) at the time the request is signed.
`salt`	Required	Random entropy string generated on your server.
`params`	Required	Object holding the target endpoint’s parameter payload.

{
  "sender": "Integration_title",
  "timestamp": 1724835600,
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "senderKey": "your_secret_key_here",
  "params": {
    "amount": 10000,
    "currency": "KES",
    "country_id": 1,
    "mobile": "254161166649",
    "payment_method_type": "send money",
    "callback_url": "https://yourdomain.com/niobi/callback",
    "third_party_reference_1": "REF-001",
    "third_party_reference_2": "REF-002"
  }
}

Add a Salt (salt): Provide your own random string (for example, 16 to 32 alphanumeric characters). This is not provided by Niobi; it is an additional security and entropy layer you control on your server to guarantee that every payment request produces a unique signature.
Include Client ID & Secret Key: Set "client_id" with your integration’s Client ID. Temporarily add your private Secret Key as "senderKey".
Add Integration Title (sender): Pass the exact integration name registered in your dashboard as "sender".
Sort Alphabetically (Recursive K-Sort): Sort all keys alphabetically in ascending order, applying the sort recursively for nested objects (such as params).
Stringify Key-Value Pairs: Convert the sorted structure into a single string formatted as key=value, concatenated with &. Nested properties are represented using dot notation (e.g. params.amount=10000).
Important URL Formatting: The callback_url (or client_callback_url) must not be URL-encoded in the stringified hash representation. For example: ...&params.callback_url=https://yourdomain.com/niobi/callback&...
Hash the String with SHA-256: Apply the SHA-256 hashing algorithm to the concatenated string. This produces a 64-character hexadecimal hash string.
Attach the Signature: Insert the resulting hash into the root JSON object as the "signature" field.
Remove the Secret Key (senderKey): Delete the "senderKey" field from the payload completely before dispatching the request over the network.

Watch Out for Whitespace & Trailing Spaces:
Ensure that your credentials (client_id, senderKey, sender) and string parameter values do not contain inadvertent leading or trailing whitespace, newlines, or extra spaces. A single accidental trailing space when copying a key will alter the computed hash and cause your request to fail with a 403 Request was not verified error. We recommend trimming all string values before hashing.

Detailed Payload Walkthrough

1. Before Signing (Pre-Signature Payload)

{
  "sender": "Integration_title",
  "timestamp": 1724835600,
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "senderKey": "your_secret_key_here",
  "params": {
    "amount": 10,
    "city": "Nairobi",
    "client_callback_url": "https://your-domain.com/niobi/result",
    "country": "KEN",
    "currency": "KES"
  }
}

2. Flattened, Sorted and Stringified Format

client_id=your_client_key_here&params.amount=10&params.city=Nairobi&params.client_callback_url=https://your-domain.com/niobi/result&params.country=KEN&params.currency=KES&salt=random_salt_value&sender=Integration_title&senderKey=your_secret_key_here&timestamp=1724835600

3. Final Signed Request Payload (Ready to Send to the Matching API Endpoint)

{
  "sender": "Integration_title",
  "timestamp": 1724835600,
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "params": {
    "amount": 10,
    "city": "Nairobi",
    "client_callback_url": "https://your-domain.com/niobi/result",
    "country": "KEN",
    "currency": "KES"
  },
  "signature": "219d12d1b0b9c8e66e84ee08cefafe05eaad68745a9e82cbcbc153131333c640"
}

Implementation Code Examples

const crypto = require('crypto');

function recursiveSort(value) {
  if (Array.isArray(value)) {
    return value.map(recursiveSort);
  }
  if (value !== null && typeof value === 'object') {
    const sorted = {};
    for (const key of Object.keys(value).sort()) {
      sorted[key] = recursiveSort(value[key]);
    }
    return sorted;
  }
  return value;
}

function stringifyValue(value) {
  if (typeof value === 'boolean') return value ? '1' : '';
  if (value === null || value === undefined) return '';
  if (typeof value === 'string') return value.trim();
  return String(value);
}

function convertToQueryString(value, parentKey = null) {
  let entries;
  if (Array.isArray(value)) {
    entries = value.map((v, i) => [i, v]);
  } else if (value !== null && typeof value === 'object') {
    entries = Object.entries(value);
  } else {
    return stringifyValue(value);
  }

  const parts = entries.map(([key, subValue]) => {
    const currentKey = parentKey !== null ? `${parentKey}.${key}` : String(key);
    if (subValue !== null && typeof subValue === 'object') {
      return convertToQueryString(subValue, currentKey);
    }
    return `${currentKey}=${stringifyValue(subValue)}`;
  });

  return parts.join('&');
}

function signRequest(payload, secretKey) {
  // 1. Create a clone and inject senderKey temporarily
  const prePayload = {
    ...payload,
    senderKey: secretKey.trim()
  };

  // 2. Sort keys recursively, then flatten into the key=value string
  const sortedPayload = recursiveSort(prePayload);
  const queryString = convertToQueryString(sortedPayload);

  // 3. Compute SHA-256 hash
  const signature = crypto
    .createHash('sha256')
    .update(queryString)
    .digest('hex');

  // 4. Return final payload without senderKey
  const finalPayload = { ...payload, signature };
  return finalPayload;
}

// Example Usage: params contains whatever is needed for your target endpoint.
// Method arrays (e.g. sendmoney) are flattened by index, not JSON-stringified:
// this becomes params.sendmoney.0.phone_number=254647647649.
const requestPayload = {
  client_id: "YOUR_CLIENT_ID",
  sender: "MyIntegration",
  salt: "random_salt_12345",
  timestamp: Math.floor(Date.now() / 1000),
  params: {
    amount: 10000,
    currency: "KES",
    country_id: 1,
    payment_method_type: "send money",
    callback_url: "https://example.com/callback",
    third_party_reference_1: "REF-001",
    third_party_reference_2: "REF-002",
    sendmoney: [
      { phone_number: "254647647649" }
    ]
  }
};

const signedPayload = signRequest(requestPayload, "YOUR_SECRET_KEY");
console.log(JSON.stringify(signedPayload, null, 2));

import hashlib
import json
import time


def recursive_ksort(value):
    if isinstance(value, dict):
        return {k: recursive_ksort(value[k]) for k in sorted(value.keys())}
    if isinstance(value, list):
        return [recursive_ksort(v) for v in value]
    return value


def stringify_value(value) -> str:
    if isinstance(value, bool):
        return '1' if value else ''
    if value is None:
        return ''
    if isinstance(value, str):
        return value.strip()
    return str(value)


def convert_to_query_string(value, parent_key=None) -> str:
    if isinstance(value, dict):
        items = list(value.items())
    elif isinstance(value, list):
        items = list(enumerate(value))
    else:
        return stringify_value(value)

    parts = []
    for key, sub_value in items:
        current_key = f"{parent_key}.{key}" if parent_key is not None else str(key)
        if isinstance(sub_value, (dict, list)):
            parts.append(convert_to_query_string(sub_value, current_key))
        else:
            parts.append(f"{current_key}={stringify_value(sub_value)}")
    return "&".join(parts)


def sign_request(payload: dict, secret_key: str) -> dict:
    pre_payload = dict(payload)
    pre_payload["senderKey"] = secret_key.strip()

    # Sort keys recursively, then flatten into the key=value string
    sorted_payload = recursive_ksort(pre_payload)
    query_string = convert_to_query_string(sorted_payload)

    # Compute SHA-256 hash
    signature = hashlib.sha256(query_string.encode('utf-8')).hexdigest()

    # Build final payload without senderKey
    final_payload = dict(payload)
    final_payload["signature"] = signature
    return final_payload

# Example Usage: params contains whatever is needed for your target endpoint.
# Method arrays (e.g. sendmoney) are flattened by index, not JSON-encoded:
# this becomes params.sendmoney.0.phone_number=254647647649.
payload = {
    "client_id": "YOUR_CLIENT_ID",
    "sender": "MyIntegration",
    "salt": "random_salt_12345",
    "timestamp": int(time.time()),
    "params": {
        "amount": 10000,
        "currency": "KES",
        "country_id": 1,
        "payment_method_type": "send money",
        "callback_url": "https://example.com/callback",
        "third_party_reference_1": "REF-001",
        "third_party_reference_2": "REF-002",
        "sendmoney": [
            {"phone_number": "254647647649"}
        ]
    }
}

signed_request = sign_request(payload, "YOUR_SECRET_KEY")
print(json.dumps(signed_request, indent=2))

<?php

function recursiveKsort(array &$array) {
    ksort($array);
    foreach ($array as &$value) {
        if (is_array($value)) {
            recursiveKsort($value);
        }
    }
}

function stringifyValue($value): string {
    if (is_bool($value)) return $value ? '1' : '';
    if (is_null($value)) return '';
    if (is_string($value)) return trim($value);
    return (string) $value;
}

function convertToQueryString(array $array, ?string $parentKey = null): string {
    $parts = [];
    foreach ($array as $key => $value) {
        $currentKey = $parentKey !== null ? $parentKey . '.' . $key : (string) $key;
        if (is_array($value)) {
            $parts[] = convertToQueryString($value, $currentKey);
        } else {
            $parts[] = $currentKey . '=' . stringifyValue($value);
        }
    }
    return implode('&', $parts);
}

function signRequest(array $payload, string $secretKey): array {
    $prePayload = $payload;
    $prePayload['senderKey'] = trim($secretKey);

    recursiveKsort($prePayload);
    $queryString = convertToQueryString($prePayload);

    $signature = hash('sha256', $queryString);

    $finalPayload = $payload;
    $finalPayload['signature'] = $signature;

    return $finalPayload;
}

// Example Usage: params contains whatever is needed for your target endpoint.
// Method arrays (e.g. sendmoney) are flattened by index, not JSON-encoded:
// this becomes params.sendmoney.0.phone_number=254647647649.
$requestPayload = [
    'client_id' => 'YOUR_CLIENT_ID',
    'sender' => 'MyIntegration',
    'salt' => 'random_salt_12345',
    'timestamp' => time(),
    'params' => [
        'amount' => 10000,
        'currency' => 'KES',
        'country_id' => 1,
        'payment_method_type' => 'send money',
        'callback_url' => 'https://example.com/callback',
        'third_party_reference_1' => 'REF-001',
        'third_party_reference_2' => 'REF-002',
        'sendmoney' => [
            ['phone_number' => '254647647649']
        ]
    ]
];

$signed = signRequest($requestPayload, 'YOUR_SECRET_KEY');
echo json_encode($signed, JSON_PRETTY_PRINT);

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.*;

public class NiobiSignature {

    private static String stringifyValue(Object value) {
        if (value == null) return "";
        if (value instanceof Boolean) return ((Boolean) value) ? "1" : "";
        if (value instanceof String) return ((String) value).trim();
        return String.valueOf(value);
    }

    @SuppressWarnings("unchecked")
    private static String convertToQueryString(Object value, String parentKey) {
        List<Map.Entry<String, Object>> entries = new ArrayList<>();

        if (value instanceof Map) {
            List<String> keys = new ArrayList<>(((Map<String, Object>) value).keySet());
            Collections.sort(keys);
            for (String key : keys) {
                entries.add(new AbstractMap.SimpleEntry<>(key, ((Map<String, Object>) value).get(key)));
            }
        } else if (value instanceof List) {
            List<Object> list = (List<Object>) value;
            for (int i = 0; i < list.size(); i++) {
                entries.add(new AbstractMap.SimpleEntry<>(String.valueOf(i), list.get(i)));
            }
        } else {
            return stringifyValue(value);
        }

        List<String> parts = new ArrayList<>();
        for (Map.Entry<String, Object> entry : entries) {
            String currentKey = (parentKey == null || parentKey.isEmpty())
                ? entry.getKey()
                : parentKey + "." + entry.getKey();
            Object subValue = entry.getValue();

            if (subValue instanceof Map || subValue instanceof List) {
                // Recurse into BOTH maps and lists the same way. An empty
                // map/list contributes an empty string here, not "[]" or "key=".
                parts.add(convertToQueryString(subValue, currentKey));
            } else {
                parts.add(currentKey + "=" + stringifyValue(subValue));
            }
        }
        return String.join("&", parts);
    }

    public static String generateSignature(Map<String, Object> payload, String secretKey) throws NoSuchAlgorithmException {
        // 1. Clone payload and temporarily attach secret key
        Map<String, Object> prePayload = new LinkedHashMap<>(payload);
        prePayload.put("senderKey", secretKey.trim());

        // 2. Sort keys recursively, then flatten into the key=value string
        String queryString = convertToQueryString(prePayload, null);

        // 3. Compute SHA-256 hash
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(queryString.getBytes(StandardCharsets.UTF_8));

        StringBuilder hexString = new StringBuilder();
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }
        return hexString.toString();
    }

    public static void main(String[] args) throws Exception {
        // Method arrays (e.g. sendmoney) are flattened by index, not
        // stringified: this becomes params.sendmoney.0.phone_number=254647647649.
        Map<String, Object> sendMoneyEntry = new LinkedHashMap<>();
        sendMoneyEntry.put("phone_number", "254647647649");

        Map<String, Object> params = new LinkedHashMap<>();
        params.put("amount", 10000);
        params.put("currency", "KES");
        params.put("country_id", 1);
        params.put("payment_method_type", "send money");
        params.put("callback_url", "https://example.com/callback");
        params.put("third_party_reference_1", "REF-001");
        params.put("third_party_reference_2", "REF-002");
        params.put("sendmoney", Collections.singletonList(sendMoneyEntry));

        Map<String, Object> payload = new LinkedHashMap<>();
        payload.put("client_id", "YOUR_CLIENT_ID");
        payload.put("sender", "MyIntegration");
        payload.put("salt", "random_salt_12345");
        payload.put("timestamp", System.currentTimeMillis() / 1000L);
        payload.put("params", params);

        String signature = generateSignature(payload, "YOUR_SECRET_KEY");
        payload.put("signature", signature);

        System.out.println("Generated Signature: " + signature);
    }
}

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"fmt"
	"sort"
	"strconv"
	"strings"
	"time"
)

func stringifyValue(value interface{}) string {
	if value == nil {
		return ""
	}
	switch v := value.(type) {
	case bool:
		if v {
			return "1"
		}
		return ""
	case string:
		return strings.TrimSpace(v)
	default:
		return fmt.Sprintf("%v", v)
	}
}

func isContainer(value interface{}) bool {
	switch value.(type) {
	case map[string]interface{}, []interface{}:
		return true
	default:
		return false
	}
}

func convertToQueryString(value interface{}, parentKey string) string {
	switch v := value.(type) {
	case map[string]interface{}:
		keys := make([]string, 0, len(v))
		for k := range v {
			keys = append(keys, k)
		}
		sort.Strings(keys)

		parts := make([]string, 0, len(keys))
		for _, k := range keys {
			currentKey := k
			if parentKey != "" {
				currentKey = parentKey + "." + k
			}
			subValue := v[k]
			if isContainer(subValue) {
				// Recurse into BOTH maps and slices the same way. An empty
				// map/slice contributes an empty string here, not "[]" or "key=".
				parts = append(parts, convertToQueryString(subValue, currentKey))
			} else {
				parts = append(parts, currentKey+"="+stringifyValue(subValue))
			}
		}
		return strings.Join(parts, "&")

	case []interface{}:
		parts := make([]string, 0, len(v))
		for i, item := range v {
			currentKey := strconv.Itoa(i)
			if parentKey != "" {
				currentKey = parentKey + "." + currentKey
			}
			if isContainer(item) {
				parts = append(parts, convertToQueryString(item, currentKey))
			} else {
				parts = append(parts, currentKey+"="+stringifyValue(item))
			}
		}
		return strings.Join(parts, "&")

	default:
		return stringifyValue(value)
	}
}

func SignRequest(payload map[string]interface{}, secretKey string) string {
	prePayload := make(map[string]interface{}, len(payload)+1)
	for k, v := range payload {
		prePayload[k] = v
	}
	prePayload["senderKey"] = strings.TrimSpace(secretKey)

	// Sort keys recursively (inline, at each level) and flatten into the
	// key=value string in the same pass.
	queryString := convertToQueryString(prePayload, "")

	hash := sha256.Sum256([]byte(queryString))
	return hex.EncodeToString(hash[:])
}

func main() {
	// Method arrays (e.g. sendmoney) are flattened by index, not
	// JSON-marshaled: this becomes params.sendmoney.0.phone_number=254647647649.
	params := map[string]interface{}{
		"amount":              10000,
		"currency":            "KES",
		"country_id":          1,
		"payment_method_type": "send money",
		"callback_url":        "https://example.com/callback",
		"third_party_reference_1": "REF-001",
		"third_party_reference_2": "REF-002",
		"sendmoney": []interface{}{
			map[string]interface{}{"phone_number": "254647647649"},
		},
	}

	payload := map[string]interface{}{
		"client_id": "YOUR_CLIENT_ID",
		"sender":    "MyIntegration",
		"salt":      "random_salt_12345",
		"timestamp": time.Now().Unix(),
		"params":    params,
	}

	signature := SignRequest(payload, "YOUR_SECRET_KEY")
	payload["signature"] = signature

	out, _ := json.MarshalIndent(payload, "", "  ")
	fmt.Println(string(out))
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public class NiobiSignature
{
    private static string StringifyValue(object value)
    {
        if (value == null) return "";
        if (value is bool b) return b ? "1" : "";
        if (value is string s) return s.Trim();
        return Convert.ToString(value, System.Globalization.CultureInfo.InvariantCulture);
    }

    private static bool IsContainer(object value) =>
        value is IDictionary<string, object> || value is IEnumerable<object>;

    private static string ConvertToQueryString(object value, string parentKey)
    {
        if (value is IDictionary<string, object> dict)
        {
            var sortedKeys = dict.Keys.OrderBy(k => k, StringComparer.Ordinal).ToList();
            var parts = new List<string>();
            foreach (var key in sortedKeys)
            {
                string currentKey = string.IsNullOrEmpty(parentKey) ? key : $"{parentKey}.{key}";
                var subValue = dict[key];
                // Recurse into BOTH dictionaries and lists the same way. An empty
                // dictionary/list contributes an empty string, not "[]" or "key=".
                parts.Add(IsContainer(subValue)
                    ? ConvertToQueryString(subValue, currentKey)
                    : $"{currentKey}={StringifyValue(subValue)}");
            }
            return string.Join("&", parts);
        }

        if (value is IEnumerable<object> list)
        {
            var parts = new List<string>();
            int i = 0;
            foreach (var item in list)
            {
                string currentKey = string.IsNullOrEmpty(parentKey) ? i.ToString() : $"{parentKey}.{i}";
                parts.Add(IsContainer(item)
                    ? ConvertToQueryString(item, currentKey)
                    : $"{currentKey}={StringifyValue(item)}");
                i++;
            }
            return string.Join("&", parts);
        }

        return StringifyValue(value);
    }

    public static string GenerateSignature(Dictionary<string, object> payload, string secretKey)
    {
        var prePayload = new Dictionary<string, object>(payload)
        {
            ["senderKey"] = secretKey.Trim()
        };

        // Sort keys recursively (inline, at each level) and flatten into the
        // key=value string in the same pass.
        string queryString = ConvertToQueryString(prePayload, null);

        using var sha256 = SHA256.Create();
        byte[] bytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(queryString));
        return BitConverter.ToString(bytes).Replace("-", "").ToLowerInvariant();
    }

    public static void Main()
    {
        // Method arrays (e.g. sendmoney) are flattened by index, not
        // serialized: this becomes params.sendmoney.0.phone_number=254647647649.
        var paramsDict = new Dictionary<string, object>
        {
            { "amount", 10000 },
            { "currency", "KES" },
            { "country_id", 1 },
            { "payment_method_type", "send money" },
            { "callback_url", "https://example.com/callback" },
            { "third_party_reference_1", "REF-001" },
            { "third_party_reference_2", "REF-002" },
            { "sendmoney", new List<object> {
                new Dictionary<string, object> { { "phone_number", "254647647649" } }
            } }
        };

        var payload = new Dictionary<string, object>
        {
            { "client_id", "YOUR_CLIENT_ID" },
            { "sender", "MyIntegration" },
            { "salt", "random_salt_12345" },
            { "timestamp", DateTimeOffset.UtcNow.ToUnixTimeSeconds() },
            { "params", paramsDict }
        };

        string signature = GenerateSignature(payload, "YOUR_SECRET_KEY");
        payload["signature"] = signature;

        Console.WriteLine(JsonSerializer.Serialize(payload, new JsonSerializerOptions { WriteIndented = true }));
    }
}

Method 2: Generating Signatures via the Niobi Signature Generation API

If you prefer not to write custom cryptographic sorting and hashing functions, or if you want to quickly test requests in Postman or Sandbox, Niobi provides a dedicated Signature Generation endpoint: Endpoint: POST /api/niobi-signature

Step 1: Send Your Request Parameters to the Signature Endpoint

Construct a request containing the following fields:

Field	Requirement	Description
`client_id`	Required	Your integration Client ID from the Niobi Dashboard.
`sender`	Required	Your exact integration title from the dashboard.
`salt`	Required	A unique random string generated on your server for entropy.
`params`	Required	Object containing the specific parameters for the destination endpoint you intend to call.

{
  "sender": "Integration_title",
  "salt": "random_salt_value",
  "client_id": "your_client_key_here",
  "params": {
    "amount": 10000,
    "mobile": "254161166649",
    "country_id": 1,
    "currency": "KES",
    "payment_method_type": "send money",
    "callback_url": "https://yourdomain.com/callback",
    "third_party_reference_1": "REF-001",
    "third_party_reference_2": "REF-002"
  }
}

Step 2: Receive the Complete Signed Payload

Niobi validates your client_id, calculates the SHA-256 signature using your account’s registered Secret Key, and returns the full signed envelope inside the data object:

{
  "success": true,
  "message": "Signature was generated successfully.",
  "data": {
    "client_id": "your_client_key_here",
    "params": {
      "amount": 10000,
      "mobile": "254161166649",
      "country_id": 1,
      "currency": "KES",
      "payment_method_type": "send money",
      "callback_url": "https://yourdomain.com/callback",
      "third_party_reference_1": "REF-001",
      "third_party_reference_2": "REF-002"
    },
    "salt": "random_salt_value",
    "sender": "Integration_title",
    "timestamp": 1724835600,
    "signature": "c6b98e1f5d6a7890bc4e123456789abcdef0123456789abcdef0123456789abc"
  }
}

Step 3: Pass the Signed Payload to the Target API

You can now take the exact JSON object inside data and send it directly to your target endpoint (e.g. POST /api/v4/niobi-unified-collections or POST /api/v4/niobi-unified-payments) without changing or modifying anything as it is.

Do Not Modify the Returned Payload:
You must transmit the JSON object inside data exactly as returned, without adding, altering, or removing any fields. Any modification to parameters or values after generation will invalidate the signature and cause the target endpoint to reject your request with a 403 Request was not verified error.

Verifying Response & Webhook Signatures

When receiving a synchronous response or asynchronous webhook callback from Niobi, you can verify its authenticity using either code or the Verification API:

1. In Code (5 Steps):

Extract Signature: Store the "signature" field from the incoming JSON and remove it from the object.
Add Secret Key: Add "senderKey": "your_secret_key_here" into the object.
Sort and Stringify: Alphabetically sort keys recursively (K-sort) and format into key=value concatenated with &.
Compute SHA-256 Hash: Hash the string with SHA-256.
Compare Signatures: Compare your computed hash with the signature received in Step 1.

2. Via the Verification Helper API:

Send the payload to POST /api/niobi-verify:

{
  "success": true,
  "message": "Request verified successfully."
}

Next Steps

Now that you can generate valid signatures, proceed to construct the signed request envelope:

Step 2

How to Pass Signature in API Requests

Learn how to structure the final signed envelope, set required headers, and avoid common 403 errors.

Integration

Start Collecting Payments

Send signed requests to the unified collection API to accept customer payments.

Get Started with Niobi

API Authentication

Collecting Payments

Making Payments

Transaction Status

Supporting Documentation

How to Create the Signature

Overview

Method 1: The Request Signing Algorithm (In Code)

Detailed Payload Walkthrough

1. Before Signing (Pre-Signature Payload)

2. Flattened, Sorted and Stringified Format

3. Final Signed Request Payload (Ready to Send to the Matching API Endpoint)

Implementation Code Examples

Method 2: Generating Signatures via the Niobi Signature Generation API

Step 1: Send Your Request Parameters to the Signature Endpoint

Step 2: Receive the Complete Signed Payload

Step 3: Pass the Signed Payload to the Target API

Verifying Response & Webhook Signatures

1. In Code (5 Steps):

2. Via the Verification Helper API:

Next Steps

How to Pass Signature in API Requests

Start Collecting Payments

​Overview

​Method 1: The Request Signing Algorithm (In Code)

​Detailed Payload Walkthrough

​1. Before Signing (Pre-Signature Payload)

​2. Flattened, Sorted and Stringified Format

​3. Final Signed Request Payload (Ready to Send to the Matching API Endpoint)

​Implementation Code Examples

​Method 2: Generating Signatures via the Niobi Signature Generation API

​Step 1: Send Your Request Parameters to the Signature Endpoint

​Step 2: Receive the Complete Signed Payload

​Step 3: Pass the Signed Payload to the Target API

​Verifying Response & Webhook Signatures

​1. In Code (5 Steps):

​2. Via the Verification Helper API:

​Next Steps

​How to Pass Signature in API Requests

​Start Collecting Payments

Overview

Method 1: The Request Signing Algorithm (In Code)

Detailed Payload Walkthrough

1. Before Signing (Pre-Signature Payload)

2. Flattened, Sorted and Stringified Format

3. Final Signed Request Payload (Ready to Send to the Matching API Endpoint)

Implementation Code Examples

Method 2: Generating Signatures via the Niobi Signature Generation API

Step 1: Send Your Request Parameters to the Signature Endpoint

Step 2: Receive the Complete Signed Payload

Step 3: Pass the Signed Payload to the Target API

Verifying Response & Webhook Signatures

1. In Code (5 Steps):

2. Via the Verification Helper API:

Next Steps

How to Pass Signature in API Requests

Start Collecting Payments