Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Bills API: airtime, data, electricity, cable TV and betting

Bill payments are paid from your NGN wallet. Each purchase is a lookup step (plans or customer details) followed by a buy step with your own tranx_id, and an optional verify step.
list plans / providers ──> resolve customer ──> buy (tranx_id) ──┬──> 200 successful ├──> 200 queued ──> verify └──> 417 failed, refunded

Outcomes

Every buy endpoint ends in one of these states:
ResponseMeaningYour action
200 ... Was Successful... Thank YouDeliveredGive value
200 ... Queued...Provider still processingPoll Verify bill
417 ... Failed And ReversedFailed, wallet refundedShow the error
401 / 400 ... Please Contact SupportNo final answer yetVerify the same tranx_id
The data record in a buy response is captured before the purchase. Use the message and HTTP status for the outcome, or Verify bill for the final state.

Airtime

Networks: 1 MTN, 2 GLO, 3 9mobile, 4 Airtel. Minimum ₦100.
POST /bills/buy_airtime
{ "network_id": 1, "phone": "08031234567", "amount": 1000, "tranx_id": "ACME-20261121-000185" }

Data

Fetch plans with GET /bills/get_data_plan?network_id=1, then buy with the plan's variation_id.
Plan from GET /bills/get_data_plan
{ "discription": "(₦1500) - 30 Days - 30DAYS", "amount": "1500", "bundle_code": "MTN-2GB-30D", "network_id": 1, "plan_bundle": "30 Days", "expiration": "30DAYS", "variation_id": "2" }
POST /bills/buy_data
{ "network_id": 1, "phone": "08031234567", "variation_id": "2", "tranx_id": "ACME-20261121-000184" }
variation_id is the plan's position in the list, not a permanent ID. Refresh the plan list shortly before buying and never hard-code it.

Electricity

  1. List providers
    GET /bills/get_electricity_provider returns each DisCo's id, name and m_id (for example IKEDC).
  2. Resolve the meter
    POST /bills/resolve_electricity with disco_name and meter_no returns the customer name, address and meter type. Show them to your customer.
  3. Buy
    POST /bills/buy_electricity. Minimum ₦200. Prepaid tokens come back in data.token.
POST /bills/buy_electricity
{ "disco_name": "IKEDC", "meter_no": "45031234567", "amount": 5000, "phone": "08031234567", "name": "ADEBAYO OLUWASEUN", "address": "12 Allen Avenue, Ikeja", "tranx_id": "ACME-20261121-000186" }
Response (prepaid)
{ "status": "success", "message": "Your Electricity Purchase To 45031234567 Was Successful... Thank You", "data": { "order_id": "ACME-20261121-000186", "amount": "5000.00", "phone": "45031234567", "token": "1234-5678-9012-3456-7890" } }
The response above is shortened; the full record is in the API Reference.

Cable TV

TV IDs: 1 GOtv, 2 DStv, 3 StarTimes. Plans have fixed prices, so you only send the plan code.
Plan from GET /bills/get_tv_plan?tv_id=1
{ "id": "1472", "code": "1472", "name": "GOtv Smallie", "amount": "1900", "type": "gotv" }
POST /bills/resolve_cable
{ "tv_id": 1, "smart_card_no": "7023456789" }
POST /bills/buy_cable
{ "tv_id": 1, "code": "1472", "smart_card_no": "7023456789", "tranx_id": "ACME-20261121-000187" }

Betting

Fund a customer's betting wallet. Between ₦500 and ₦100,000.
POST /bills/resolve_betting
{ "betting_provider": "BET9JA", "user": "1234567" }
POST /bills/buy_betting
{ "provider": "BET9JA", "customer_id": "1234567", "name": "ADEBAYO OLUWASEUN", "amount": 5000, "tranx_id": "ACME-20261121-000188" }

Verify and history

  • GET /bills/verify_transaction?tranx_id=... returns 200 successful, 400 pending, 417 failed and refunded, or 404 unknown.
  • GET /bills/get_all_transaction lists recent activity across bills, collections and transfers.