Skip to content

Niobi integration scope

Status: Scoped from Niobi’s public docs (docs.niobi.co, read 2026-11-02) and Niobi’s answers the same day. Revised 2026-11-02: direct collections API with our own top-up screen, not hosted checkout (decisions log, Top-ups through Niobi’s direct collections API). Owner: Hassan Tasks: phase 6 (P6.01–P6.08), P9.02 (webhook path in production)

How Router.Africa collects top-ups through Niobi: what we call, how we sign, the customer flows, how a payment comes back, and the limits per market. Design context: ../product/design-doc.md section 4; decisions log Niobi payments static IP handling, Niobi webhooks, Top-up status check.

Only collections. No payouts, no sub-merchants (design doc section 2), no wallets beyond the one pooled merchant wallet.

Use Endpoint Called from
Start a top-up payment POST /api/v4/niobi-unified-collections niobi-proxy
Côte d’Ivoire Orange: submit the customer’s OTP the OTP verify step (docs, OTP-Verified Payins) niobi-proxy
Confirm a payment’s outcome (status check, and before every credit) POST /api/v3/get-unified-transaction-status (type: "payin") niobi-proxy
Pooled wallet balance, for reconciliation get-account-balance niobi-proxy
Receive the outcome our callback URL, POST from Niobi niobi-proxy (webhook route)

Not used at launch: payment links (hosted checkout). Its pages can’t be framed (X-Frame-Options: SAMEORIGIN, checked 2026-11-02), and a link can’t carry our reference. It is the likely route for card payments later, opened in a new tab, since direct collections don’t take cards.

Environments: sandbox https://sandbox.users.niobi.co, production https://users.niobi.co. Separate credentials per environment (portal, Workspace → Integrations): client_id, sender (the integration title) and the secret key (senderKey). Staging uses Niobi’s sandbox with the sandbox credentials; automated tests use niobi-proxy’s mock (decided 2026-11-02).

Network: Niobi blocks any server IP that isn’t whitelisted, before checking the signature (403 restricted access). Our outbound calls leave from the droplet through niobi-proxy (decisions log, Niobi payments static IP handling); the droplet’s IP [redacted-ip] is whitelisted for sandbox and production (done 2026-11-02). Niobi’s webhook source IP is [redacted-ip] for both environments (from Niobi, 2026-11-02; not in the docs); the DigitalOcean firewall allows 443 only from it (decisions log, Niobi webhooks).

Every request carries a fresh signature; callbacks and responses carry Niobi’s.

  1. Build { client_id, sender, timestamp (Unix seconds), salt (random, ours), params: {…endpoint fields} } and add senderKey temporarily.
  2. Sort keys recursively, flatten to key=value joined by &, with dot notation for nesting (params.amount=10). Strings are trimmed, booleans become 1 or empty, null becomes empty, URLs are not URL-encoded.
  3. signature = SHA-256 (hex) of that string. Remove senderKey, add signature, send.
  4. Verifying a callback or response: take out signature, add senderKey, repeat steps 2–3, compare in constant time.

This is a keyed hash with the secret inside the hashed string, not a true HMAC, despite the docs’ wording; it’s what Niobi checks, so we match it exactly. Niobi documents no timestamp window, so replay protection is ours: the reference is idempotent (section 4) and the status query confirms every credit.

Test vector (from the docs, verified 2026-11-02): the docs’ worked example string hashes to 219d12d1b0b9c8e66e84ee08cefafe05eaad68745a9e82cbcbc153131333c640. P6.02’s tests use it. The docs’ Node.js implementation is the reference implementation.

  1. Customer, on top-up screen 17, enters credits, picks a payment method for their country (section 5) and gives the details that method needs (phone number for mobile money; name, plus ID number for Capitec, in South Africa). dashboard-api adds the vendor fee and creates a pending top-up. The total is a whole number of the currency, because Niobi’s amount is an integer: the fee rounds up to a whole unit.
  2. niobi-proxy starts the collection with amount (the total), currency, country_id, payment_method_type, mobile, the method’s extra fields, callback_url, and third_party_reference_1 = our top-up id (with is_third_party_reference_1_unique: 1).
  3. The customer authorises in the way the method requires, and screen 17 shows the matching view (section 5): “check your phone”, bank details to transfer to, an OTP box, or a hand-off to the provider’s page in a new tab.
  4. Niobi calls back (payment_step: 2; status success or failed; statusCode 000000 or 000005). niobi-proxy verifies the signature, pushes the event to the niobi-callbacks queue and answers 200 within a few seconds (P6.03).
  5. Before crediting, the consumer has niobi-proxy run the status query by our reference and checks: status success, currency equals the top-up’s, amount equals the top-up’s total. The callback carries no currency field, and Niobi recommends this “dual-layer confirmation”. The callback’s amount is what we requested; Niobi’s fee is a separate field (confirmed by Niobi, 2026-11-02), stored on the top-up for the margin report (47). Then the guarded credit runs as designed (credits only, never our fee; WHERE status = 'pending').
  6. Anything that doesn’t match (wrong currency, different amount, an unknown or already-closed top-up) is never credited automatically: it is recorded and shown on the admin Transactions screen (46).

A start that fails (Niobi answers status_code: "000005" with no payment_step: invalid number, unsupported method, limit) marks the top-up failed at once, with Niobi’s message shown to the customer.

Status codes: 000000 success and 000005 failed are final. 000001 pending, and 000006 timeout, are not: Niobi can still turn a timeout into success or failed later. Both keep the top-up pending, and the status-check job keeps asking at spaced intervals (never a tight loop). Pending past the threshold is flagged, never auto-failed (unchanged).

  • Our top-up id is third_party_reference_1, sent on the request and returned in the callback and the status query. The callback is matched by it; Niobi’s depositId / reference is stored too, with a unique index.
  • A repeated or resent callback (Niobi’s portal has a manual Resend Callback) is harmless: the credit is guarded by WHERE status = 'pending'.
  • Niobi does not reject duplicate collections (its uniqueness flags are enforced on payouts only), so a retried start could prompt the customer twice. niobi-proxy never retries a start blindly: on a timeout or network error it queries status by our reference first, and only starts again if Niobi has no record.

Methods from Niobi’s collections matrix; limits are Niobi’s “Deposit” limits (read 2026-11-02). The customer picks the method, so each method has its own range. They are configuration in the admin app (per currency and method), not code, since Niobi changes them.

Market Currency country_id Methods (payment_method_type) Customer flow Deposit range
Kenya KES 1 send money (M-Pesa), airtel Phone prompt 10–250,000 (M-Pesa range confirmed by the operator, 2026-11-02)
Benin XOF 2 mtn, moov Phone prompt 200–2,000,000
Côte d’Ivoire XOF 3 mtn, moov, Orange, Wave Phone prompt; Orange: OTP; Wave: provider page MTN, Orange 500–1,000,000; Moov 500–1,500,000; Wave 200–1,500,000
Cameroon XAF 4 mtn, Orange Phone prompt 500–500,000
DRC CDF 5 airtel, Orange, vodacom Phone prompt Airtel 500–6,250,000; Orange 500–1,000,000; Vodacom 1,000–1,000,000
Rwanda RWF 8 mtn, airtel Phone prompt MTN 100–2,000,000; Airtel 100–1,500,000
Senegal XOF 9 Orange, free, Wave Phone prompt; Orange: SMS shortcode, then USSD PIN; Wave: provider page 200–2,000,000
Tanzania TZS 10 airtel, halotel, tigo, vodacom Phone prompt 1,001–4,000,000
Uganda UGX 11 mtn, airtel Phone prompt 1,000–5,000,000
Zambia ZMW 12 mtn, zamtel, airtel Phone prompt 10–10,000
Sierra Leone SLE 13 Orange Phone prompt 5–15,000
South Africa ZAR 15 bank_eft, capitec Provider page; needs name; Capitec also the 13-digit ID number 10–1,000,000
Ghana GHS 16 mtn, At, vodafone Phone prompt 10–10,000
Nigeria NGN 17 virtual_account Bank transfer to a one-off account (needs first and last name) 100–10,000,000
Mali XOF 18* Orange, moov Phone prompt 500–500,000
Burkina Faso XOF 19* Orange, moov Phone prompt Orange 500–1,000,000; Moov 500–2,000,000
Togo XOF 20* moov, tmoney Phone prompt 200–2,000,000
Malawi MWK — — Not available (“upcoming” in Niobi’s docs) —

* Niobi’s payment-link page gives different IDs (Burkina Faso 18, Mali 24, Togo 28). We use the collections page’s, and confirm them in the sandbox before launch.

The customer’s country for a top-up is the org’s billing country (screen 21), which also decides which XOF or XAF market’s methods are offered.

One form, driven by the table above as data: amount (credits, with fee and total), method (the billing country’s list), and the method’s fields (phone number, prefilled from the profile where known). After the start, one of four views, each updating live from the top-up’s status:

  1. Phone prompt: “Approve the payment on your phone”; Senegal Orange adds the shortcode instruction.
  2. Bank transfer (Nigeria): the one-off account’s bank, number and name returned by Niobi, the exact amount, and a note that the balance updates when the transfer lands.
  3. OTP (Côte d’Ivoire Orange): a code box; the code goes to niobi-proxy’s OTP verify call.
  4. Provider page (Wave, South Africa): opens in a new tab; successful_url and failure_url return to the billing screen, which shows the top-up’s status.

Every view ends in the same states: pending, succeeded (balance updated), failed (Niobi’s reason, try again).

Only Niobi’s listed test phone numbers work in the sandbox; each gives a fixed outcome per country and network (success, failure, and no callback, stuck in submitted), which covers the status-check path. Côte d’Ivoire Orange’s sandbox OTP is 000000. niobi-proxy’s mock mirrors these outcomes for automated tests; staging calls the real sandbox.

Before launch, in the sandbox: one success, one failure and one no-callback case for each flow type (phone prompt, bank transfer, OTP, provider page), and one success each in Mali, Burkina Faso and Togo to confirm their country_ids.

For Niobi (support@niobi.co): None. Malawi is set aside for now (operator, 2026-11-02): no top-ups there at launch, and no follow-up with Niobi until it’s picked up again.

For the operator: production credentials before P9.14. Sandbox credentials are in Bitwarden (2026-11-02); they go into the niobi-proxy Kubernetes secret when P6.01 deploys it to staging.

Answered or done 2026-11-02: webhook source IP [redacted-ip]; callback amount is what we requested, with the fee separate; droplet IP whitelisted for sandbox and production; staging uses the sandbox. Framing the hosted checkout and passing a reference on payment links no longer matter (not used at launch).