Product · Telecommunications

Airtime

Top up any supported Nigerian mobile network directly to a recipient phone number with instant fulfillment and partner discounts.

Base path/api/v1/partner/airtime

Authx-api-key (+ x-signature on purchase)

Supported NetworksMTN (mtn) · Airtel (airtel) · Glo (glo) · 9mobile (9mobile)

Rate limit30 requests / 60s (failure circuit breaker)

1. List Supported Networks

Retrieve the active telecommunication carriers and their corresponding network slugs:

List active telecom networks

GET /partner/airtime/networks

API key only

cURL

Node.js

curl https://api.billpadi.com/api/v1/partner/airtime/networks \
  -H "x-api-key: $API_KEY"

const res = await partnerClient.get("/airtime/networks");

Example response — 200 OK

{
  "success": true,
  "message": "Networks retrieved",
  "data": [
    { "network": "mtn", "name": "MTN" },
    { "network": "airtel", "name": "Airtel" },
    { "network": "glo", "name": "Glo" },
    { "network": "9mobile", "name": "9mobile" }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/networks"
}

2. Purchase Airtime

Purchase airtime for a customer phone number. The transaction is instantly dispatched to the active telco gateway:

Purchase mobile airtime

POST /partner/airtime/purchase

Signature required

Field	Type	Required	Description
phone	string	required	Recipient 11-digit Nigerian phone number (e.g. `08012345678`)
amount	number	required	Amount in NGN (positive number, min 50, max 1,000,000)
network	string	required	Network slug: `mtn`, `airtel`, `glo`, or `9mobile`
partnerReference	string	required	Unique reference string (2–100 characters) for idempotency

cURL

Node.js

curl -X POST https://api.billpadi.com/api/v1/partner/airtime/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "phone": "08012345678",
    "amount": 500,
    "network": "mtn",
    "partnerReference": "PR-AT-55210"
  }'

const res = await partnerClient.post("/airtime/purchase", {
  phone: "08012345678",
  amount: 500,
  network: "mtn",
  partnerReference: "PR-AT-55210"
});

Example response — 200 OK

{
  "success": true,
  "message": "Airtime purchase initiated",
  "data": {
    "transactionReference": "TXN_1720603200000_1A2B",
    "partnerReference": "PR-AT-55210",
    "status": "pending",
    "phone": "08012345678",
    "network": "mtn",
    "amount": 500,
    "totalCost": 485,
    "timestamp": 1752136800000
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/airtime/purchase"
}

When the carrier confirms top-up delivery, Billpadi fires an airtime.purchase.success webhook to your webhook URL — see Webhooks.

3. Transaction Status & Listing

Get airtime transaction status

GET /partner/airtime/transactions/:reference

API key only

List airtime transactions

GET /partner/airtime/transactions

API key only

← PreviousIdentity Verification Next →Mobile Data