Electricity

DisCo names and typical min/max (no plan IDs): Catalog.

Pay prepaid or postpaid electricity for Nigerian DisCos. Put the meter number in msisdn and send the matching plan_code from the plans list — each DisCo exposes separate prepaid and postpaid catalog entries. Optionally send phone as the customer’s mobile number (not the meter).

POST /v1/transactions

External create is sync — the response includes the final outcome (response_code 00 or 01). No status polling required. Response shapes: Field conventions.

1. List electricity plans

GET /v1/plans/bills/electricity

Optional filter: ?network=Ikeja Electric.

curl "https://api.subthingy.io/v1/plans/bills/electricity?network=Ikeja Electric" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret"

Use the returned plan id as plan_code on purchase.

DisCo network values

Prepaid vs postpaid

List plans with GET /v1/plans/bills/electricity (optionally filter by network). Each DisCo returns separate prepaid and postpaid rows — pass the plan id as plan_code.

Successful prepaid purchases include token and units in data. Postpaid purchases return a receipt without a token.

2. Pay electricity

curl -X POST "https://api.subthingy.io/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_your_key_id" \
  -H "X-Merchant-Secret: your_issued_secret" \
  -d '{
    "merchant": "YOUR_MERCHANT",
    "msisdn": "10000000001",
    "phone": "08012345678",
    "network": "Ikeja Electric",
    "product": "ELECTRICITY",
    "plan_code": "1001",
    "amount": "5000",
    "request_ref": "subthingy-bill-ikeja-001"
  }'

HTTP 200 — success (prepaid):

{
  "status": "success",
  "response_code": "00",
  "response_message": "Successful",
  "data": {
    "internal_reference": "019262ab-7c4d-7000-8000-000000000010",
    "msisdn": "10000000001",
    "product": "ELECTRICITY",
    "request_id": "subthingy-bill-ikeja-001",
    "network": "Ikeja Electric",
    "amount": "5000",
    "plan": "1001",
    "merchant_id": 10,
    "created_at": "2026-05-17T10:30:00Z",
    "token": "1234-5678-9012-3456-7890",
    "units": "45.2 kWh"
  }
}

Successful prepaid electricity includes token and units in the create data response (and again on status payload). kct1 and kct2 are optional 20-digit Key Change Tokens — present only when issued for the meter; load both on the meter before the recharge token when they appear. Omitted on most purchases.

When the DisCo applies the payment to outstanding meter debt instead of issuing a token, create data and status payload may include payment_spent_on (e.g. "debt") with no token. This field is response-only.

Failed purchases return response_code 01 with status failed.

3. Check status (optional)

To re-fetch a transaction later:

GET /v1/transactions/status?request_ref={request_ref}

See Bill payments overview — Check status.

Test meters

On test credentials, only these meters are accepted. Purchase returns the same success envelope as live (response_code 00, response_message Successful) and is simulated. Any other meter is rejected.

Live credentials always require a real meter.

Ask your account manager to enable electricity on your merchant profile before go-live.