Overview

/v1/bills

All Bills Payment endpoints live under this base path.

Use this section to

• Discover available billers, data plans, and cable plans
• Verify a customer's meter or smartcard before charging them
• Purchase airtime, data, cable TV, or electricity
• Check transaction status and handle webhooks for pending payments

Response format

Success

{
  "status": "success",
  "message": "...",
  "data": { }
}

Error

{
  "status": "error",
  "code": "ERROR_CODE",
  "message": "..."
}

Idempotency - the reference field

Every purchase request takes a reference — a unique key you generate per purchase.

• Retrying a purchase with the same reference will not charge you again; it returns the original transaction.
• Your value is echoed back as merchant_reference in responses.
• Our own transaction ID is returned as reference in the response — use that value for status polling.

Typical integration flow

1. Get Billers pick a biller slug for the category you need.
2. Data / Cable only get the available plans and pick a package id.
3. Cable / Electricity (recommended) - verify the customer to confirm their name before charging them.
4. Purchase calls the airtime, data, cable, or electricity endpoint.
5. If the response is pending, resolve it via the webhook or by polling the transaction status.