Paying bills
Every bill type follows the same steps:
- Find the biller. Call
GET /bills/billers?type=…and pick one. - Find the product (data and cable TV only). Call
GET /bills/billers/{billerId}/products?type=…. - Validate the number (cable TV and electricity). Call
POST /bills/validateand show the holder's name to your customer. - Price it (optional). Call
POST /bills/quote. - Pay. Call
POST /billswith anIdempotency-Key.
By bill type
Airtime
Send the network's billerId, the phone number and amountMinor. Amounts
must be whole naira ("50000" is ₦500). The phone number may be in any
usual Nigerian form (0803…, +234803…, 234803…). It is returned in
11-digit local form.
Data
Send the network's billerId, the phone number and a bundle productCode
from the products list. The bundle has a fixed price, so amountMinor can be
left out. If you do send it, it must equal the bundle's price
(otherwise AMOUNT_MISMATCH).
Cable TV
Validate the smartcard/IUC number first and show customerName to your
customer. Then pay with the operator's billerId, the smartcard number and
the plan's productCode.
Electricity
Validate the meter number first. The response says whether it is
PREPAID or POSTPAID, the holder's name and address, and for postpaid
meters outstandingMinor. Pay with the distribution company's billerId,
the meter number and amountMinor. The amount must be within
minAmountMinor and maxAmountMinor (otherwise AMOUNT_TOO_LOW /
AMOUNT_TOO_HIGH).
For a prepaid meter, the bill carries the token once it is
SUCCESSFUL. Give it to your customer. The token appears in the pay
response, in GET /bills/{reference} and in the webhook, but not in
GET /bills lists.
Statuses
| Status | Meaning | Your wallet |
|---|---|---|
PENDING | Sent; the biller has not confirmed yet | Charged |
SUCCESSFUL | Delivered | Charged |
FAILED | Not delivered; see failureReason | Refunded in full |
REVERSED | Was successful, then reversed by the biller | Refunded in full |
Most payments complete within seconds, often in the pay response itself.
A PENDING payment usually settles within a few minutes. To follow one,
either:
- wait for the webhook (recommended); or
- poll
GET /bills/{reference}every 10–30 seconds. Each call also asks the biller for news when a check is due.
Never pay again because a bill is PENDING. Vmonie keeps checking until it
settles, and a second payment would charge you twice.
Idempotency
POST /bills requires an Idempotency-Key header: 16–64 characters made
of letters, digits, - or _. Make it unique per payment. Your own order
ID is a good choice.
- Same key, same payment: you get the original bill back. Nothing is paid twice. Retry timeouts and network errors this way.
- Same key, different payment:
409 IDEMPOTENCY_KEY_REUSED. - Lost the response? Call
GET /bills/by-key/{idempotencyKey}to find the payment, or404if it was never created.
Fees and your discount
feeMinor is the fee after your reseller discount, and discountMinor is
the discount itself. totalMinor (amountMinor + feeMinor) is what
your wallet is charged. Your discount rate per bill type is agreed with
Vmonie. Always use the quote or the payment response for the exact
figures.
Listing payments
GET /bills lists your payments, newest first. Filter with type, and
page with limit (up to 100) and cursor (the previous page's
nextCursor).