Overview
Electricity purchases follow a two-step flow:- Validate the meter number to confirm it’s active and retrieve the customer name
- Buy units (prepaid token) or pay a postpaid bill
Authentication
Both endpoints require your merchant API key and thechannel: API header.
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
Step 1 — Validate meter
POST /api/v1/electricity/validate
Request body
| Field | Type | Required | Description |
|---|---|---|---|
meterNumber | string | ✓ | Customer’s meter number |
billerCode | string | ✓ | From Get products (e.g. "EKEDC") or display name (e.g. "Eko Electricity") |
amount | number | ✓ | Intended vend amount in NGN (for pricing context) |
meterType | string | ✓ | "prepaid" or "postpaid" |
curl -sS -X POST "https://api.dancity.app/api/v1/electricity/validate" \
-H "Authorization: Bearer $DANCITY_API_KEY" \
-H "Content-Type: application/json" \
-H "channel: API" \
-d '{
"meterNumber": "45012345678",
"billerCode": "EKEDC",
"amount": 2000,
"meterType": "prepaid"
}'
const res = await fetch("https://api.dancity.app/api/v1/electricity/validate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
"Content-Type": "application/json",
channel: "API",
},
body: JSON.stringify({
meterNumber: "45012345678",
billerCode: "EKEDC",
amount: 2000,
meterType: "prepaid",
}),
});
const { data } = await res.json();
console.log(data.customerName); // display to user
import requests, os
res = requests.post(
"https://api.dancity.app/api/v1/electricity/validate",
headers={
"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
"Content-Type": "application/json",
"channel": "API",
},
json={
"meterNumber": "45012345678",
"billerCode": "EKEDC",
"amount": 2000,
"meterType": "prepaid",
},
)
customer_name = res.json()["data"]["customerName"]
Sample response
{
"success": true,
"message": "Validation successful",
"data": {
"customerName": "Jane Doe"
}
}
Always show
customerName to the user before proceeding to purchase — it confirms the meter number is correct.Step 2 — Buy electricity token
POST /api/v1/electricity/buy
Request body
| Field | Type | Required | Description |
|---|---|---|---|
meterNumber | string | ✓ | Same number used in validation |
billerCode | string | ✓ | From Get products (e.g. "EKEDC") |
meterType | string | ✓ | "prepaid" or "postpaid" |
amount | number | ✓ | Vend amount in NGN (minimum ₦500) |
customerName | string | ✓ | Name returned from validation |
address | string | ✓ | Customer’s address |
customerRef | string | Your internal reference ID | |
saveAsBeneficiary | boolean | Save meter as beneficiary | |
promocode | string | Discount promo code |
curl -sS -X POST "https://api.dancity.app/api/v1/electricity/buy" \
-H "Authorization: Bearer $DANCITY_API_KEY" \
-H "Content-Type: application/json" \
-H "channel: API" \
-d '{
"meterNumber": "45012345678",
"billerCode": "EKEDC",
"meterType": "prepaid",
"amount": 2000,
"customerName": "Jane Doe",
"address": "12 Lekki Phase 1, Lagos",
"customerRef": "ELEC-REF-001"
}'
const res = await fetch("https://api.dancity.app/api/v1/electricity/buy", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
"Content-Type": "application/json",
channel: "API",
},
body: JSON.stringify({
meterNumber: "45012345678",
billerCode: "EKEDC",
meterType: "prepaid",
amount: 2000,
customerName: "Jane Doe",
address: "12 Lekki Phase 1, Lagos",
customerRef: "ELEC-REF-001",
}),
});
const data = await res.json();
import requests, os
res = requests.post(
"https://api.dancity.app/api/v1/electricity/buy",
headers={
"Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
"Content-Type": "application/json",
"channel": "API",
},
json={
"meterNumber": "45012345678",
"billerCode": "EKEDC",
"meterType": "prepaid",
"amount": 2000,
"customerName": "Jane Doe",
"address": "12 Lekki Phase 1, Lagos",
"customerRef": "ELEC-REF-001",
},
)
print(res.json())
Sample response (prepaid)
{
"success": true,
"message": "Electricity purchase processed",
"data": {
"transactionId": "TXN-2025-XXXXX",
"token": "1234-5678-9012-3456-7890",
"amount": 2000,
"meterNumber": "45012345678"
}
}
For prepaid meters, the
token field in the response is the recharge token to give the customer. Store it with the transaction record.Full purchase flow
1. Collect meterNumber, meterType, billerCode from user
2. POST /api/v1/electricity/validate { meterNumber, billerCode, amount, meterType }
→ confirm customerName
3. Show customerName to user → user confirms
4. POST /api/v1/electricity/buy
→ send meterNumber, billerCode, meterType, amount, customerName, address
The minimum vend amount is ₦500. Requests below this threshold return a
400 validation error.