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.
/vtu/airtime/partner/vtu/airtimeBuy airtime
{
"network": "mtn",
"phone": "08011112222",
"amount": "200.00"
}/vtu/data/partner/vtu/dataBuy a data bundle
{
"network": "mtn",
"phone": "08011112222",
"plan_code": "1GB-30D",
"amount": "500.00"
}/vtu/cable/partner/vtu/cablePay a cable subscription
{
"cable_provider": "dstv",
"smartcard_number": "1122334455",
"plan_code": "COMPACT",
"amount": "7900.00"
}/vtu/electricity/partner/vtu/electricityPay an electricity bill
{
"disco": "ikeja-electric",
"meter_number": "66778899",
"amount": "2000.00"
}/vtu/betting/partner/vtu/bettingFund a betting account
{
"betting_provider": "nairabet",
"customer_id": "CUST123",
"amount": "1000.00"
}/vtu/recharge-pin/partner/vtu/recharge-pinGenerate recharge card e-PINs
{
"network": "mtn",
"denomination": "500.00",
"quantity": 10,
"amount": "5000.00"
}/vtu/data-pin/partner/vtu/data-pinGenerate data e-PINs
{
"network": "mtn",
"plan_code": "1GB-30D",
"quantity": 10,
"amount": "5000.00"
}/vtu/smile/partner/vtu/smileBuy a Smile data plan
{
"plan_code": "SMILE-5GB",
"mobile_number": "08011112222",
"amount": "4000.00"
}/vtu/exam-pin/partner/vtu/exam-pinBuy a WAEC or JAMB PIN
{
"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.
/vtu/orders/partner/vtu/ordersList purchase orders
Query params: limit (default 50, max 200), offset.
{
"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.