Quickstart

Make your first API call in about five minutes.

---

1. Get a key

Open the InstaPayBill developer portal and sign in with your InstaPayBill account. Access is granted to active, approved agents with a verified email address — there is no separate developer signup.

From the portal:

Key	Where	Use it for
Sandbox key (sk_test_…)	API Keys page	Simulated transactions. Free, no wallet, no real providers.
Live key (sk_live_…)	API Keys page	Real purchases against your real wallet balance.

The sandbox key is what the interactive playground and these examples use. The live key draws down your production wallet.

Keep live keys on your server

A live key can spend real money from your wallet. Never ship it in a browser bundle, a mobile app, a public repo, or a client-side environment variable. Store it in a secret manager and read it at runtime.

---

2. Make a sandbox call

export IPB_SANDBOX_KEY="sk_test_..."

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"
  }'

Response:

{
  "msg": "MTN Airtime Purchase of ₦500 for 08012345678 was successful",
  "data": {
    "code": 200,
    "reference": "SBTEST-ABCD1234EF",
    "description": "MTN Airtime Purchase",
    "message": "Top-up of ₦500 to 08012345678 delivered successfully.",
    "type": "airtime"
  },
  "code": 200
}

The three fields that matter:

• code — 200 succeeded, 300 still being verified by the provider, 400 failed. It always matches the HTTP status.
• data.reference — your unique reference. Save it.
• data.message — the human-readable outcome, safe to show a user.

---

3. Make a live call

Swap the endpoint and the key. Two things change:

• Use a sk_live_… key.
• Send a User-Agent header. The backend rejects requests without one. Omitting it returns HTTP 500 with "Server Error: user agent is missing".

export IPB_LIVE_KEY="sk_live_..."

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"
  }'

apiRefId is your reference for the order. It is stored on the transaction only for API-channel requests, and you can look it up later with GET /api/v1/transactions/resolve?apiRefID=order-1001.

---

4. Look up what happened

curl -G https://api.instapaybill.com/api/v1/transactions/resolve \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0" \
  --data-urlencode "apiRefID=order-1001"

If the purchase settled in a provider callback (after the original response returned 300), the resolve endpoint shows the final code — 200 for delivered, 400 for failed and refunded.

---

5. Handle the failure modes

A purchase can end in three places, and your integration must treat them differently:

Outcome	HTTP / code	What happened	Your action
Success	200	Delivered	Fulfill the order.
Pending	300	Provider has not confirmed yet	Do not retry yet. Wait for the webhook or poll resolve. The wallet is still debited.
Failure	400	Provider declined	The wallet was refunded. Surface the message. Safe to retry.

The most common integration bug is treating 300 as a failure and retrying immediately. A 300 means unknown, and the platform is already polling the provider. Retrying risks a double charge.

---

6. Subscribe to webhooks

Register a public HTTPS URL on the API Keys page and the platform will POST settlement results to it.

curl -X POST https://sandbox.instapaybill.com/api/v1/sandbox/keys/webhook \
  -H "Authorization: Bearer $IPB_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://your-server.com/webhooks/instapaybill"}'

Live webhooks are signed — see Webhooks for the payload shape and the HMAC verification snippet.

---

Next steps

• Authentication — the full auth model, including sessions and the developer portal SSO.
• Errors & Status Codes — the full error contract, including the validation-error shape and per-field error paths.
• Rate Limits — what you can safely send, and how to back off.
• API Reference — every endpoint.