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.
1. What we use
Section titled “1. What we use”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).
2. Signing
Section titled “2. Signing”Every request carries a fresh signature; callbacks and responses carry Niobi’s.
- Build
{ client_id, sender, timestamp (Unix seconds), salt (random, ours), params: {…endpoint fields} }and addsenderKeytemporarily. - Sort keys recursively, flatten to
key=valuejoined by&, with dot notation for nesting (params.amount=10). Strings are trimmed, booleans become1or empty, null becomes empty, URLs are not URL-encoded. signature= SHA-256 (hex) of that string. RemovesenderKey, addsignature, send.- Verifying a callback or response: take out
signature, addsenderKey, 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.
3. The top-up flow
Section titled “3. The top-up flow”- 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-apiadds the vendor fee and creates apendingtop-up. The total is a whole number of the currency, because Niobi’samountis an integer: the fee rounds up to a whole unit. niobi-proxystarts the collection withamount(the total),currency,country_id,payment_method_type,mobile, the method’s extra fields,callback_url, andthird_party_reference_1= our top-up id (withis_third_party_reference_1_unique: 1).- 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.
- Niobi calls back (
payment_step: 2;statussuccessorfailed;statusCode000000or000005).niobi-proxyverifies the signature, pushes the event to theniobi-callbacksqueue and answers200within a few seconds (P6.03). - Before crediting, the consumer has
niobi-proxyrun the status query by our reference and checks: statussuccess, 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’samountis 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'). - 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).
4. Matching and idempotency
Section titled “4. Matching and idempotency”- 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’sdepositId/referenceis 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-proxynever 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.
5. Markets, methods and limits
Section titled “5. Markets, methods and limits”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.
6. The top-up screen (17)
Section titled “6. The top-up screen (17)”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:
- Phone prompt: “Approve the payment on your phone”; Senegal Orange adds the shortcode instruction.
- 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.
- OTP (Côte d’Ivoire Orange): a code box; the code goes to
niobi-proxy’s OTP verify call. - Provider page (Wave, South Africa): opens in a new tab;
successful_urlandfailure_urlreturn 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).
7. Sandbox and testing
Section titled “7. Sandbox and testing”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.
8. Open items
Section titled “8. Open items”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).