Skip to content

InstaPayBill API

Programmable bill payments for Nigeria — airtime, data, electricity, cable TV, education result-checker PINs and Startimes — behind one REST API.

This is the reference for agents, developers and automated systems that integrate with the InstaPayBill payments backend. It documents every agent-facing endpoint, the exact request and response shapes, and how the backend actually works under the hood.
Base URL https://sandbox.instapaybill.com
API prefix /api/v1
Sandbox base https://sandbox.instapaybill.com/api/v1/sandbox
Live base https://api.instapaybill.com/api/v1
Content type application/json
Live auth header Authorization: Bearer sk_live_…
Sandbox auth header Authorization: Bearer sk_test_… (sandbox routes only)
Currency Nigerian Naira (₦)

Test against the sandbox host. sandbox.instapaybill.com is the simulated environment for developer testing at /api/v1/sandbox/*. Use api.instapaybill.com/api/v1/* with a Live key for real payments. staging-api.instapaybill.com is reserved for internal QA.

What you can do with it

Service Endpoint What it does
Airtime POST /api/v1/airtime/buy Top up any Nigerian mobile number on MTN, Glo, Airtel or 9mobile
Data POST /api/v1/data/buy Activate a data bundle from the live plan catalogue
Electricity POST /api/v1/electricity/buy Buy prepaid units and receive a meter token
Cable TV POST /api/v1/cables/buy Renew or subscribe to DStv, GOtv, ShowMax, Startimes
Education POST /api/v1/education/buy Generate WAEC, JAMB and other result-checker PINs
Transactions GET /api/v1/transactions List, resolve and reconcile your transactions
Wallet GET /api/v1/wallet/manage-wallet-balance Check spendable balance and commission
Webhooks x-webhook-signature Receive signed async settlement notifications

Start here

  • :material-rocket-launch: Quickstart

    Make your first purchase in five minutes. Sandbox key, curl call, response walkthrough.

  • :material-key: Authentication

    Sandbox and Live keys, session JWTs, and developer portal SSO.

  • :material-alert-circle: Errors & Status Codes

    The 300 vs 400 distinction that decides whether you retry or stop.

Two ways to integrate

Authenticate with an API key and call the purchase endpoints directly.

curl -X POST https://api.instapaybill.com/api/v1/airtime/buy \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-integration/1.0" \
  -d '{"phone":"08012345678","amount":500,"network":"MTN","apiRefId":"order-1001"}'

Production keys live in your server, are tied to an approved agent account, and draw down a real wallet balance.

2. Sandbox (free, no money moves)

Every sandbox endpoint is a simulation — it never reaches a provider, never charges a wallet, and returns realistic response shapes so you can build against them. The sandbox key is available to every approved agent from the developer portal.

curl -X POST https://sandbox.instapaybill.com/api/v1/sandbox/airtime \
  -H "Authorization: Bearer $IPB_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"08012345678","amount":500,"network":"MTN","scenario":"success"}'

The sandbox lets you force outcomes with the scenario field (success, failure, pending) — see Sandbox.

Conventions used in this documentation

  • Field names are shown exactly as they appear in the JSON payload. The casing is inconsistent in places (for example apiRefId on the request but apiRefID on the resolve query) — that is the real behaviour, not a typo.
  • Status codes follow the platform convention documented in Errors & Status Codes: 200 success, 300 retryable, 400 permanent failure, 403 not permitted.
  • Source — every claim here was read out of the running backend (InstaPayBill-api): Routes/, Controllers/, Services/, Middlewares/, Models/ and utils/. Where behaviour is conditional on a live configuration flag (kill switches, feature flags, provider health), the condition is called out explicitly.
  • Internal-only endpoints (admin panels, CRM, cron triggers, risk scoring) are not part of the public integration surface.

Not an agent yet?

Production API keys are issued to approved InstaPayBill agents. Apply from your profile settings. Sandbox access requires an approved agent account too — the portal never creates standalone accounts.

For AI agents

Two machine-readable entry points are published alongside these docs:

File What it is
/docs/llms.txt A manifest of every page with a one-line summary. Fetch this first, then request only the pages you need.
/docs/llms-full.txt The entire reference concatenated into one file. Fetch this if you want everything in a single request.

The llms.txt format is described at llmstxt.org.

If you are driving the API from an agent, the shortest useful path is:

  1. getting-started.md — the auth header and the request shape.
  2. errors.md — the 300 vs 400 rule, which determines whether to retry.
  3. The service page you need — api/airtime.md, api/data.md, api/electricity.md, api/cables.md or api/education.md.
  4. api/webhooks.md — if you want the final outcome pushed to you.

Two things to get right

  • Send a User-Agent header. Without one the API returns HTTP 500.
  • Never retry a 300 immediately. It means the provider has not confirmed yet. Wait for the webhook, or poll resolve after about a minute. See errors.md.