> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vtuagent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vtuagent.com/_mcp/server.

# Overview

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.

```yaml

          
```