Skip to navigation
Overview

Overview

Interactive documentation generated from your API specification
View as Markdown

VTUAgent is a Nigerian VTU platform for selling airtime, mobile data, cable TV subscriptions and electricity from your own product, funded from a prepaid wallet.

Use this documentation to integrate with the VTUAgent API, understand the available endpoints, and test requests against the generated API reference. Every purchase is confirmed synchronously where possible and reconciled through a transaction-status endpoint and signed webhooks where it is not.

API base URL
https://api.vtuagent.com/v1

Authentication

Generate an API key from the VTUAgent dashboard and send it with every request as Authorization: Bearer {your_api_key}. Requests with a missing, malformed or revoked key return 401 Unauthorized.

Wallet
All purchases are debited from your VTUAgent wallet at the moment they are accepted. If the provider later rejects a purchase (424), the amount is refunded automatically. Top up your wallet from the dashboard.

VTUAgent integration flow

  • API — Create an API key and send it with every request.
  • API — Call POST /webhook/set with your HTTPS endpoint to receive signed notifications for airtime and data purchases. Verify each delivery with hash = hex(sha256("{your_api_key}:{reference}")) and respond 200.
  • API — For data, call GET /data/plans to list every bundle priced for your account tier. Store the plan_id values; the price shown is exactly what your wallet will be debited.
  • API — For cable TV, call POST /cabletv/variations with the provider (dstv, gotv, startimes) to list bouquets and their prices, then POST /cabletv/verify with the customer’s smartcard number to retrieve the account holder’s name.
  • API — For electricity, call POST /electricity/verify with the disco, meter number and meter type (prepaid / postpaid) to retrieve the customer name and address.
  • UI — Show the customer the plan, bouquet or meter details and your retail price, and ask them to confirm.
  • API — Place the purchase with a unique request_ref (UUID recommended, ≤ 50 characters): POST /airtime/purchase, POST /data/purchase, POST /cabletv/purchase or POST /electricity/purchase. Your wallet is debited immediately. Never resubmit the same request_ref — it is rejected with 400; create a new reference for a new attempt.
  • API — Read the response status: successful (200) means delivered; failed (424) means the provider rejected it and your wallet has been refunded; pending (202) means the provider has not confirmed yet. For electricity, a successful prepaid purchase returns the meter token and units — show them to the customer.
  • Webhook/API — For a pending purchase, wait for the airtime.purchase.* or data.purchase.* webhook, or poll POST /transaction/status with your request_ref until status is successful or failed. Cable TV and electricity do not emit webhooks — poll the status endpoint.
  • API — Call POST /transaction/status at any time to retrieve a transaction’s final state, amount, and your wallet balance before and after the debit. Each call also re-sends a transaction.requery webhook.