Skip to content

Electricity

Buy prepaid electricity units for Nigerian distribution companies (discos) and receive a meter token.

Electricity discos

GET/api/v1/electricity/
curl https://api.instapaybill.com/api/v1/electricity/ \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "User-Agent: my-integration/1.0"

Returns the list of discos you can pay, with their logos and metadata. Each entry carries a disco code (e.g. EEDC, IKEDC) and a name.

Validate a meter

POST/api/v1/electricity/validate

Confirms a meter number belongs to a real customer and returns their name. Do this before a purchase so you can show the customer who the units are going to.

curl -X POST https://api.instapaybill.com/api/v1/electricity/validate \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-integration/1.0" \
  -d '{
    "meterNo": "09012345678",
    "disco": "EEDC",
    "type": "prepaid"
  }'

Request body

Field Type Required Description
meterNo string ✅ Meter number. Numeric.
disco string ✅ Disco code, e.g. EEDC.
type string — prepaid or postpaid. Defaults to prepaid.

Success response — 200

{
  "msg": "EEDC validation completed",
  "data": {
    "status": "200",
    "message": "Meter validated successfully",
    "customerName": "JOHN DOE",
    "customerAddress": "12 Test Street, Lagos",
    "outstandingAmount": null,
    "minimumPayable": null,
    "meterNo": "09012345678",
    "disco": "EEDC",
    "type": "prepaid"
  }
}

Unverifiable meter — 200

This is not an error status

When the provider cannot confirm a meter, the response is still HTTP 200. The signal is in the body: customerName and customerAddress are null and message says the number could not be verified.

{
  "msg": "EEDC validation completed",
  "data": {
    "status": "200",
    "message": "Could not verify this number. Please double-check it before paying.",
    "customerName": null,
    "customerAddress": null,
    "outstandingAmount": null,
    "minimumPayable": null,
    "meterNo": "09012345678",
    "disco": "EEDC",
    "type": "prepaid"
  }
}

Check customerName before proceeding. An HTTP 200 alone does not mean the meter is valid.

Explicitly invalid meter — 300

When the provider rejects the number outright (HTTP 400 or 422 from the provider, with a message matching an invalid-meter pattern):

{
  "error": [
    {
      "msg": "Invalid meter number for selected DISCO",
      "path": "meterNo"
    }
  ]
}

Buy electricity

POST/api/v1/electricity/buy
curl -X POST https://api.instapaybill.com/api/v1/electricity/buy \
  -H "Authorization: Bearer $IPB_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-integration/1.0" \
  -d '{
    "meterNo": "09012345678",
    "disco": "EEDC",
    "type": "prepaid",
    "amount": 5000,
    "phoneNumber": "08012345678",
    "apiRefId": "order-2001"
  }'

Request body

Field Type Required Description
meterNo string ✅ Meter number. Numeric.
disco string ✅ Disco code.
type string ✅ prepaid or postpaid.
amount number ✅ Amount in naira.
phoneNumber string ✅ Nigerian mobile number (en-NG). The customer's contact number.
apiRefId string — Your order reference. API-channel only.
pin string — Wallet PIN. Ignored for API-key requests.
promoCode / coupon string — Not applied for API-channel requests.

Success response — 200

{
  "msg": "prepaid EEDC Electricity Purchase of ₦5,000 for 09012345678 was successful",
  "data": {
    "code": 200,
    "reference": "IP|TN|E|125|20260918120000_ASDFG",
    "msg": "Purchase successful",
    "message": "Units: 66.67 kWh",
    "token": "1234-5678-9012",
    "unit": "66.67",
    "description": "EEDC prepaid Electricity Purchase",
    "type": "electricity"
  },
  "code": 200
}

Electricity is the only service that returns a token

data.token is the prepaid token the customer types into their meter. data.unit is the kilowatt-hours purchased. Note the field is unit (singular) here, while the webhook payload also uses unit.

Pending — 300

{
  "code": 300,
  "reference": "IP|TN|E|125|20260918120000_ASDFG",
  "error": [
    {
      "path": "electricity-merrybills",
      "msg": "Your purchase is being verified with the provider. We will confirm delivery shortly."
    }
  ]
}

Failure — 400

{
  "code": 400,
  "reference": "IP|TN|E|125|20260918120000_ASDFG",
  "error": [
    {
      "path": "electricity-merrybills",
      "msg": "Electricity provider currently unavailable. Try again later."
    }
  ]
}

Guards

Check Rejects when Response
checkNetworkState The disco's category is flagged networkBad 300 with canSchedule: true
UserActive Account suspended 403
TransactionStatusAndKYCCheck No BVN and no NIN 300, path: "kyc_required"
usecases.electricity The service is switched off 300
Category enabled The disco's category is off 300
Wallet balance Insufficient funds 300
Biller health The provider is flagged down 300
Duplicate guards An identical request is in flight 300
KYC purchase gate privilege === 'user' with no BVN/NIN 300, path: "kyc"
  • Cable TV — the other "subscription" service, same validate-then-buy pattern
  • Transactions — resolving a purchase
  • Webhooks — receiving the token asynchronously