> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abcmpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VTU

> Airtime, data, cable TV, electricity, and exam pins

Buy airtime, data, cable TV subscriptions, electricity tokens, and exam pins directly via API. Every purchase debits your wallet first, then either confirms, is left `processing` (for providers that confirm asynchronously), or fails and is **automatically refunded** to your wallet.

<Note>
  VTU is enabled per-merchant. If it isn't enabled on your account, these endpoints return a `SERVICE_NOT_ENABLED` error — contact support to request access.
</Note>

<Info>
  Unlike other ABCMPay endpoints, VTU's `reference` is **generated by us**, not sent by you — it comes back in the purchase response. Save it to poll [Check VTU Transaction Status](#check-vtu-transaction-status).
</Info>

## Buy Airtime

**POST** `/api/v1/vtu/airtime`

<ParamField body="network" type="string" required>
  One of: `mtn`, `glo`, `airtel`, `9mobile`.
</ParamField>

<ParamField body="phone" type="string" required>
  Recipient phone number.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount in Naira (min ₦50, max ₦50,000).
</ParamField>

<ParamField body="airtime_type" type="string" default="VTU">
  `VTU` or `Sharesell`.
</ParamField>

```bash theme={null}
curl -X POST "https://www.abcmpay.com/api/v1/vtu/airtime" \
  -H "X-Api-Key: your-public-key" \
  -H "X-Api-Secret: your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "mtn",
    "phone": "08012345678",
    "amount": 500
}'
```

```json Response theme={null}
{
    "success": true,
    "status": "success",
    "message": "Transaction successful.",
    "reference": "VTU-AIR-20260215120000-K3F9QZ",
    "token": null
}
```

This same response shape (`success`, `status`, `message`, `reference`, `token`) is returned by every purchase endpoint below.

| `status`     | Meaning                                                                                |
| ------------ | -------------------------------------------------------------------------------------- |
| `success`    | Confirmed immediately                                                                  |
| `processing` | Sent to the provider, confirming asynchronously — poll status or wait for it to settle |
| `fail`       | Failed — wallet already refunded                                                       |

***

## Data

**GET** `/api/v1/vtu/data-plans?network={network}`

Returns available data plans, each with the `id` you pass as `data_plan_id` below. `network` is optional and filters the list.

**POST** `/api/v1/vtu/data`

<ParamField body="phone" type="string" required>
  Recipient phone number.
</ParamField>

<ParamField body="data_plan_id" type="integer" required>
  Plan ID from [Get Data Plans](#data).
</ParamField>

***

## Cable TV

**GET** `/api/v1/vtu/cable-plans?provider_name={provider}`

Returns available cable plans (DSTV, GOTV, Startimes). `provider_name` is optional.

**POST** `/api/v1/vtu/cable`

<ParamField body="cable_plan_id" type="integer" required>
  Plan ID from [Get Cable Plans](#cable-tv).
</ParamField>

<ParamField body="smart_card_number" type="string" required>
  Smart card / IUC number.
</ParamField>

<ParamField body="phone" type="string">
  Customer phone number.
</ParamField>

***

## Electricity

**GET** `/api/v1/vtu/discos`

Returns supported electricity providers (discos).

**POST** `/api/v1/vtu/electricity`

<ParamField body="disco_id" type="integer" required>
  Disco ID from [Get Discos](#electricity).
</ParamField>

<ParamField body="meter_number" type="string" required>
  Meter number.
</ParamField>

<ParamField body="meter_type" type="string" required>
  `Prepaid` or `Postpaid`.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount in Naira (min ₦500, max ₦100,000).
</ParamField>

<ParamField body="customer_name" type="string" />

<ParamField body="customer_address" type="string" />

<ParamField body="customer_phone" type="string" />

<Tip>
  On success, `token` in the response carries the prepaid meter token — the only endpoint where that field is populated.
</Tip>

***

## Exam Pins

**GET** `/api/v1/vtu/exam-types`

Returns supported exam types (WAEC, NECO, etc.), each with a `selling_price`.

**POST** `/api/v1/vtu/exam`

<ParamField body="exam_type_id" type="integer" required>
  Exam type ID from [Get Exam Types](#exam-pins).
</ParamField>

<ParamField body="quantity" type="integer" required>
  Number of pins (1–20).
</ParamField>

***

## Check VTU Transaction Status

**GET** `/api/v1/vtu/transaction/status?reference={reference}`

Use the `reference` returned from any purchase endpoint above.

```json Response theme={null}
{
    "success": true,
    "reference": "VTU-AIR-20260215120000-K3F9QZ",
    "type": "debit",
    "service": "airtime",
    "status": "Success",
    "amount": 500,
    "description": "VTU Airtime (mtn) to 08012345678",
    "date": "2026-02-15T12:00:00Z"
}
```