How to Pass the Signature in Requests

Overview

Once you have generated your signature, either locally via the SHA-256 algorithm or using the Niobi Signature Generation API, the final step is formatting and dispatching the HTTP request. Every Niobi API request follows a standardized envelope structure that bundles your authentication metadata with your specific payment parameters.

Pre-requisite: IP Whitelisting
Before sending any API requests to Niobi servers or endpoints (in Sandbox or Production), your server’s outgoing public IP address must be whitelisted in the Niobi Dashboard under Workspace -> IP Whitelisting. Requests sent from non-whitelisted IPs will be blocked. See our IP Whitelisting Guide for setup steps.

Request Envelope Structure

Every signed request to Niobi contains two tiers:

Root-Level Authentication Metadata: Identifies your integration, timestamp, salt, and cryptographic signature.
Nested params Object: Contains whatever specific parameters are required by the destination endpoint you are invoking.

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835600,
  "salt": "random_salt_string",
  "signature": "c6b98e1f5d6a7890bc4e123456789abcdef0123456789abcdef0123456789abc",
  "params": {
    /* Destination endpoint-specific parameters go here */
  }
}

Root Fields Specification

Field	Type	Required	Description
`client_id`	`string`	Yes	The unique identifier assigned to your integration in the Niobi Dashboard.
`sender`	`string`	Yes	The exact name of your integration entity as created in the dashboard.
`timestamp`	`integer` / `string`	Yes	The exact UNIX timestamp (in seconds) used when the request was signed.
`salt`	`string`	Yes	A unique random string generated on your server providing an additional layer of security and entropy.
`signature`	`string`	Yes	64-character hexadecimal SHA-256 hash computed using your Secret Key (or returned by the Niobi Signature Generation API).
`params`	`object`	Yes	The nested parameters required by the specific target endpoint.

The params Object is Dynamic:
The outer fields (client_id, sender, timestamp, salt, signature) never change between endpoints. But the contents of "params": { ... } change to match the schema of the endpoint you are calling.

Complete Request Examples Across Endpoints

Collections / Deposits
Payouts / Disbursements

Endpoint: POST /api/v4/niobi-unified-collections

{
  "client_id": "client_id",
  "sender": "Integration_name",
  "timestamp": 1724835600,
  "salt": "salt_value",
  "signature": "c6b98e1f5d6a7890bc4e123456789abcdef0123456789abcdef0123456789abc",
  "params": {
    "amount": 10000,
    "currency": "KES",
    "country_id": 1,
    "mobile": "254161166649",
    "payment_method_type": "send money",
    "callback_url": "https://yourdomain.com/callbacks",
    "third_party_reference_1": "TX-COLL-001",
    "third_party_reference_2": "CUST-450"
  }
}

View Unified Collections API Reference ->

Endpoint: POST /api/v4/niobi-unified-payments

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835600,
  "salt": "random_salt_67890",
  "signature": "e5f6a7b8c90123456789abcdef0123456789abcdef0123456789abcdef012345",
  "params": {
    "amount": 5000,
    "currency": "KES",
    "country_id": 1,
    "payment_method_type": "send money",
    "payment_reference": "PAYOUT-REF-1001",
    "first_name": "Jane",
    "last_name": "Doe",
    "mobile": "254647647649",
    "email": "jane.doe@example.com",
    "city": "Nairobi",
    "postal_code": "00100",
    "address": "Kilimani, Nairobi",
    "client_callback_url": "https://yourdomain.com/payout-callbacks",
    "third_party_reference_1": "PAYOUT-REF-1001",
    "third_party_reference_2": "BATCH-AUG",
    "sendmoney": [
      { "phone_number": "254647647649" }
    ],
    "sub_merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

View Unified Payments API Reference ->

Sub-Merchant Parameter Placement

If you are operating multiple distinct brands or merchants under one master account:

Pass the approved sub-merchant UUID in params.sub_merchant_id.
The sub_merchant_id field must be included in the pre-signature object when generating the signature (either in code or via the Niobi Signature Generation API) so that the hash remains valid.
For more information on creating and managing sub-merchants, see Sub-Merchant Management.

Common Pitfalls & How to Avoid Them

1. Leaving senderKey in the request body

Error: Security hazard and potential rejection.
Fix: The senderKey is strictly used on your server to compute the SHA-256 hash. Always delete senderKey before sending the payload over the wire.

2. Modifying params after computing the signature (403 Error)

Error: 403 - Request was not verified.
Fix: If any field in params or the root envelope changes (e.g. updating an amount or reference), the signature must be recomputed.

3. URL-encoding the callback URL before hashing

Error: Signature mismatch on the server.
Fix: When stringifying the pre-signature object, ensure callback_url remains unencoded (e.g. https://yourdomain.com/callback rather than https%3A%2F%2F...).

4. Type mismatch between signing and dispatching

Error: Signature mismatch.
Fix: Ensure parameter types remain consistent (e.g. if amount is a number 10000, do not send "10000" as a string).

5. Sending requests from an unwhitelisted IP address

Error: Request blocked or connection refused.
Fix: Ensure your server’s outgoing public IP address is whitelisted in your Niobi Dashboard under Workspace -> IP Whitelisting. See our IP Whitelisting Guide.

6. Unintentional leading or trailing whitespace

Error: 403 - Request was not verified.
Fix: Trailing or leading whitespace can occur on your credentials (client_id, sender, senderKey) when copied from the dashboard, as well as on string parameter values inside params (e.g. callback_url, mobile, email, payment_reference). Always trim string values across all fields before computing the hash to prevent signature mismatches.

Next Steps

You are now ready to make authenticated API requests:

Payin

Collecting Payments

Learn how to initiate collections across mobile money, cards, and bank transfers.

Payout

Making Payments

Learn how to initiate disbursements and payouts across 17+ African markets.

Get Started with Niobi

API Authentication

Collecting Payments

Making Payments

Transaction Status

Supporting Documentation

How to Pass the Signature in Requests

Overview

Request Envelope Structure

Root Fields Specification

Complete Request Examples Across Endpoints

Sub-Merchant Parameter Placement

Common Pitfalls & How to Avoid Them

Next Steps

Collecting Payments

Making Payments

​Overview

​Request Envelope Structure

​Root Fields Specification

​Complete Request Examples Across Endpoints

​Sub-Merchant Parameter Placement

​Common Pitfalls & How to Avoid Them

​Next Steps

​Collecting Payments

​Making Payments

Overview

Request Envelope Structure

Root Fields Specification

Complete Request Examples Across Endpoints

Sub-Merchant Parameter Placement

Common Pitfalls & How to Avoid Them

Next Steps

Collecting Payments

Making Payments