> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bill payments introduction

> What the enquiry protects against, how bills differ from transfers, and when the service is the wrong tool.

Paying a bill looks like a transfer with a different destination. It is not. A bill is delivered as *value* — units of electricity, minutes of airtime, a month of television — and value that has been delivered cannot be recalled.

That asymmetry explains everything about the design.

## Why the enquiry exists

A meter number typed one digit wrong is a valid meter number belonging to someone else. Send money to it and the electricity is delivered — to them.

The enquiry is the check:

| It returns | It prevents |
| - | - |
| The customer's name and address | Paying the wrong meter or account |
| `minimumAmount`, `totalDue` | Sending an amount the biller will reject |
| `charge`, `commission`, `totalDebit` | Surprising the payer with the real cost |
| `canVend` | Attempting a customer the biller will not serve |

Show the name before you take the money. It is a two-second confirmation that catches the one class of mistake this service cannot undo.

The ten-minute expiry is part of the same idea: the answer is a snapshot, and a snapshot from an hour ago is not evidence.

## Bills are not transfers

| | Transfer | Bill payment |
| - | - | - |
| Destination | A destination object | An enquiry |
| Pre-check lifetime | 24 hours | **10 minutes** |
| Currency | Seven fiat, four crypto | **NGN only** |
| Amounts | Minor units, `"500000"` | Decimals, `"5000.00"` |
| Failure | Money stays put | **Debit reversed automatically** |
| Success state | `completed` | **`confirmed`** |
| Delivers | Money | Value — units, minutes, a token |

The three bolded rows are where integrations go wrong: the wrong amount convention, waiting too long between enquiry and payment, and looking for a `completed` that never arrives.

## When this is the wrong service

* **Paying a person or a business.** That is a [transfer](/services/transfers/overview).
* **Paying in any currency but NGN.** Bill payments are naira only.
* **Anything not in the catalog.** You cannot pay an arbitrary biller; the catalog is the whole universe.

## What the enquiry cannot tell you

* **Whether the customer wants to pay.** It confirms identity, not intent.
* **Whether delivery will succeed.** `canVend` is the biller's opinion at that moment; the vend can still fail.
* **What the token will be.** Credentials come with the confirmation, not before.

## The shape of the API

The catalog tree, then three steps.

| Operation | Notes |
| - | - |
| [`GET /v1/bill-payments/groups`](/api-reference/bill-payments/list-biller-groups) | Kinds of bill. |
| [`GET …/groups/{groupId}`](/api-reference/bill-payments/get-a-biller-group) | One group. |
| [`GET …/groups/{groupId}/billers`](/api-reference/bill-payments/list-billers-in-a-group) | Billers in one group. |
| [`GET …/groups/{groupId}/billers/{billerId}`](/api-reference/bill-payments/get-a-biller-in-a-group) | One biller. |
| [`GET …/groups/{groupId}/billers/{billerId}/packages`](/api-reference/bill-payments/list-packages-for-a-biller-in-a-group) | Packages, group-scoped. |
| [`GET …/billers/{billerId}`](/api-reference/bill-payments/get-a-biller) | One biller, unscoped. |
| [`GET …/billers/{billerId}/packages`](/api-reference/bill-payments/list-packages-for-a-biller) | Packages, unscoped. |
| [`GET …/packages/{packageId}`](/api-reference/bill-payments/get-a-package) | One package, by id. |
| [`POST /v1/bill-payments/enquiries`](/api-reference/bill-payments/validate-a-customer) | Validate and price. Ten minutes. |
| [`POST /v1/bill-payments`](/api-reference/bill-payments/pay-a-bill) | Pay. |
| [`GET /v1/bill-payments`](/api-reference/bill-payments/list-bill-payments) | History, filterable by status. |
| [`GET /v1/bill-payments/{paymentId}`](/api-reference/bill-payments/get-a-bill-payment) | One payment, with its token. |

There is no cancel and no refund endpoint. A failure refunds itself; a success is final.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.