Skip to main content

Paying bills

Every bill type follows the same steps:

  1. Find the biller. Call GET /bills/billers?type=… and pick one.
  2. Find the product (data and cable TV only). Call GET /bills/billers/{billerId}/products?type=….
  3. Validate the number (cable TV and electricity). Call POST /bills/validate and show the holder's name to your customer.
  4. Price it (optional). Call POST /bills/quote.
  5. Pay. Call POST /bills with an Idempotency-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​

StatusMeaningYour wallet
PENDINGSent; the biller has not confirmed yetCharged
SUCCESSFULDeliveredCharged
FAILEDNot delivered; see failureReasonRefunded in full
REVERSEDWas successful, then reversed by the billerRefunded 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, or 404 if 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).