BILLS PAYMENT

Pay Electricity

Pay a prepaid or postpaid electricity bill. Prepaid purchases return a vend token and units.

POST /v1/bills/electricity

Use this endpoint to

Pay a prepaid or postpaid electricity bill for a meter number
Retrieve the vend token and units for prepaid purchases
Safely retry a purchase without double-charging, using reference

Body parameters

Field	Type	Required	Description
`disco`	string	Yes	Electricity biller `slug` from Get Billers (e.g. `IKEDC`)
`meter`	string	Yes	Meter number
`amount`	number	Yes	NGN, minimum 2,000
`meter_type`	string	Yes	`PREPAID` or `POSTPAID`
`customer_name`	string	No	Name from Verify Customer - recommended, not required
`reference`	string	Yes	Your unique idempotency key for this purchase

Code Samples

const response = await fetch("https://sandbox.hitchpay.ng/v1/bills/electricity", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    disco: "IKEDC",
    meter: "45700123456",
    amount: 5000,
    meter_type: "PREPAID",
    customer_name: "JOHN DOE",
    reference: "order-elec-001"
  })
});

const data = await response.json();
console.log(data);

<?php

$ch = curl_init();

curl_setopt_array($ch, [
  CURLOPT_URL => "https://sandbox.hitchpay.ng/v1/bills/electricity",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode([
    "disco" => "IKEDC",
    "meter" => "45700123456",
    "amount" => 5000,
    "meter_type" => "PREPAID",
    "customer_name" => "JOHN DOE",
    "reference" => "order-elec-001"
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_ACCESS_TOKEN",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

import requests

url = "https://sandbox.hitchpay.ng/v1/bills/electricity"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json"
}
payload = {
    "disco": "IKEDC",
    "meter": "45700123456",
    "amount": 5000,
    "meter_type": "PREPAID",
    "customer_name": "JOHN DOE",
    "reference": "order-elec-001"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json()

Response

Success (prepaid)

{
  "status": "success",
  "message": "Bill payment successful.",
  "data": {
    "reference": "HTCHB…",
    "merchant_reference": "order-elec-001",
    "product": "electricity",
    "provider": "IKEDC",
    "amount": 5000,
    "fee": 0,
    "amount_charged": 5000,
    "recipient": "45700123456",
    "currency": "NGN",
    "balance": 88450.75,
    "token": "1234-5678-9012-3456",
    "units": "34.5 kWh",
    "paid_at": "2026-07-02T10:30:00.000Z"
  }
}

Fields

Field	Type	Description
`reference`	string	Our transaction id — use this for status polling
`merchant_reference`	string	Echoes the `reference` you sent
`product`	string	`electricity`
`provider`	string	Disco slug
`amount`	number	Amount charged
`fee`	number	Fee charged, if any
`amount_charged`	number	Total debited from your wallet
`recipient`	string	Meter number charged
`currency`	string	`NGN`
`balance`	number	Your wallet balance after this transaction
`token`	string	Vend token (prepaid only, when the provider returns one)
`units`	string	Units purchased (prepaid only, when the provider returns one)
`paid_at`	string	ISO 8601 timestamp

Errors

Code	Meaning
`INVALID_REQUEST`	Missing/invalid fields, or `amount` below NGN 2,000
`UNAUTHORIZED`	Business not found or inactive
`PRODUCT_UNAVAILABLE`	No matching disco configured
`INSUFFICIENT_BALANCE`	Wallet balance too low
`BILL_FAILED`	Provider declined the purchase — wallet is auto-refunded
`PROVIDER_ERROR` / `VERIFY_FAILED`	Provider or verification call failed

Note: If token/units are missing from an otherwise successful prepaid response; check Get Transaction Status shortly after. Some providers return the token asynchronously.

If the response is pending, resolve it via Get Transaction Status or the bill.success / bill.failed webhook.

Questions? Email [email protected]. Also on GitBook.