Transaction Status & Reconciliation

Overview

While asynchronous webhook callbacks (payment_step: 2) are Niobi’s primary real-time notification mechanism, the Get Transaction Status API provides an authoritative on-demand verification endpoint. Use this endpoint to:

Resolve In-Doubt Transactions: Check transaction outcomes if a temporary network disruption delayed your incoming callback.
Execute Double-Verification: Reconcile mission-critical payments (such as high-value payouts or instant digital wallet top-ups) by confirming webhook data against an independent status query.
Audit & Recover: Safely query historical or batch transaction records during automated ledger closeouts.

API Environments & Base URLs

Environment	Base URL	Endpoint Path
Sandbox	`https://sandbox.users.niobi.co`	`/api/v3/get-unified-transaction-status`
Production	`https://users.niobi.co`	`/api/v3/get-unified-transaction-status`

Request Parameters

The status query endpoint requires standard HMAC SHA-256 envelope parameters wrapping the query details in params:

Root Envelope Fields

Field	Type	Required	Description
`client_id`	`string`	Yes	Your integration Client ID from the Niobi Dashboard.
`sender`	`string`	Yes	Your exact integration title as registered in the dashboard.
`timestamp`	`integer`	Yes	Unix timestamp (in seconds) used during signature calculation.
`salt`	`string`	Yes	A random unique string generated for entropy.
`signature`	`string`	Yes	The computed 64-character SHA-256 hash.
`params`	`object`	Yes	The query specification object.

Parameters (`params` Object)

Parameter	Type	Required	Description
`id`	`string`	Yes	The transaction identifier to query. You can pass Niobi’s `reference` (e.g. `NIO-S0000062`), your `payment_reference`, or your `third_party_reference_1`.
`type`	`string`	Yes	Must be set to `"payin"` for collections (deposits) or `"payout"` for disbursements.

Sample Status Query Requests

Collection Query (payin)
Payout Query (payout)

{
  "client_id": "YOUR_CLIENT_ID",
  "sender": "YOUR_INTEGRATION_NAME",
  "timestamp": 1724835600,
  "salt": "random_salt_12345",
  "signature": "a1b2c3d4e5f60718293a4b5c6d7e8f90123456789abcdef0123456789abcdef0",
  "params": {
    "id": "TX-COLL-1001",
    "type": "payin"
  }
}

{
  "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 Query Responses

Successful Transaction (000000)
Pending Transaction (000001)
Failed Transaction (000005)
Timed Out Collection (000006)

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": 1000,
    "fee": 10,
    "currency": "KES",
    "status": "success",
    "mobile": "254161166649",
    "account_number": "80000002",
    "transaction_id": "CR-NIO-S0000062",
    "ref": "TX-COLL-1001",
    "payment_method_type": "send money",
    "third_party_reference_1": "TX-COLL-1001",
    "third_party_reference_2": "CUST-450",
    "created_at": "2026-08-28 12:30:00",
    "updated_at": "2026-08-28 12:30:15",
    "status_code": "000000",
    "failureReason": {
      "failureCode": null,
      "failureMessage": null
    }
  }
}

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": 1000,
    "fee": 0,
    "currency": "KES",
    "status": "pending",
    "mobile": "254161166649",
    "account_number": "80000002",
    "transaction_id": "CR-NIO-S0000062",
    "ref": "TX-COLL-1001",
    "payment_method_type": "send money",
    "third_party_reference_1": "TX-COLL-1001",
    "third_party_reference_2": "CUST-450",
    "created_at": "2026-08-28 12:30:00",
    "updated_at": "2026-08-28 12:30:05",
    "status_code": "000001",
    "failureReason": {
      "failureCode": null,
      "failureMessage": null
    }
  }
}

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": 1000,
    "fee": 0,
    "currency": "KES",
    "status": "failed",
    "mobile": "254161166649",
    "account_number": "80000002",
    "transaction_id": "CR-NIO-S0000062",
    "ref": "TX-COLL-1001",
    "payment_method_type": "send money",
    "third_party_reference_1": "TX-COLL-1001",
    "third_party_reference_2": "CUST-450",
    "created_at": "2026-08-28 12:30:00",
    "updated_at": "2026-08-28 12:30:20",
    "status_code": "000005",
    "failureReason": {
      "failureCode": "DS-004",
      "failureMessage": "User cancelled transaction / Payment declined by user"
    }
  }
}

{
  "success": true,
  "message": "Transaction data fetched successfully.",
  "data": {
    "amount": 1000,
    "fee": 0,
    "currency": "KES",
    "status": "timeout",
    "mobile": "254161166649",
    "account_number": "80000002",
    "transaction_id": "CR-NIO-S0000062",
    "ref": "TX-COLL-1001",
    "payment_method_type": "send money",
    "third_party_reference_1": "TX-COLL-1001",
    "third_party_reference_2": "CUST-450",
    "created_at": "2026-08-28 12:30:00",
    "updated_at": "2026-08-28 12:32:00",
    "status_code": "000006",
    "failureReason": {
      "failureCode": "TO-001",
      "failureMessage": "The transaction timed out. The payment prompt was not completed within the allowed time window."
    }
  }
}

Status Codes & Action Matrix

When querying transaction status, inspect both data.status and data.status_code:

Status Code	Status String	State Type	Meaning	Developer Action
`000000`	`"success"`	Terminal	Transaction completed and settled. Funds credited to recipient/merchant.	Fulfill the customer order, update user wallet balance, or mark payout as complete.
`000001`	`"pending"`	Non-Terminal	Authorization or upstream network switch processing is in progress.	Do NOT act on this state. Do not fulfill orders, retry transfers, or mark as failed. Wait for callback or re-query after a delay.
`000005`	`"failed"`	Terminal	Transaction was declined, rejected, or reversed by the upstream provider.	Mark order/payout as failed. Inspect `failureReason` for specific provider diagnostics.
`000006`	`"timeout"`	Non-Terminal	Collection prompt session timed out before the customer completed authorization. (Collections/deposits only)	Check status again after 2 to 3 minutes before taking further action.

Strict Rule on pending (000001):
Never release value, credit user wallets, fulfill goods, or retry payments while a transaction is in pending status. A pending status indicates the transaction is in-flight across banking or telecommunication switches. Always wait for a terminal status (000000 or 000005).

The Double-Verification Reconciliation Recipe

For platforms managing high financial volume, automated payroll, or instant digital withdrawals, implement Niobi’s recommended double-verification recipe:

Reconciliation Checklist:

Inbound Signature Verification: Validate incoming webhook signatures using your Secret Key before parsing data.
Concurrency Control: Use database row-level locking (SELECT ... FOR UPDATE or optimistic locking on third_party_reference_1) to ensure duplicate callbacks or simultaneous polling queries do not process twice.
Triple-Point Match: Confirm that statusCode, amount, currency, and third_party_reference_1 match your internal order record exactly.
Atomic Settlement: Update your internal ledger to SETTLED inside a single atomic database transaction.

Polling Guidelines & Best Practices

To ensure optimal performance and avoid hitting rate limits:

Rely on Webhooks First: Use callbacks as your primary notification channel.
Avoid Tight Polling Loops: Never poll the status API immediately in rapid loops (e.g. every second).
Use Spaced Backoff Intervals: If you must poll for a pending transaction, use progressive spaced intervals (for example: wait 5 seconds after initiation, then 15 seconds, then 30 seconds, then 60 seconds).
Idempotency Keys: Always query using the same third_party_reference_1 or reference originally assigned to the transaction.

Next Steps

Explore related operational and security guides:

Architecture

Idempotency & Uniqueness

How Niobi prevents duplicate transactions, handles reference tracking, and ensures safe retries.

API Reference

Get Transaction Status API

Complete OpenAPI schema and interactive request builder for the status endpoint.

Get Started with Niobi

API Authentication

Collecting Payments

Making Payments