Developer API · Electricity API
Electricity bill payment API for Nigerian DISCOs
Check a meter, then sell prepaid units or settle a postpaid bill with one request. Prepaid purchases return the token and units in the response, and we also text the token to the customer.
- REST and JSON
- Bearer API key
- Refund on every failed purchase
/v1/electricity/purchase{
"disco": "ikeja-electric",
"meter_number": "1111111111111",
"meter_type": "prepaid",
"amount": 2000,
"phone": "08012345678",
"request_ref": "d4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f"
}Endpoints
All requests go to https://api.vtuagent.com with your key in the Authorization header.
Example request
POST /v1/electricity/purchase, in the language your site is built with.
curl -X POST https://api.vtuagent.com/v1/electricity/purchase \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"disco": "ikeja-electric",
"meter_number": "1111111111111",
"meter_type": "prepaid",
"amount": 2000,
"phone": "08012345678",
"request_ref": "d4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f"
}'const res = await fetch('https://api.vtuagent.com/v1/electricity/purchase', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.VTUAGENT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"disco": "ikeja-electric",
"meter_number": "1111111111111",
"meter_type": "prepaid",
"amount": 2000,
"phone": "08012345678",
"request_ref": "d4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f"
}),
});
const result = await res.json();$ch = curl_init('https://api.vtuagent.com/v1/electricity/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([
'disco' => 'ikeja-electric',
'meter_number' => '1111111111111',
'meter_type' => 'prepaid',
'amount' => 2000,
'phone' => '08012345678',
'request_ref' => 'd4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f',
]),
]);
$result = json_decode(curl_exec($ch), true);import os, requests
res = requests.post(
"https://api.vtuagent.com/v1/electricity/purchase",
headers={"Authorization": f"Bearer {os.environ['VTUAGENT_API_KEY']}"},
json={
"disco": "ikeja-electric",
"meter_number": "1111111111111",
"meter_type": "prepaid",
"amount": 2000,
"phone": "08012345678",
"request_ref": "d4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f"
},
)
result = res.json()Response
{
"status": "successful",
"status_code": 200,
"message": "Electricity purchase successful",
"reference": "d4a8c1e2-6f3b-4a7d-9e0c-5b6a7c8d9e0f",
"data": {
"address": "12 Example Street, Ikeja, Lagos",
"amount": "2000",
"customer_name": "JOHN DOE",
"disco": "ikeja-electric",
"meter_number": "1111111111111",
"token": "1234 5678 9012 3456 7890",
"units": "28.64"
}
}How it behaves
Verify before you charge
POST /v1/electricity/verify returns the customer name and address, so your customer can confirm the meter before paying.
Token in the response
Successful prepaid purchases include token and units. The token is also sent by SMS to the phone number you pass.
Final answer, no webhook needed
The DISCO is called while you wait, so the response is the result. Only a 202 pending needs a follow-up with the status endpoint.
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.
DISCOs and commission by account type
The share of each payment paid back to you. API accounts get the API column.
| DISCO | Regular | Agent | API |
|---|---|---|---|
| Abuja Electricity | 0.8% | 0.8% | 1% |
| Eko Electricity | 0.8% | 0.8% | 0.8% |
| Enugu Electricity | 0.8% | 0.8% | 1% |
| Ibadan Electricity | 0.8% | 0.8% | 0.9% |
| Ikeja Electric | 0.8% | 0.8% | 0.8% |
| Jos Electricity | 0.6% | 0.6% | 0.7% |
| Kaduna Electric | 0.8% | 0.8% | 1% |
| Port Harcourt Electricity | 0.8% | 0.8% | 0.9% |
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 DISCOs does the electricity API support?
The live list, with the commission on each, is in the table on this page. It includes Abuja (AEDC), Ikeja (IKEDC), Eko (EKEDC), Ibadan, Enugu, Port Harcourt, Jos and Kaduna.
Is there a minimum amount?
Minimums are set by each DISCO and are typically ₦1,000.
Does the API return the prepaid token?
Yes. A successful prepaid purchase returns token and units in the response, and the token is also sent by SMS to the phone number in the request.
Can I pay postpaid bills through the API?
Yes. Set meter_type to postpaid. The response confirms the payment; token and units are empty for postpaid.
Other APIs
Start selling with the Electricity API
Apply for API access, then follow the docs at docs.vtuagent.com.