Reaching into Nomba's merchant rails and virtual-account flows

Behind the consumer-facing Nomba app sit two business-side systems an integrator usually wants to reach: the merchant ledger that drives the 300,000-plus POS terminals Nomba says it now operates after the Apple Pay rollout, and the virtual-account fabric that Nomba itself reports carries roughly 75% of API-platform volume. The same mobile app also covers personal balances, bill-pay, airtime top-ups, and Safe Stash and Flexible Savings. That mix — consumer wallet on one side, merchant rails on the other — is what makes the integration interesting and what shapes the route.

Bottom line: most of what an integrator needs is reachable through Nomba's own developer endpoints under a consented merchant authorization, with protocol analysis filling the gaps for screens that the developer surfaces do not mirror one-to-one. The page below maps that out.

Where the data lives inside the app

The Nomba app is two products sharing a login — a personal money app and a merchant operations console — and the data each holds is shaped accordingly.

Routes that actually carry it

Three routes apply on a typical Nomba build. Pick by what is reachable, how durable the connection is, and how much of the merchant's day the integration has to keep up with.

1 · Consented developer API access

Nomba publishes a developer surface at developer.nomba.com covering virtual accounts, transfers, payouts, checkout, and a webhook layer; authentication is OAuth2 (client-credentials or PKCE), and the developer documentation describes a signed webhook contract for inbound events. Under a merchant authorization, this is the spine of the build for businesses: low-latency reads, real-time inbound credit events, and the cross-border payout endpoints introduced with the Global Payout product. Access keys, the webhook URL and signing key are arranged with the merchant during onboarding — we handle that step rather than asking the customer to land in the dashboard first.

2 · Authorized protocol analysis of the mobile app's traffic

For surfaces that the developer endpoints do not mirror one-for-one — the consumer side of the app, bill-pay receipts in the format the user sees, the savings pots — interface integration runs against the mobile traffic itself under the user's written consent. This is documented protocol analysis: capture the request/response pairs the app uses against Nomba's backend, document the auth chain, and turn the relevant calls into a maintained client. It is the slower route to set up, durable enough in practice if maintenance is wired in (see the engineering notes below).

3 · Native export, where it exists

For merchants who only need periodic statements, the Nomba dashboard exports a CSV per account and a printed receipt per POS transaction. This route does not scale to real-time, but for tax pulls and quarterly reconciliations it is fast to deploy and asks nothing of the runtime — useful as a fallback or a parallel sanity check alongside route 1.

On a merchant build the consented developer route carries the bulk of the work, with protocol analysis kept in reserve for whichever screen a particular merchant raises. On a personal-finance aggregation, that order inverts — protocol analysis does most of the lifting and dashboard CSV exports act as the safety net.

What lands on your side

The deliverable is a working integration, not a report. For a typical Nomba engagement that means:

• An OpenAPI specification covering the endpoints we actually call on this merchant's footprint — virtual accounts, transfer creation, webhook events, payout creation where global payout is in scope.
• A protocol and auth-flow note describing the OAuth2 token cycle (Nomba accepts client-credentials and PKCE), the accountId header pattern observed during the build, and the webhook signature scheme.
• Runnable source code in Python and Node.js for the working endpoints: list virtual-account transactions, fetch a single virtual account, post a transfer, verify a webhook payload, paginate a settlement window.
• An automated test pack against a sandbox tenant and a recorded fixture pack for offline runs, so a change in the developer surface is caught the same day it ships.
• Interface documentation written for your own engineers — every field, every error code, every retry rule — and the data-retention and consent-revocation guidance that goes with it.

A reference snippet

Illustrative shapes from the build; exact tenant identifiers and field names are confirmed against the live response before handover.

# Pull a virtual-account transaction window from Nomba and verify a webhook
import hmac, hashlib, time, httpx

ACCESS = oauth2_client_credentials(
    client_id=NOMBA_CLIENT_ID,
    client_secret=NOMBA_CLIENT_SECRET,
    scope="virtual-accounts transfers",
)

def list_va_transactions(account_id: str, since_ms: int):
    r = httpx.get(
        f"https://api.nomba.com/v1/accounts/virtual/{account_id}/transactions",
        params={"from": since_ms, "to": int(time.time() * 1000), "limit": 100},
        headers={
            "Authorization": f"Bearer {ACCESS}",
            "accountId": NOMBA_ACCOUNT_ID,  # tenant header observed on Nomba calls
        },
        timeout=15.0,
    )
    r.raise_for_status()
    return r.json().get("data", [])

def verify_event(body: bytes, signature_header: str, signing_key: str) -> bool:
    # Nomba's webhook guide sends a signature header per event; verify before trust
    digest = hmac.new(signing_key.encode(), body, hashlib.sha512).hexdigest()
    return hmac.compare_digest(digest, signature_header)

Engineering notes from working this kind of project

A few things that come up repeatedly on Nomba integrations and that we handle as part of the build, not as preconditions on the customer.

Reconciliation lives at the virtual-account layer, not the merchant account

Nomba's own messaging puts virtual accounts at around three-quarters of API platform volume, and that holds in practice — most inbound money lands first against a per-customer or per-invoice virtual account and only then sweeps to the main merchant balance. We design the consumer-side ledger so the row key is the virtual-account transaction identifier (the thing the webhook also carries), not the parent settlement, so chargebacks and replays do not double-count when the sweep arrives later in the day.

Channel separation matters more after the Apple Pay rollout

Since Nomba's Apple Pay rollout across its POS terminals announced in December 2025, the same merchant ledger now mixes card-present, contactless Apple Pay, bank-transfer-in and QR rows. We map the channel marker explicitly in the normalized output so fee analysis and dispute flow stay correct — a single column instead of an inferred join.

Webhook plus pull, never webhook alone

Webhook delivery in any Nigerian fintech context occasionally misses on first attempt — carrier-grade NAT, brief edge outages, the usual. The integration is built so a webhook event and a later replay-by-window pull agree on the same row keys, and the pull is a safety net rather than a separate ledger. This is the bit of plumbing that keeps the merchant's books matching the bank.

Front-end drift on the consumer side

For the personal app — savings pots, bill-pay receipt formats — front-end drift is a maintenance budget item, not an exception. A scheduled re-check sits in the test suite on a cadence agreed with the merchant, so a renamed field surfaces as a failing fixture before it surfaces as a missing column downstream.

Consent and the Nigerian rulebook

Nigeria sits in an unusual spot. The CBN issued the Regulatory Framework for Open Banking in 2021 and the Operational Guidelines in March 2023, making it the first African country with a clearly stipulated open banking regime — registry, participant licensing, customer consent that must be informed and revocable, and a 72-hour breach reporting window. National go-live was approved for August 2025 and did not happen; the implementation workstreams handed deliverables to the CBN in September 2025 and the industry now expects a phased start.

For a project running today, the dependable basis is the merchant's own authorization to access their Nomba data, alongside a signed scope and consent record. We log every call, hold only the fields named in the scope, NDA where the merchant requires it, and run the build as a regulated-participant-ready shape so that when the CBN registry opens, the same integration translates into an AISP flow with a narrow change surface rather than a rewrite. Where personal data is involved, the Nigeria Data Protection Act sets the floor and we work to it.

Adjacent Nigerian apps an integrator usually meets

A merchant rarely sits on Nomba alone, and a personal-finance pull rarely sees only one wallet. Plain neighbours, by what they actually hold:

• Moniepoint — agent banking and POS terminals at scale; the merchant ledger overlaps strongly with Nomba's and is the most common second source in reconciliation work.
• OPay — mobile money plus a large agent network; consumer wallet and bills history sit close to the Nomba personal side.
• PalmPay — wallet plus agent network across hundreds of thousands of points; the wallet ledger reconciles in the same shape.
• Flutterwave — payment processing and online checkout; sits alongside Nomba's payout side for cross-border flows.
• Paystack — online checkout and recurring billing; merchants typically hold both Nomba (in-person) and Paystack (online) and want one view across them.
• Kuda Business — digital business bank; statement and transfer endpoints are routinely pulled in the same aggregation as Nomba.
• Kippa — bookkeeping for small merchants; downstream of Nomba, ingesting transaction feeds rather than producing them.

Unified integration treats each provider as its own ledger source, normalizes the channel and amount fields, and resolves cross-provider duplicates so a card route on one and a settlement on another do not show up as two transactions.

Integrator questions, answered for this app

Can the Nomba virtual-account stream be reconciled per terminal or per merchant?

Yes, in practice. Virtual accounts in Nomba are issued per merchant and, when scoped that way, per till or terminal, and the transaction list carries the account identifier on every event. We design the consumer end so a webhook delivery and a later replay-by-window pull agree on the same row keys, which is what lets reconciliation hold up across reprints and disputes.

How does the pending Nigerian open banking go-live affect a Nomba project started today?

The CBN's August 2025 launch date did not materialize and the industry is now waiting on a phased go-live; the implementation workstreams handed deliverables to the CBN in September 2025. For a project starting today, that means the build sits on Nomba's own developer endpoints and on a consented authorization with the merchant, not on a national open banking rail. When the registry opens, the same scoping translates into a regulated AISP flow with a narrower change surface.

What changes for a merchant who runs Nomba alongside Moniepoint, OPay, or Paystack?

Different shapes, the same job. Moniepoint and OPay sit closer to Nomba on agent and in-person flows, while Paystack and Flutterwave cover the online checkout side. A unified pull treats each provider as a separate ledger source, normalizes amount and channel fields, and resolves the same payment across two ledgers when a card transaction routes through one and settles through another.

Does the Apple Pay rollout on Nomba terminals open anything new for an integrator?

For data work, not really new fields — settlement still lands in the merchant's Nomba account — but the channel marker on the transaction lets you separate contactless Apple Pay volume from card-present and bank-transfer rows. That separation matters for fee analysis and for any chargeback flow you build downstream.

What we checked while writing this

Sources opened for the merchant rails, the developer surface, and the regulatory state, with the dates that matter on each one:

• Nomba developer documentation — virtual accounts, transfers, webhooks: developer.nomba.com.
• Nomba Global Payout API launch coverage on cross-border corridors and settlement windows: Techpoint.
• Apple Pay rollout across Nomba's POS terminals, December 2025: TechCabal.
• CBN Operational Guidelines for Open Banking, March 2023: cbn.gov.ng (PDF); status of the missed August 2025 go-live: Technext.

Reviewed 2026-05-20 by the OpenBanking Studio integration desk.

Working with us

Delivery on this kind of build runs on a 1–2 week cycle. The source-code package starts at $300 and is billed only after handover, once the merchant-ledger pull is running on your side; the hosted-API option carries no upfront fee — you call our endpoints and pay per call. Send the app name and what you actually need to /contact.html and the next step is on us — access, sandbox, and the compliance paperwork are arranged with the merchant as part of scoping, not something to clear before we start.

Nomba — the public facts

Nomba (formerly Kudi) is a Lagos-based fintech serving Nigerian individuals and businesses. Its Play Store listing reports a single mobile app covering personal accounts and business accounts, with bill payments, airtime and data top-ups, Safe Stash (advertised at up to 20% annual interest) and Flexible Savings, and send/receive across Nigerian banks. On the merchant side, Nomba operates the POS terminal estate that reached 300,000-plus units around the December 2025 Apple Pay integration, alongside a developer platform documented at developer.nomba.com — virtual accounts, transfers, checkout, and a recently launched Global Payout API covering UK Faster Payments, SEPA, Canada Interac, and DRC Mobile Money. The operator is licensed by the Central Bank of Nigeria as a mobile money operator and is NDIC-insured.