Developer API · Airtime API
Airtime API for MTN, Airtel, Glo and 9mobile
Send airtime to any Nigerian number with one request. You choose the amount, we deliver it and pay commission back on every successful top-up.
- REST and JSON
- Bearer API key
- Refund on every failed purchase
/v1/airtime/purchase{
"network": "mtn",
"phone": "08012345678",
"amount": 100,
"request_ref": "9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70"
}Endpoints
All requests go to https://api.vtuagent.com with your key in the Authorization header.
Example request
POST /v1/airtime/purchase, in the language your site is built with.
curl -X POST https://api.vtuagent.com/v1/airtime/purchase \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"network": "mtn",
"phone": "08012345678",
"amount": 100,
"request_ref": "9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70"
}'const res = await fetch('https://api.vtuagent.com/v1/airtime/purchase', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.VTUAGENT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"network": "mtn",
"phone": "08012345678",
"amount": 100,
"request_ref": "9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70"
}),
});
const result = await res.json();$ch = curl_init('https://api.vtuagent.com/v1/airtime/purchase');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('VTUAGENT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'network' => 'mtn',
'phone' => '08012345678',
'amount' => 100,
'request_ref' => '9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70',
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
res = requests.post(
"https://api.vtuagent.com/v1/airtime/purchase",
headers={"Authorization": f"Bearer {os.environ['VTUAGENT_API_KEY']}"},
json={
"network": "mtn",
"phone": "08012345678",
"amount": 100,
"request_ref": "9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70"
},
)
result = res.json()Response
{
"status": "successful",
"status_code": 200,
"message": "Airtime purchase successful - 100 to 08012345678",
"reference": "9f1c2a4e-7b3d-4c8e-9a1f-2b3c4d5e6f70",
"data": {
"amount": "100",
"network": "mtn",
"phone": "08012345678"
}
}How it behaves
Four networks, one field
Set network to mtn, airtel, glo or etisalat (9mobile). The amount is in naira and can be a number or a numeric string.
Answer within 15 seconds
The request waits up to 15 seconds for the network. If it’s slower you get 202 pending, and the result arrives by webhook or from the status endpoint.
Charged once, refunded on failure
Your wallet is debited when the request is accepted. If the provider rejects the purchase you get HTTP 424 and the money is already back in your wallet.
Safe to retry
Every purchase carries your own request_ref (a UUID works). Sending the same reference twice is rejected with 400, so a retry after a timeout can’t charge you twice.
Airtime commission by account type
The share of each payment paid back to you. API accounts get the API column.
| Network | Regular | Agent | API |
|---|---|---|---|
| 9MOBILE | 2% | 2.5% | 3% |
| AIRTEL | 2% | 2.5% | 3% |
| GLO | 2% | 2.5% | 3% |
| MTN | 2% | 2.5% | 3% |
Commission is paid into your commission balance on every successful purchase. Agent and API accounts earn more.
Get your API key
- Step 1
Create an account
Sign up for free with your email.
- Step 2
Apply for API access
On Upgrade Account, choose API User and add the website or app you’ll connect.
- Step 3
Get your key
Once you’re approved, generate your key in Settings → API Keys. Send it as Authorization: Bearer <key> on every request.
- Step 4
Fund your wallet
Purchases are paid from your wallet balance at API prices, so top it up by bank transfer or card.
Questions people ask
Which networks can I top up?
MTN, Airtel, Glo and 9mobile. 9mobile uses the network value etisalat.
Do I earn commission on airtime sold through the API?
Yes. The API rate for each network is in the table on this page, and it is the highest of our three account types.
How do I know if a top-up succeeded?
Most top-ups return 200 successful in the same request. Slower ones return 202 pending, followed by an airtime.purchase.success or airtime.purchase.failed webhook. You can also poll POST /v1/transaction/status.
Can I retry a top-up that timed out?
Check it first with POST /v1/transaction/status using the same request_ref. A purchase with a reference you already used is rejected, so you can’t pay twice by mistake.
Other APIs
Start selling with the Airtime API
Apply for API access, then follow the docs at docs.vtuagent.com.