You're offline — reconnect to continue buying or checking your wallet.
Core concepts

Purchases

Nine purchase endpoints, one shape: debit the wallet, route the request to a provider, and settle the order as success or failed, a failure refunds the wallet automatically as a separate ledger entry, never by rewinding the debit.

Partner-only fields

Each partner purchase endpoint accepts an optional partner_customer_reference query parameter, pass your own end-customer's id so it shows up on the order for your own reconciliation. TopupRelay never requires or interprets it.

POST/vtu/airtime
POST/partner/vtu/airtime

Buy airtime

Request body
{
  "network": "mtn",
  "phone": "08011112222",
  "amount": "200.00"
}
POST/vtu/data
POST/partner/vtu/data

Buy a data bundle

Request body
{
  "network": "mtn",
  "phone": "08011112222",
  "plan_code": "1GB-30D",
  "amount": "500.00"
}
POST/vtu/cable
POST/partner/vtu/cable

Pay a cable subscription

Request body
{
  "cable_provider": "dstv",
  "smartcard_number": "1122334455",
  "plan_code": "COMPACT",
  "amount": "7900.00"
}
POST/vtu/electricity
POST/partner/vtu/electricity

Pay an electricity bill

Request body
{
  "disco": "ikeja-electric",
  "meter_number": "66778899",
  "amount": "2000.00"
}
POST/vtu/betting
POST/partner/vtu/betting

Fund a betting account

Request body
{
  "betting_provider": "nairabet",
  "customer_id": "CUST123",
  "amount": "1000.00"
}
POST/vtu/recharge-pin
POST/partner/vtu/recharge-pin

Generate recharge card e-PINs

Request body
{
  "network": "mtn",
  "denomination": "500.00",
  "quantity": 10,
  "amount": "5000.00"
}
POST/vtu/data-pin
POST/partner/vtu/data-pin

Generate data e-PINs

Request body
{
  "network": "mtn",
  "plan_code": "1GB-30D",
  "quantity": 10,
  "amount": "5000.00"
}
POST/vtu/smile
POST/partner/vtu/smile

Buy a Smile data plan

Request body
{
  "plan_code": "SMILE-5GB",
  "mobile_number": "08011112222",
  "amount": "4000.00"
}
POST/vtu/exam-pin
POST/partner/vtu/exam-pin

Buy a WAEC or JAMB PIN

Request body
{
  "exam_type": "exam_jamb",
  "phone": "08011112222",
  "profile_id": "1234567890",
  "amount": "6200.00"
}

exam_type is exam_waec or exam_jamb. profile_id is required for JAMB, omit it for WAEC.

GET/vtu/orders
GET/partner/vtu/orders

List purchase orders

Query params: limit (default 50, max 200), offset.

201 response, any purchase endpoint
{
  "success": true,
  "data": {
    "id": "d4e5f6a7-...",
    "reference": "PO-17C0EA5155C544FF",
    "service_type": "airtime",
    "recipient_identifier": "08011112222",
    "amount": "200.00",
    "status": "success",
    "failure_reason": null,
    "product_details": { "network": "mtn", "phone": "08011112222" },
    "created_at": "2026-11-17T16:11:00Z",
    "completed_at": "2026-11-17T16:11:01Z"
  }
}

status is one of pending, processing, success, failed, or reversed. A 402 response with INSUFFICIENT_BALANCE means nothing was debited, fund the wallet and retry. Which upstream network actually fulfilled a purchase is never part of this response, by design.