Payout Callbacks

Overview

Because disbursement processing across African mobile money switches and interbank clearing systems is asynchronous, Niobi notifies your server of the final settlement outcome by sending an HTTP POST callback request to the client_callback_url specified under params.client_callback_url in your disbursement request.

Terminal Callback Guarantee (`payment_step: 2`)

Terminal Settlement Rule:
Only mark payouts as cleared and notify recipients when the callback delivers payment_step: 2 with status: "success" and statusCode: "000000". Never assume clearance on initial dispatch (payment_step: 1). If status: "failed" (statusCode: "000005") is received, the payout failed at the destination switch and merchant funds are unlocked.

The callback is delivered for both successful (status: "success", statusCode: "000000") and failed (status: "failed", statusCode: "000005") disbursements.
Update your application’s payout records based on both the status and statusCode fields delivered inside params. See our Transaction Status Codes Reference for details.

Callback Payload Structure

Incoming payout callbacks from Niobi follow the standard signed envelope structure:

1. Successful Payout Callback (`payment_step: 2`)

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "salt": "random_salt_value",
  "timestamp": 1724835630,
  "signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
  "params": {
    "amount": 1000,
    "currency": "KES",
    "mobile": "254647647649",
    "payment_method_type": "send money",
    "payment_reference": "PAYOUT-REF-1001",
    "payment_step": 2,
    "reference": "NIO-PAYOUT-789012",
    "status": "success",
    "statusCode": "000000",
    "third_party_reference_1": "TX-DISB-9901"
  }
}

2. Failed Payout Callback (`payment_step: 2`)

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "salt": "random_salt_value",
  "timestamp": 1724835635,
  "signature": "e5f6a7b8c90123456789abcdef0123456789abcdef0123456789abcdef012345",
  "params": {
    "amount": 1000,
    "currency": "KES",
    "mobile": "254647647649",
    "payment_method_type": "send money",
    "payment_reference": "PAYOUT-REF-1001",
    "payment_step": 2,
    "reference": "NIO-PAYOUT-789012",
    "status": "failed",
    "statusCode": "000005",
    "failureReason": {
      "failureCode": "DS-008",
      "failureMessage": "Recipient mobile money wallet is inactive or unregistered"
    },
    "third_party_reference_1": "TX-DISB-9901"
  }
}

Callback Payload Parameters (`params` Object)

Parameter	Type	Description
`params.amount`	`integer`	Disbursed amount in major currency units.
`params.currency`	`string`	3-letter currency code (e.g. `KES`).
`params.mobile`	`string`	Recipient mobile phone number.
`params.payment_method_type`	`string`	Payout channel used.
`params.payment_reference`	`string`	Your internal payout reference.
`params.payment_step`	`integer`	Set to `2` for terminal disbursement callbacks.
`params.reference`	`string`	Niobi unique system transaction ID.
`params.status`	`string`	Outcome status: `"success"` or `"failed"`.
`params.statusCode`	`string`	System status code: `"000000"` (success) or `"000005"` (failed).
`params.failureReason`	`object`	Detailed diagnostic object (present on failed callbacks).
`params.third_party_reference_1`	`string`	Your primary merchant idempotency tracking reference.

Verifying Callback Signatures

Always verify incoming payout callbacks using HMAC SHA-256 before applying ledger balance updates:

Extract Root Fields: Extract client_id, sender, salt, timestamp, and params from the callback payload.
Inject Secret Key: Add "senderKey": "YOUR_SECRET_KEY" into the payload object.
Sort Keys (Recursive K-Sort): Alphabetically sort all keys recursively.
Flatten & Hash: Convert to key-value query string format concatenated with &, and hash with SHA-256.
Compare: Compare your computed hash with the signature from Step 1. If they match, the callback is authentic.

Dual-Layer Confirmation: Querying Payout Status

As an additional layer of confirmation, Niobi encourages querying the transaction status alongside listening for callbacks. Combining the incoming asynchronous callback with an on-demand status query gives your system independent, double-verified confirmation before closing batch payout runs. The full recipe is three steps: rely on the callback as your primary signal, fall back to a status query if it hasn’t arrived, and only close out the payout once that confirmed status is reconciled against your own internal payout records.

Endpoint

POST /api/v3/get-unified-transaction-status

Request Parameters (`params` Object)

Field	Requirement	Type	Description
`id`	Required	`string`	The payout transaction reference to query. Pass your `reference`, `payment_reference`, or `third_party_reference_1`.
`type`	Required	`string`	Must be set to `"payout"` for disbursement and payout transactions.

Sample Signed Status Query Request

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835600,
  "salt": "random_salt_12345",
  "signature": "b1c2d3e4f5a60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
  "params": {
    "id": "PAYOUT-REF-1001",
    "type": "payout"
  }
}

Sample Status Query Response

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": 1000,
    "fee": 25,
    "currency": "KES",
    "status": "success",
    "mobile": "254647647649",
    "transaction_id": "DR-NIO-P98765432",
    "ref": "PAYOUT-REF-1001",
    "payment_method_type": "send money",
    "third_party_reference_1": "TX-DISB-9901",
    "created_at": "2026-08-28 12:35:00"
  },
  "status_code": "000000"
}

Reconciling Query Results:

status: "success" (status_code: "000000"): Funds were successfully credited to the recipient. Mark the payout order as completed in your ledger.
status: "failed" (status_code: "000005"): The disbursement failed; funds remain in (or have been refunded to) your merchant wallet. Mark the payout as failed.
status: "pending" (status_code: "000001"): The transfer is still processing with the destination network switch. Do not take action on this state (do not retry the transfer or adjust recipient balances). Keep the payout in a pending state and await the asynchronous callback (payment_step: 2) or re-query after a brief delay.

Callback Receiver Implementation Guidelines

1. Respond Promptly with HTTP 200

Your callback listener should respond with an HTTP 200 OK status as quickly as possible (ideally within 3 to 5 seconds). Perform long-running background tasks (e.g. sending SMS receipts or updating external ERPs) asynchronously in a background job queue after returning 200 OK.

2. Implement Idempotent Processing

In rare cases of network timeouts between Niobi and your server, callback notifications may be retried. Ensure your callback handler uses params.reference or params.payment_reference to verify whether a disbursement has already been marked as complete before applying balance adjustments.

3. Avoid Aggressive Polling Loops

Rely on the payment_step: 2 callback as the primary notification mechanism. Do not continuously poll the status API in a tight loop while waiting for a callback; if a callback has not been received after a while, query the Get Transaction Status API (POST /api/v3/get-unified-transaction-status) using spaced intervals.

Resending Callbacks via the Payment Portal

You can resend callbacks in case of a delivery failure through the payment portal. To do this, access the specific transaction and click on Resend Callback.

Resend Callback from Niobi Payment Portal — Resending a failed callback delivery directly from the transaction details modal in the payment portal

When can a callback be resent?
The Resend Callback option can only be triggered via the payment portal for a deposit or payout request in cases where the callback was not delivered correctly to your server (for example, if your listener experienced downtime, timed out, or returned an HTTP error). It is not displayed for callbacks that were already acknowledged with HTTP 200.

Next Steps

Follow these guides to complete and secure your payout flow:

Step 3

Payout Best Practices

Wallet balance management, recipient phone validation, idempotency, and error handling.

Reconciliation

Get Transaction Status API

Query payout transaction status as an independent fallback verification mechanism.

Get Started with Niobi

API Authentication

Collecting Payments

Making Payments

Transaction Status

Supporting Documentation

Payout Callbacks

Overview

Terminal Callback Guarantee (`payment_step: 2`)

Callback Payload Structure

1. Successful Payout Callback (`payment_step: 2`)

2. Failed Payout Callback (`payment_step: 2`)

Callback Payload Parameters (`params` Object)

Verifying Callback Signatures

Dual-Layer Confirmation: Querying Payout Status

Endpoint

Request Parameters (`params` Object)

Sample Signed Status Query Request

Sample Status Query Response

Reconciling Query Results:

Callback Receiver Implementation Guidelines

Resending Callbacks via the Payment Portal

Next Steps

Payout Best Practices

Get Transaction Status API

​Overview

​Terminal Callback Guarantee (payment_step: 2)

​Callback Payload Structure

​1. Successful Payout Callback (payment_step: 2)

​2. Failed Payout Callback (payment_step: 2)

​Callback Payload Parameters (params Object)

​Verifying Callback Signatures

​Dual-Layer Confirmation: Querying Payout Status

​Endpoint

​Request Parameters (params Object)

​Sample Signed Status Query Request

​Sample Status Query Response

​Reconciling Query Results:

​Callback Receiver Implementation Guidelines

​Resending Callbacks via the Payment Portal

​Next Steps

​Payout Best Practices

​Get Transaction Status API

Overview

Terminal Callback Guarantee (`payment_step: 2`)

Callback Payload Structure

1. Successful Payout Callback (`payment_step: 2`)

2. Failed Payout Callback (`payment_step: 2`)

Callback Payload Parameters (`params` Object)

Verifying Callback Signatures

Dual-Layer Confirmation: Querying Payout Status

Endpoint

Request Parameters (`params` Object)

Sample Signed Status Query Request

Sample Status Query Response

Reconciling Query Results:

Callback Receiver Implementation Guidelines

Resending Callbacks via the Payment Portal

Next Steps

Payout Best Practices

Get Transaction Status API