Partner API
Product · Telecommunications

Mobile Data

Purchase mobile data bundles from a catalog of network packages (SME, Gifting, Corporate) with instant delivery and partner pricing.

Base path/api/v1/partner/data
Authx-api-key (+ x-signature on purchase)
Network Slugsmtn · airtel · glo · 9mobile
Rate limit30 requests / 60s (failure circuit breaker)

1. List Data Networks

Retrieve the active data providers and their network slugs:

List active data networks

GET /partner/data/networks
API key only
cURL
curl https://api.billpadi.com/api/v1/partner/data/networks \
  -H "x-api-key: $API_KEY"
Example response — 200 OK
{
  "success": true,
  "message": "Networks retrieved",
  "data": [
    { "id": "64f1a2b1c4d5e6f7a8b9c001", "name": "MTN", "code": "mtn" },
    { "id": "64f1a2b1c4d5e6f7a8b9c002", "name": "Airtel", "code": "airtel" },
    { "id": "64f1a2b1c4d5e6f7a8b9c003", "name": "Glo", "code": "glo" },
    { "id": "64f1a2b1c4d5e6f7a8b9c004", "name": "9mobile", "code": "9mobile" }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/data/networks"
}

2. List Data Bundle Products

Query available data plans for a given network slug or service ID:

List data plans for network

GET /partner/data/products
API key only
Query ParamTypeRequiredDescription
serviceIdstringrequiredNetwork slug (e.g. mtn, airtel, glo, 9mobile) or MongoDB ObjectId
dataTypestringoptionalOptional filter: SME, GIFTING, CORPORATE
cURL
curl "https://api.billpadi.com/api/v1/partner/data/products?serviceId=mtn" \
  -H "x-api-key: $API_KEY"
Example response — 200 OK
{
  "success": true,
  "message": "Products retrieved",
  "data": [
    {
      "id": "64f3a2b1c4d5e6f7a8b9c0e1",
      "code": "mtn-1gb-sme",
      "name": "MTN 1GB SME Data",
      "amount": 265,
      "validity": "30 Days",
      "dataType": "SME",
      "dataSize": 1024,
      "dataSizeDisplay": "1GB",
      "description": "MTN SME Data bundle valid for 30 days"
    },
    {
      "id": "64f3a2b1c4d5e6f7a8b9c0e2",
      "code": "mtn-2gb-sme",
      "name": "MTN 2GB SME Data",
      "amount": 530,
      "validity": "30 Days",
      "dataType": "SME",
      "dataSize": 2048,
      "dataSizeDisplay": "2GB",
      "description": "MTN SME Data bundle valid for 30 days"
    }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/data/products"
}

3. Purchase a Data Bundle

Purchase a data plan. You can pass either the product's id (MongoDB ObjectId) or the human-readable code (e.g. mtn-1gb-sme):

Purchase data bundle

POST /partner/data/purchase
Signature required
FieldTypeRequiredDescription
phonestringrequiredRecipient 11-digit phone number (e.g. 08012345678)
productIdstringrequiredProduct id or slug code from the products catalog
partnerReferencestringrequiredUnique reference string (2–100 characters) for idempotency
cURL
Node.js
curl -X POST https://api.billpadi.com/api/v1/partner/data/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "phone": "08012345678",
    "productId": "mtn-1gb-sme",
    "partnerReference": "PR-DATA-33012"
  }'
const res = await partnerClient.post("/data/purchase", {
  phone: "08012345678",
  productId: "mtn-1gb-sme",
  partnerReference: "PR-DATA-33012"
});
Example response — 200 OK
{
  "success": true,
  "message": "Data purchase initiated",
  "data": {
    "transactionReference": "TXN_1720603200000_5E6F",
    "partnerReference": "PR-DATA-33012",
    "status": "pending",
    "phone": "08012345678",
    "amount": 265,
    "productName": "MTN 1GB SME Data"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/data/purchase"
}

When the carrier confirms bundle provision, Billpadi fires a data.purchase.success webhook to your endpoint.

4. Transaction Status & Listing

Get data transaction status

GET /partner/data/transactions/:reference
API key only

List data transactions

GET /partner/data/transactions
API key only
← PreviousAirtimeNext →Electricity