Airtime Topup API

Purchase VTU airtime instantly across all major Nigerian telecommunication networks (MTN, GLO, AIRTEL, 9MOBILE) via a secure, idempotent API.

POST /api/v1/airtime/purchase

Authentication & Headers

HEADER	VALUE	REQUIRED
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes
`Content-Type`	`application/json`	Yes
`Accept`	`application/json`	Yes

Supported Network Codes

NETWORK	NETWORK CODE	ACCEPTED ALIASES	DISCOUNT (BASE PRICE)	MIN / MAX AMOUNT	STATUS
Airtel Nigeria	100	`100`, `airtel`	2.0%	₦50 - ₦5,000	Active
MTN Nigeria	101	`101`, `mtn`	2.0%	₦50 - ₦5,000	Active
Glo Nigeria	102	`102`, `glo`	2.0%	₦50 - ₦5,000	Active
9mobile Nigeria	103	`103`, `9mobile`, `etisalat`	2.0%	₦50 - ₦5,000	Active

Request Parameters

PARAMETER	TYPE	DESCRIPTION	REQUIRED
`network`	string	Network Code (e.g. `101` or `mtn`).	Required
`mobileno`	string	11-digit Nigerian mobile number starting with 07, 08, or 09 (e.g. `08012345678`).	Required
`amount`	integer	Recharge amount between ₦50 and ₦5,000.	Required
`request_id`	string	Optional unique client request reference for idempotency and duplicate-request protection (max 64 chars).	Optional

Sample Request Payload

JSON

{
    "network": "101",
    "mobileno": "08012345678",
    "amount": 500,
    "request_id": "REQ_20261019_001"
}

Success Response (200 OK)

{
    "status": "success",
    "code": 200,
    "message": "Airtime successful",
    "data": {
        "transaction_ref": "202610194829104",
        "request_id": "REQ_20261019_001",
        "network": "101",
        "network_name": "Mtn",
        "amount": 500,
        "phone": "08012345678",
        "commission_earned": 10.0,
        "new_balance": 4510.0,
        "status": "success"
    }
}

Failed Response (400 Bad Request)

{
    "status": "failed",
    "code": 400,
    "message": "Airtime failed."
}