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

# Airtime

> Top up any Nigerian mobile number. Discover the networks at runtime, then purchase.

Buy airtime for a phone number on any supported Nigerian network. Discover the networks with
`fetch-providers` rather than hardcoding them — the list changes without an API version bump.

## Get Airtime Networks

```
GET /api/v1/business/vas/airtime/fetch-providers
```

**Signature required:** No

### Request example

```bash theme={null}
curl -X GET "https://api.usenumero.com/numeroaccount/api/v1/business/vas/airtime/fetch-providers" \
  -H "X-Numero-Api-Key: your_api_key"
```

### Response

```json theme={null}
{
  "data": {
    "providers": [
      {
        "code": "MTN",
        "name": "MTN"
      },
      {
        "code": "GLO",
        "name": "Glo"
      },
      {
        "code": "AIRTEL",
        "name": "Airtel"
      },
      {
        "code": "9MOBILE",
        "name": "9mobile"
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}
```

Use `code` as the `network` value when you purchase.

## Buy Airtime

```
POST /api/v1/business/vas/airtime
```

**Signature required:** Yes

### Headers

| Header                       | Required | Description                                                                                         |
| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `X-Numero-Api-Key`           | Yes      | Your API key                                                                                        |
| `X-Numero-Signature`         | Yes      | HMAC-SHA256 of the raw request body — see [Request signing](/03-request-signing)                    |
| `X-Numero-Signature-Version` | Yes      | `v2`                                                                                                |
| `Idempotency-Key`            | Yes      | A unique string per purchase. Replaying it returns the original result instead of topping up twice. |

### Body

| Field       | Type   | Required | Description                                            |
| ----------- | ------ | -------- | ------------------------------------------------------ |
| `reference` | string | Yes      | Your own unique reference for this purchase            |
| `network`   | string | Yes      | Network `code` from `fetch-providers` (e.g. `MTN`)     |
| `phone`     | string | Yes      | The number to credit                                   |
| `amount`    | number | Yes      | Major units (naira, not kobo)                          |
| `service`   | string | No       | Optional service qualifier where a network exposes one |

<Note>
  `validationCode` and `transactionPin` are **not** used on this channel. The API key plus the request
  signature authorise a server-to-server purchase; there is no session to send a code to. Both remain in
  force on the merchant dashboard, which is a different channel.
</Note>

### Request example

```bash theme={null}
curl -X POST "https://api.usenumero.com/numeroaccount/api/v1/business/vas/airtime" \
  -H "X-Numero-Api-Key: your_api_key" \
  -H "X-Numero-Signature: your_signature" \
  -H "X-Numero-Signature-Version: v2" \
  -H "Idempotency-Key: 5f1c0b6e-9a2d-4c3a-8b7e-1f2a3b4c5d6e" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "AIR-20260810-0001",
    "network": "MTN",
    "phone": "08012345678",
    "amount": 500
  }'
```

### Response

```json theme={null}
{
  "data": {
    "message": "Purchase successful",
    "reference": "AIRTIME-20260810-001"
  },
  "error": null,
  "meta": {
    "request_id": "req_365123ebc73323f1482508560ce6400e",
    "pagination": null
  }
}
```

## Checking the outcome

A purchase can settle after the response returns. Poll
[`GET /business/vas/status`](/api-reference/vas-overview) with your `reference`, or handle the
`VAS_NOTIFICATION` webhook — do not treat the absence of an error as proof the top-up landed.

## Fees

Airtime carries a per-transaction fee on your account. Read the charge from the transaction record
rather than assuming a rate; pricing is per merchant.