# InstaPayBill API

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

Base URL: `https://sandbox.instapaybill.com`  ·  Prefix: `/api/v1`

Auth: `Authorization: Bearer sk_live_…` (or `sk_test_…`). A `User-Agent` header is required.

Most requests are `Content-Type: application/json`.

## Docs
- [index](https://developer.instapaybill.com/docs/): Overview of the InstaPayBill payments API and how to integrate.
- [getting-started](https://developer.instapaybill.com/docs/getting-started/): Five-minute quickstart: get a key, make a purchase, handle the failure modes.
- [authentication](https://developer.instapaybill.com/docs/authentication/): API keys, the sk_test_/sk_live_ split, session JWTs, the agent key, and which endpoints accept which credential.
- [errors](https://developer.instapaybill.com/docs/errors/): The error envelope, what each status code means, and the 300-vs-400 retry rule.
- [rate-limits](https://developer.instapaybill.com/docs/rate-limits/): Per-group limits, the 1-request-per-5-seconds purchase cap, and the duplicate-request guard.
- [overview](https://developer.instapaybill.com/docs/api/overview/): Endpoint map, common request fields, the response envelope, and reference values.
- [airtime](https://developer.instapaybill.com/docs/api/airtime/): Airtime purchase endpoint, request fields, response shapes, and the guards that apply.
- [data](https://developer.instapaybill.com/docs/api/data/): Data bundle purchase and the data plan catalogue endpoints.
- [electricity](https://developer.instapaybill.com/docs/api/electricity/): Electricity meter validation and prepaid purchase, including the meter token.
- [cables](https://developer.instapaybill.com/docs/api/cables/): Cable TV smart-card validation and purchase for DStv, GOtv, ShowMax and Startimes.
- [education](https://developer.instapaybill.com/docs/api/education/): Result-checker PIN generation for WAEC, JAMB and other exams.
- [transactions](https://developer.instapaybill.com/docs/api/transactions/): Listing, resolving and reconciling transactions, including the pending-purchase poll loop.
- [wallet-keys](https://developer.instapaybill.com/docs/api/wallet-keys/): Wallet balance and buckets, funding, API key management, and notifications.
- [catalogue](https://developer.instapaybill.com/docs/api/catalogue/): Networks, categories, settings, feature flags and other reference data.
- [webhooks](https://developer.instapaybill.com/docs/api/webhooks/): Webhook payloads, the x-webhook-signature HMAC scheme, delivery and retry behaviour.
- [sandbox](https://developer.instapaybill.com/docs/api/sandbox/): Simulated endpoints for building against without moving real money.
- [agent-channel](https://developer.instapaybill.com/docs/api/agent-channel/): The WhatsApp agent channel surface and how it differs from the API-key surface.
- [mcp](https://developer.instapaybill.com/docs/api/mcp/): The Model Context Protocol server: transport, authentication and the 50 tools.
- [architecture](https://developer.instapaybill.com/docs/backend/architecture/): How the backend is layered and how a request travels through it.
- [purchase-lifecycle](https://developer.instapaybill.com/docs/backend/purchase-lifecycle/): The purchase path end to end, including holds, refunds and crash recovery.
- [money-model](https://developer.instapaybill.com/docs/backend/money-model/): Wallet buckets, how profit is derived, and commission recoupment.
- [data-models](https://developer.instapaybill.com/docs/backend/data-models/): The Mongo collections and Redis keys behind the API.
- [providers](https://developer.instapaybill.com/docs/backend/providers/): Upstream billers and payment providers, and how a purchase is routed.
- [security](https://developer.instapaybill.com/docs/backend/security/): Every guard on the request path: CORS, blocklist, KYC, permissions, SSRF protection.
- [developer-sso](https://developer.instapaybill.com/docs/backend/developer-sso/): The developer portal PKCE + SSO handshake and why it is built the way it is.

## Optional
- [Full documentation as a single file](https://developer.instapaybill.com/docs/llms-full.txt): every page concatenated.