Kolomoni Business Banking API integration (Nigeria agency banking & OpenFinance)

Feeds a large, underserved POS ecosystem

Nigeria remains the continent's largest agency banking market, with millions of neighbourhood POS agents handling cash-in / cash-out for customers who would otherwise have to queue at a branch. A Kolomoni agent processes dozens of daily transactions through a single MPOS, and every record (amount, channel, success rate, fee, commission) is a signal a partner can act on — from working-capital underwriting to cash-logistics planning.

Bill, telco & cable payments in one stream

The app bundles airtime recharge, data subscription, utility bill (DisCo) payments and cable TV renewals (DStv, GOtv, StarTimes). Normalising these into a single OpenData feed removes the need to integrate each biller one by one, and gives merchants a ready-to-query view of what their community is spending on outside pure banking.

Super-agent hierarchies & e-PIN automation

Super agents onboard a minimum of 10 sub-agents and distribute MPOS terminals (₦15,000 standard, ~₦10,000 under super-agent pricing). Exposing this hierarchy via API unlocks sub-agent league tables, tiered commissions, fraud scoring and automated e-PIN replenishment — none of which is practical to run manually from the bare mobile app.

1. Agent authentication & session

Mirrors the app's login flow (phone / BVN-tagged account, PIN, device binding) and returns OAuth-style access and refresh tokens. Use case: sign an agent in from a web console so a super-agent can monitor their fleet without handing over the phone.

2. Transaction history & statement API

Paginated endpoint for every MPOS transaction: cash withdrawal, deposit, transfer, bill payment, airtime / data, cable TV. Fields: rrn, channel, masked_pan, biller_id, fee, commission, status. Use case: daily reconciliation into Sage, Zoho Books or a custom ledger.

3. Instant settlement & commission ledger

Webhook and pull API for instant-settlement events, including the 1% airtime chargeback and ~₦50 cable TV cashback. Use case: a super-agent dashboard that shows real-time gross commission per sub-agent and triggers payout rules.

4. e-PIN & voucher generation

Structured e-PIN objects (telco, value, serial, PIN, expiry) synchronised out of the app so a biller-agnostic printing or messaging stack can take over. Use case: auto-SMS the generated pin to a walk-in customer and store the transaction for audit.

5. MPOS device & success-rate telemetry

The app exposes a "Live Card Transaction Success Rate" — we expose it as a numeric stream per terminal, merged with failure reasons (network, do-not-honour, insufficient funds). Use case: SRE-style alerting when a terminal's success rate drops below a threshold.

6. Utility bill & cable TV connectors

Normalised responses for DisCo (EKEDC, IKEDC, AEDC etc.) token purchases, DStv / GOtv / StarTimes renewals and water-board bills. Use case: embed "Pay your bill" in a partner super-app that re-uses Kolomoni rails rather than integrating each biller itself.

Scenario 1 — Super-agent back office

Business context: a super-agent with 40 Kolomoni sub-agents needs a single web portal to watch fleet performance. Data: transaction history API + instant settlement feed + success-rate telemetry. OpenData mapping: these endpoints slot directly into the CBN Open Banking "Account Information" and "Transaction" product families, so the same portal can later merge in Moniepoint or OPay feeds without re-architecting.

Scenario 2 — SME accounting & tax

Business context: an SME uses Kolomoni to collect cash from customers and pay suppliers. Data: statement query API (date range + channel filter) pushed nightly to Zoho Books / QuickBooks / Sage via CSV + JSON webhook. OpenData mapping: the same contract used for OpenBanking "Statement Download" — debit, credit, balance_after — so an accountant's plug-in works against Kolomoni just as it would against a regulated bank.

Scenario 3 — Agent lending / float financing

Business context: a lender wants to advance daily float to top Kolomoni agents. Data: 90-day rolling transaction count, commission earned, average ticket size, fraud flags, success-rate stability. OpenData mapping: an OpenFinance-style credit decisioning feed; the lender receives a scoring input without seeing the raw PII of end customers.

Scenario 4 — Biller / telco partner reporting

Business context: a DisCo or telco wants aggregated volume routed through Kolomoni agents per region. Data: utility / airtime endpoints grouped by biller_id and LGA. OpenData mapping: OpenData "aggregate" datasets; no personal data, just commercial volume and unit price — safe to share under a B2B data-sharing agreement.

Scenario 5 — Compliance & AML case-file

Business context: a compliance officer needs to investigate a flagged cash deposit chain. Data: transaction history + agent profile + e-PIN voucher log stitched on a session and RRN basis, plus the original MPOS receipt image where available. OpenData mapping: an auditable, append-only replica of the regulated record — the same pattern NFIU expects when an EFCC / CBN enquiry lands.

Agent login & token refresh

POST /api/v1/kolomoni/auth/login
Content-Type: application/json

{
  "agent_phone": "+2348030000000",
  "pin": "******",
  "device_id": "MPOS-NG-0001-SN98823",
  "mfa_token": "142889"
}

// 200 OK
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "v1.rt.d1c0...",
  "expires_in": 1800,
  "agent_id": "KLM-AG-44127",
  "super_agent_id": "KLM-SA-0088",
  "kyc": { "bvn_verified": true, "tier": 3 }
}

Statement query API

POST /api/v1/kolomoni/statement
Authorization: Bearer <ACCESS_TOKEN>

{
  "agent_id": "KLM-AG-44127",
  "from": "2026-03-01",
  "to":   "2026-03-31",
  "channels": ["CASH_WITHDRAWAL","TRANSFER","AIRTIME","CABLE_TV"],
  "page": 1,
  "page_size": 100
}

// 200 OK (excerpt)
{
  "total": 1842,
  "records": [{
    "rrn": "603421999812",
    "timestamp": "2026-03-14T11:42:08+01:00",
    "channel": "CASH_WITHDRAWAL",
    "amount_ngn": 20000.00,
    "fee_ngn": 100.00,
    "commission_ngn": 70.00,
    "status": "SUCCESS",
    "terminal_id": "MPOS-NG-0001-SN98823",
    "masked_pan": "506099******4411"
  }]
}

Settlement webhook (server → client)

POST https://your-erp.example.com/kolomoni/hook
X-Kolomoni-Signature: sha256=9e2c...
Content-Type: application/json

{
  "event": "settlement.credited",
  "agent_id": "KLM-AG-44127",
  "batch_id": "STL-2026-03-14-0007",
  "gross_ngn": 184500.00,
  "commission_ngn": 4320.50,
  "net_ngn":  180179.50,
  "settled_at": "2026-03-14T23:55:10+01:00"
}

// Verify: HMAC-SHA256 over raw body using shared secret
// Retry: exponential backoff up to 24h on non-2xx

Error handling & idempotency

All write endpoints accept an Idempotency-Key header so that agents on flaky networks can safely retry. Standardised error envelope:

{
  "error": {
    "code": "NIP_TIMEOUT",
    "http_status": 504,
    "message": "NIBSS Instant Payment upstream timed out",
    "retryable": true,
    "trace_id": "01J4Q..."
  }
}

Deliverables checklist

• OpenAPI 3.1 / Swagger specification for every exposed endpoint
• Protocol and auth-flow report (OAuth-style tokens, device binding, MPOS pairing)
• Runnable source for login, statement, settlement and webhook APIs (Python / Node.js / Go)
• Unit and integration tests, plus a replayable sandbox fixture set
• ERP connector examples (Zoho Books, QuickBooks, Sage) + CSV / Excel export templates
• Compliance guidance aligned to CBN Open Banking, NDPA 2023 and NFIU expectations

Engagement models

Source code delivery from $300: we hand over runnable API source, docs and tests; you pay after delivery upon satisfaction. Good for teams that want to self-host and own the code.

Pay-per-call hosted API: point your backend at our managed endpoint and pay only per successful call — zero upfront cost. Good for MVPs, one-off data exports and teams that prefer usage-based pricing.

Engagement workflow

1. Scope confirmation — which Kolomoni modules (statement, settlement, e-PIN, utility), volumes, target ERP.
2. Authorised protocol analysis & API design — typically 2–5 business days.
3. Build & internal validation against sandbox agents — 3–8 business days.
4. Documentation, sample clients and compliance brief — 1–2 business days.
5. First usable delivery within 5–15 business days; third-party KYC / processor approvals may extend.

FAQ

What do you need from me?

How long does delivery take?

How do you handle compliance?

Can you combine Kolomoni with Moniepoint, OPay or PalmPay data?

About us

We are an independent technical studio focused on App interface integration and authorised API integration. Our engineers come from retail banking, payment-switch operators, mobile-app protocol analysis and cloud platforms, and have shipped financial APIs across Africa, South Asia, the EU and the Middle East. We know NIBSS, NIP, CBN Open Banking, PCI-DSS and NDPA constraints, and we build end-to-end pipelines that stand up to both compliance reviews and production traffic.

• Agency banking, digital wallets, micro-lending and cross-border clearing
• Protocol analysis, enterprise API gateways and security reviews
• Python / Node.js / Go / Kotlin SDKs and replayable test harnesses
• Source code delivery from $300 — runnable code plus docs, pay on satisfaction
• Pay-per-call hosted API — usage-based, no upfront fee

Contact

Ready to brief us on your Kolomoni Business Banking integration? Share your target modules (statement, settlement, e-PIN, utility), agent volume and preferred engagement model, and we will come back with a scoped quote.

Open contact page