> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.vtuagent.com/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vtuagent.com/_mcp/server. # API Reference ## Docs - [Webhook](https://docs.vtuagent.com/api-reference/overview/webhook.md) ## API Docs - VTUAgent Consumable API > Airtime [Purchase Airtime](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/airtime/purchase-airtime.md) - VTUAgent Consumable API > Data [Fetch Data Plans](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/data/fetch-data-plans.md) - VTUAgent Consumable API > Data [Purchase Data Bundle](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/data/purchase-data-bundle.md) - VTUAgent Consumable API > Cable Tv [Fetch Cable TV Packages](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/cable-tv/fetch-cable-tv-packages.md) - VTUAgent Consumable API > Cable Tv [Verify Cable TV Smartcard / IUC Number](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/cable-tv/verify-cable-tv-smartcard-iuc-number.md) - VTUAgent Consumable API > Cable Tv [Purchase Cable TV Subscription](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/cable-tv/purchase-cable-tv-subscription.md) - VTUAgent Consumable API > Electricity [Verify Electricity Meter Number](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/electricity/verify-electricity-meter-number.md) - VTUAgent Consumable API > Electricity [Purchase Electricity Units](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/electricity/purchase-electricity-units.md) - VTUAgent Consumable API > Transaction [Query Transaction Status](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/transaction/query-transaction-status.md) - VTUAgent Consumable API > Webhooks [Set Webhook URL](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/webhooks/set-webhook-url.md) - VTUAgent Consumable API > Webhooks [Get Webhook URL](https://docs.vtuagent.com/api-reference/vtu-agent-consumable-api/webhooks/get-webhook-url.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://docs.vtuagent.com/api-reference/openapi.json) - [OpenAPI YAML](https://docs.vtuagent.com/api-reference/openapi.yaml) > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.vtuagent.com/api-reference/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 ```