Skip to main content

​
Overview

Electricity purchases follow a two-step flow:
  1. Validate the meter number to confirm it’s active and retrieve the customer name
  2. Buy units (prepaid token) or pay a postpaid bill
Supported DISCOs include IKEDC, EKEDC, AEDC, PHEDC, and others.

​
Authentication

Both endpoints require your merchant API key and the channel: API header. 
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API

​
Step 1 — Validate meter

POST /api/v1/electricity/validate

​
Request body

FieldTypeRequiredDescription
meterNumberstring✓Customer’s meter number
billerCodestring✓From Get products (e.g. "EKEDC") or display name (e.g. "Eko Electricity")
amountnumber✓Intended vend amount in NGN (for pricing context)
meterTypestring✓"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"
  }'

​
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

FieldTypeRequiredDescription
meterNumberstring✓Same number used in validation
billerCodestring✓From Get products (e.g. "EKEDC")
meterTypestring✓"prepaid" or "postpaid"
amountnumber✓Vend amount in NGN (minimum ₦500)
customerNamestring✓Name returned from validation
addressstring✓Customer’s address
customerRefstringYour internal reference ID
saveAsBeneficiarybooleanSave meter as beneficiary
promocodestringDiscount 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"
  }'

​
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.

​
Next steps