# Bulk airtime

`POST https://api.paybeta.ng/v2/bulk-airtime`

Authentication: `P-API-KEY` header.

Queue airtime for every recipient in the list. Saves `batch_id` / `reference` for the other requests.

| Field | Required | Notes |
|---|---|---|
| reference | yes | your id for the whole request, unique per account |
| description | no | your label, max 100 chars |
| recipients | yes | 1 – 1,000 items |
| recipients[].biller | yes | `mtn` · `glo` · `airtel` · `9mobile` |
| recipients[].phone_number | yes | `2348031234567` (or `08031234567`) |
| recipients[].amount | yes | NGN50 – NGN20,000 |
| recipients[].reference | no | your id for this number; default `<reference>-<row>` |

## Body

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `reference` | string | yes |  |
| `description` | string | yes |  |
| `recipients` | array | yes |  |
| `recipients[].biller` | string | yes |  |
| `recipients[].phone_number` | string | yes |  |
| `recipients[].amount` | integer | yes |  |
| `recipients[].reference` | string | no |  |

## Request: Request body

```json
{
    "reference": "PAYROLL-{{$timestamp}}",
    "description": "October staff airtime",
    "recipients": [
        {
            "biller": "mtn",
            "phone_number": "2348031234567",
            "amount": 1000,
            "reference": "STAFF-{{$timestamp}}-ADA"
        },
        {
            "biller": "glo",
            "phone_number": "2348051234567",
            "amount": 500
        },
        {
            "biller": "airtel",
            "phone_number": "08021234567",
            "amount": 200
        }
    ]
}
```

## Response 201: Success

```json
{
    "status": "successful",
    "message": "Bulk airtime queued. 3 recipient(s) will be processed shortly.",
    "data": {
        "reference": "PAYROLL-OCT",
        "batch_id": "BLK-K3P9XQ2M7Z1A",
        "description": "October staff airtime",
        "status": "queued",
        "total_recipients": 3,
        "total_amount": 1700,
        "total_charge": 1644,
        "amount_charged": 0,
        "summary": {
            "successful": 0,
            "pending": 0,
            "failed": 0,
            "queued": 3,
            "cancelled": 0
        },
        "created_at": "2026-10-05T09:00:00+01:00",
        "started_at": null,
        "completed_at": null,
        "cancelled_at": null,
        "recipients": [
            {
                "row": 1,
                "reference": "STAFF-OCT-ADA",
                "biller": "mtn",
                "phone_number": "08031234567",
                "amount": 1000,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            },
            {
                "row": 2,
                "reference": "PAYROLL-OCT-2",
                "biller": "glo",
                "phone_number": "08051234567",
                "amount": 500,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            },
            {
                "row": 3,
                "reference": "PAYROLL-OCT-3",
                "biller": "airtel",
                "phone_number": "08021234567",
                "amount": 200,
                "charged_amount": null,
                "status": "queued",
                "response_description": null,
                "transaction_id": null,
                "processed_at": null
            }
        ]
    }
}
```

## Response 422: Error

```json
{
    "status": "failed",
    "message": "Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits).",
    "errors": {
        "recipients.2.phone_number": [
            "Recipient 3 phone_number must be 234 followed by 10 digits (or 0 followed by 10 digits)."
        ]
    }
}
```