Partner API
Product · Utilities

Electricity Bill Payment

Pay prepaid and postpaid electricity bills across all Nigerian Electricity Distribution Companies (DISCOs) with instant token generation and webhook callbacks.

Base path/api/v1/partner/electricity
Authx-api-key (+ x-signature on purchase)
Supported Meter Typesprepaid · postpaid
Rate limit30 requests / 60s (failure circuit breaker)

1. List Electricity Providers (DISCOs)

Query the catalog of active electricity distribution companies and their slug codes:

List active DISCO providers

GET /partner/electricity/providers
API key only
cURL
curl https://api.billpadi.com/api/v1/partner/electricity/providers \
  -H "x-api-key: $API_KEY"
Example response — 200 OK
{
  "success": true,
  "message": "Providers retrieved",
  "data": [
    { "id": "64f1e1a1c4d5e6f7a8b9c101", "name": "Ikeja Electric", "code": "ikeja-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c102", "name": "Eko Electricity (EKEDC)", "code": "eko-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c103", "name": "Abuja Electricity (AEDC)", "code": "abuja-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c104", "name": "Ibadan Electricity (IBEDC)", "code": "ibadan-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c105", "name": "Enugu Electricity (EEDC)", "code": "enugu-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c106", "name": "Port Harcourt Electricity (PHED)", "code": "port-harcourt-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c107", "name": "Jos Electricity (JEDC)", "code": "jos-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c108", "name": "Kaduna Electricity (KAEDCO)", "code": "kaduna-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c109", "name": "Kano Electricity (KEDCO)", "code": "kano-electric" },
    { "id": "64f1e1a1c4d5e6f7a8b9c110", "name": "Benin Electricity (BEDC)", "code": "benin-electric" }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/electricity/providers"
}

2. Pay an Electricity Bill

Purchase electricity for a prepaid meter or settle a postpaid account. The providerId field accepts either the DISCO slug (e.g. ikeja-electric) or the MongoDB ObjectId:

Pay electricity bill

POST /partner/electricity/purchase
Signature required
FieldTypeRequiredDescription
meterNumberstringrequiredPrepaid or postpaid meter number
providerIdstringrequiredDISCO slug code (e.g. ikeja-electric, eko-electric) or ObjectId
amountnumberrequiredPayment amount in NGN (min 500)
meterTypestringrequiredprepaid or postpaid
phonestringrequiredCustomer phone number for SMS token delivery
partnerReferencestringrequiredUnique reference string (2–100 characters) for idempotency
cURL
Node.js
curl -X POST https://api.billpadi.com/api/v1/partner/electricity/purchase \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "meterNumber": "04123456789",
    "providerId": "ikeja-electric",
    "amount": 5000,
    "meterType": "prepaid",
    "phone": "08012345678",
    "partnerReference": "PR-ELEC-77120"
  }'
const res = await partnerClient.post("/electricity/purchase", {
  meterNumber: "04123456789",
  providerId: "ikeja-electric",
  amount: 5000,
  meterType: "prepaid",
  phone: "08012345678",
  partnerReference: "PR-ELEC-77120"
});
Example response — 200 OK
{
  "success": true,
  "message": "Electricity purchase initiated",
  "data": {
    "transactionReference": "TXN_1720603200000_8F9A",
    "partnerReference": "PR-ELEC-77120",
    "status": "pending",
    "meterNumber": "04123456789",
    "amount": 5000,
    "token": "4123 9081 2234 5678 9012",
    "units": "54.2 kWh"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/electricity/purchase"
}

For prepaid meters where the DISCO generates the token asynchronously, our background poller queries the carrier and dispatches an electricity.purchase.success webhook containing the token as soon as it is generated — see Webhooks.

3. Transaction Status & Listing

Get electricity transaction status

GET /partner/electricity/transactions/:reference
API key only

List electricity transactions

GET /partner/electricity/transactions
API key only
← PreviousMobile DataNext →Cable TV