Syncing Nomba balances, transfers and settlement events into your own stack

Nomba runs money for small and mid-size Nigerian merchants — card, bank transfer, USSD and QR collections through its terminals, with automated settlement back to a bank account. Formerly branded Kudi (per published reviews), it now describes a network in the hundreds of thousands of merchant locations. For anyone building bookkeeping, lending, treasury or analytics on top of that, the data worth reaching is the per-account ledger: what came in, what went out, what settled, and when. This brief maps that data, the authorized way to read it, and the working code we hand over.

What sits behind a Nomba account

These are the surfaces a Nomba account actually exposes to its holder. Granularity below is what an integrator can realistically pull per call or per event.

Authorized routes to the data

Two of these apply to almost every Nomba engagement; the other two are situational. We arrange access and onboarding with you as part of the build.

Interface integration on the merchant's credentials

For a business account, the cleanest path is the merchant's own OAuth client-credentials. Nomba's documented flow issues a short-lived access token (30 minutes, per its developer docs) exchangeable via a refresh token, and that scope reaches transactions, transfers, virtual accounts and settlements. Durable, well-defined, and it runs against a sandbox or a consenting live account that we set up with you.

Protocol analysis of the authenticated app traffic

Where a surface the holder sees in the app is needed but is not cleanly exposed for server use, we analyse the authenticated traffic under the account holder's authorization and implement it directly. This reaches anything the user can see. It needs a re-check when the app changes, which we build into maintenance.

Regulated open-banking consent

Nigeria's framework is real but not yet generally live. As the CBN's Open Banking Registry channel opens, a consent-based read becomes the most durable option, and we design the pipeline so it can move onto that rail without a rewrite.

Native export

Statements and invoice exports cover one-off or low-frequency needs without any live connection. A fallback, not a feed.

For most builds we run the first route as the backbone and fold in protocol analysis only for the surfaces it cannot reach — that keeps the integration on documented, token-based access while still covering what the merchant can see in the app.

Sample integration against a real surface

Token acquisition follows Nomba's documented client-credentials grant; the event side is built around a queue so a consumer that was offline replays from where it stopped. Field names below are illustrative and pinned to the live response shapes during the build.

# 1. Obtain a short-lived access token (client-credentials grant)
POST https://api.nomba.com/v1/auth/token/issue
  { "grant_type": "client_credentials",
    "client_id": CLIENT_ID, "client_secret": CLIENT_SECRET }
-> { "access_token": "...", "expires_in": 1800, "refresh_token": "..." }
# token lives ~30 min; we refresh ahead of the deadline so the puller never stalls mid-run

# 2. Consume transfer / charge events off our queue, not the socket
def on_event(evt):
    cursor = store.last_offset(account_id)
    if evt.offset <= cursor:          # already processed; drop the duplicate
        return ack(evt)
    record = normalize(evt)           # card / transfer / USSD -> one schema
    ledger.upsert(record, key=evt.reference)   # reference dedupes a replayed event
    store.commit_offset(account_id, evt.offset)
    ack(evt)

# 3. Close the gap the push channel can miss
GET /v1/accounts/{account_id}/transactions?since={cursor}&limit=100
  Authorization: Bearer ACCESS_TOKEN
# nightly sweep reconciles the feed against the authoritative list
      

What you get

The headline deliverable is code that runs, not a document set:

• Runnable source for the key surfaces — a Python or Node.js client that authenticates, pulls transactions, transfers, balances and settlements, and normalizes them.
• A webhook consumer with the replay and offset handling shown above, so Nomba event callbacks survive restarts and deploys.
• An automated test harness covering token refresh, duplicate events, and the reconciliation sweep — a broken surface shows up in the suite before it reaches your data.
• A batch-versus-realtime sync design: where the live event channel feeds you, and where a scheduled pull backstops it.
• An OpenAPI/Swagger description of the surfaces we wire up, and a protocol and auth-flow report (the OAuth token and refresh chain as it behaves for this account).
• Interface documentation and data-retention guidance.

Engineering notes specific to Nomba

Two things shape every Nomba build, and we handle both rather than hand them back to you as conditions.

First, multi-currency. Nomba carries NGN plus USD, GBP and EUR wallets, and its Global Payout flow (launched March 2026, per trade press) moves money across markets. We model each currency as its own balance line and keep source and destination currency on every cross-border record, so reconciliation ties out in naira and in the settlement currency rather than silently netting them.

Second, the acquiring mix. The same merchant takes card, bank transfer, USSD and QR — including offline-captured payments that settle later. We design the ingestion so a payment authorized at the terminal and a settlement that lands days afterward are linked on one record, and the freshness window is set so a late settlement is reconciled rather than treated as a new event. Access to a sandbox or a consenting account is arranged with you during onboarding; the build runs against that.

Consent and the Nigerian regime

Nomba operates under Nigerian financial regulation, and the relevant data-sharing framework is the CBN's Operational Guidelines for Open Banking, published March 2023 (per the CBN). They establish an Open Banking Registry, tiered participant onboarding, token-based API security and breach reporting to the CBN within roughly 72 hours. A nationwide go-live was signalled for 2025 and has been pushed; a phased start has been expected into 2026, so the regulated consent channel is best treated as forthcoming rather than something to depend on today. Until it is live, our basis is the account holder's own documented authorization, consistent with the NDPR: clear, recorded, revocable consent, data minimized to what the integration needs, access logged, and an NDA where the engagement calls for one.

Where teams use this

• A lender scoring a merchant pulls the transaction history and settlement cadence to size a working-capital offer.
• An accounting tool keeps a merchant's books current by ingesting transfers and POS activity nightly and on event.
• A marketplace reconciles payouts to vendors against Nomba settlement batches instead of chasing them by hand.
• A treasury dashboard reads the NGN, USD, GBP and EUR wallet balances side by side for a multi-account operator.

Engagement

A first working Nomba integration lands inside one to two weeks. From there you pick how it is delivered. Source-code delivery starts at $300: you get the runnable client, the webhook consumer, tests and documentation as a handover, and you pay after delivery once it does what you needed. Or run it as a pay-per-call hosted API — we host the integration, you call our endpoints and pay only for the calls, with nothing upfront. Tell us the app and what you want out of its data, and we handle the access, onboarding and compliance with you. Start the conversation on the contact page.

Interface evidence

Screens from the Play listing, for reference to the surfaces above.

Sources and review

Checked in May 2026 against the Play listing for com.nomba.business, Nomba's developer documentation for the auth and transaction surfaces, the CBN's open-banking guidance, and trade coverage of the Global Payout launch. Where a figure could not be independently confirmed — merchant counts, network size — it is attributed to the company's own description and not asserted as audited fact.

• Nomba Developers — authentication (client-credentials, token lifetime)
• CBN — Operational Guidelines for Open Banking in Nigeria (2023)
• Google Play — Nomba - Mobile Banking listing
• Techpoint — Nomba Global Payout API launch

OpenFinance Lab · engineering notes, May 2026.

Related apps in the same space

A unified integration usually spans several of these; each holds comparable per-account financial data.

• Moniepoint — agency banking and merchant accounts with settlement and POS records across a large terminal base.
• OPay — wallets, transfers and bill payments with a heavy personal-finance footprint.
• PalmPay — mobile wallet with transfers, bills and a transaction ledger per user.
• Paga — transfers and bill pay aimed at everyday and informal-economy use.
• Flutterwave — payment processing and collections with transaction and settlement data for businesses.
• Paystack — online payment acceptance with charges, transfers and settlement records.
• Kuda — a digital bank holding balances, statements and transfers per account.
• Baxi — agent-banking and bill-payment activity at the terminal level.

Questions integrators ask

How do you keep a Nomba transaction feed in sync without dropping events?

We treat Nomba's webhook callbacks as the live edge and the transaction list as the source of truth. Events land on a queue, get acknowledged fast, and are replayed from a stored cursor when a consumer was down — so a settlement that fired during a deploy is still picked up on the next pass. Periodic reconciliation against the transaction history closes any gap the push channel missed.

For a Nomba business account, which data can a third party actually read?

With the merchant's own authorization we reach the surfaces the app and Nomba's developer documentation expose: per-currency balances, the transaction history, transfers in and out, virtual-account collection records, automated settlement records, invoices, and POS terminal activity. We map each to a normalized schema so a card payment, a bank transfer and a USSD collection read the same way downstream.

Does Nigeria's open banking regime cover Nomba yet?

The CBN published Operational Guidelines for Open Banking in March 2023 and a phased go-live has been signalled but repeatedly pushed; as of this writing the consent-based regulated channel is not yet generally live. Until it is, the dependable basis is the account holder's own authorization, with consent records and NDPR-aligned data handling. We design the integration so it can switch onto the regulated consent flow once the Open Banking Registry channel is available.

Nomba moves money in NGN, USD, GBP and EUR — how do you handle multi-currency balances?

Each currency wallet is modelled as its own balance line keyed to the account, so totals never collapse into a single misleading figure. Cross-border payout records from Nomba's Global Payout flow carry their source and destination currency, and we keep both on the normalized record so reconciliation in naira and in the settlement currency both tie out.