Overview
Building a resilient, production-ready payment collection flow requires proper error handling, disciplined polling behavior, strict input validation, and reliable transaction reconciliation. Follow these best practices to ensure seamless transaction processing and avoid common production pitfalls.1. When to Query Status vs. Waiting for Callbacks
Niobi processes transactions asynchronously with regional payment switches and mobile network operators.Primary FlowCollection Callback
Rely on the incoming payment_step: 2 payload.
Fallback FlowTransaction Status Query API
Query with spaced intervals if the callback isn’t received.
Best Practices for Status Handling:
- Rely on Callbacks as the Primary Source:
The callback delivered to yourcallback_urlis the primary and most efficient notification mechanism. - Avoid Aggressive Polling Loops:
Do not poll the status API immediately in a tight loop after initiating a collection. Aggressive polling consumes unnecessary bandwidth and may trigger rate limits. - Query Status Using Spaced Intervals:
If your server has not received a callback after a while, you can query the Get Transaction Status API (POST /api/v3/get-unified-transaction-status) using spaced intervals (e.g. progressive backoff) to reconcile pending collection transactions.
2. The Double-Verification Reconciliation Recipe
For mission-critical workflows where releasing value prematurely or acting on an unverified signal creates financial risk, Niobi recommends implementing a double-verification reconciliation recipe: rely on thepayment_step: 2 callback as your primary signal, fall back to a status query if it hasn’t arrived, and only close out the order once that confirmed status is reconciled against your own internal order records.
When to Implement Double-Verification:
- Instant Digital Value & Wallet Credits: Crypto on-ramps, forex trading platforms, and digital wallet top-ups where credited funds can be immediately withdrawn.
- Automated Chain Reactions (Collection to Payout): Systems where collection completion automatically triggers a downstream disbursement (e.g. cross-border remittances or escrow releases).
- High-Value B2B Invoicing & Automated Dispatch: Wholesalers or e-commerce platforms triggering automated warehouse dispatch upon payment confirmation.
The 4-Step Technical Reconciliation Flow:
Reconciliation Checklist:
- Inbound Signature Verification: Always verify the incoming SHA-256 callback signature using your integration Secret Key (
senderKey) before parsing the payload. - Concurrency Lock & Idempotency Check: Acquire a row-level database lock on
third_party_reference_1before processing balance updates. If both a callback and a status query arrive concurrently, only the first thread processes the credit while the second safely exits. - Triple-Point Data Match: Confirm that all three attributes match your internal order record:
- Status & Code: Both
status: "success"andstatusCode: "000000"(Success Code 000000). - Amount & Currency: The received
amountmatches the exact order total (prevents underpayment fulfillment). - Reference: The
third_party_reference_1matches the specific customer order ID.
- Status & Code: Both
- Atomic Ledger Settlement: Execute the balance credit and update the local order status to
SETTLEDinside a single atomic database transaction.
3. Phone Number & Amount Formatting Rules
Strict Integer Rule for amount (No Decimal Points)
All collection amounts submitted in API requests MUST be whole integers (e.g. 1000 for 1,000 KES/NGN/ZAR). Do not send decimal points (such as 1000.50 or 1000.00). Submitting decimal amounts will cause the request to fail validation.
Phone Number Formatting Rules:
- Digits Only: Strip all spaces, plus signs (
+), hyphens, parentheses, or symbols. - Length: Between 8 and 15 digits (including country code).
- International Prefix without Plus: Always include the country code, but omit the leading
+or local trunk0.
4. Error Handling & Retry Policies
Design your integration to distinguish between permanent client errors and temporary upstream issues:1. Handling 4xx Client Errors (Do Not Auto-Retry)
1. Handling 4xx Client Errors (Do Not Auto-Retry)
Examples:
Action: Do not retry these requests automatically with the same payload. Log the error message, inspect your parameter validation, verify your signature generation algorithm, and correct the payload before resending. See 400 Client Errors for code breakdowns.
400 Bad Request, 403 Request not verified, 404 Not Found.Action: Do not retry these requests automatically with the same payload. Log the error message, inspect your parameter validation, verify your signature generation algorithm, and correct the payload before resending. See 400 Client Errors for code breakdowns.
2. Handling 5xx Server Errors (Retry with Exponential Backoff)
2. Handling 5xx Server Errors (Retry with Exponential Backoff)
Examples:
Action: Implement exponential backoff (e.g. retry after 2s, 4s, 8s, 16s) up to a maximum of 3 to 5 attempts. If timeouts persist, check transaction status before re-initiating.
500 Internal Server Error, 502 Bad Gateway, 504 Gateway Timeout.Action: Implement exponential backoff (e.g. retry after 2s, 4s, 8s, 16s) up to a maximum of 3 to 5 attempts. If timeouts persist, check transaction status before re-initiating.
3. Exact Amount Handling for Virtual Accounts
3. Exact Amount Handling for Virtual Accounts
For Nigerian NGN virtual account collections, always collect the exact amount. Any excess payment is automatically reversed by the banking system, which may cause customer confusion if not handled cleanly.