Bulk airtime
Bearer ds_live_ / ds_test_POST
/api/v1/merchant/airtime/bulkQueues airtime for a list of numbers. Set one amount for everyone, or pass objects with their own amount.
Language
curl -X POST "https://finaldatasub.com/api/v1/merchant/airtime/bulk" \
-H "Authorization: Bearer ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"reference": "BULK-AIRTIME-0008",
"network": "MTN",
"amount": 200,
"recipients": [
"08031234567",
{
"phone": "08123456789",
"amount": 500
}
]
}'Authentication
Send your secret API key in the header. Authorization: Token … and X-API-Key: … are also accepted.
| Header | Value | Required |
|---|---|---|
| Authorization | Bearer ds_live_YOUR_KEY | Yes |
| Content-Type | application/json | Yes |
| Accept | application/json | Recommended |
Authentication failures (401 UNAUTHORIZED, 403 IP_NOT_ALLOWED / ACCOUNT_SUSPENDED / API_ACCESS_NOT_APPROVED, 429 RATE_LIMITED) are listed in Authentication.
Parameters
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
| reference | string | Yes | Unique order reference (max 100 chars). |
| network | string | Yes | MTN, GLO, AIRTEL or 9MOBILE (or an airtime biller slug). |
| recipients | array | Yes | Phone strings or { "phone": "…", "amount": 500 } objects. Max 100 per order by default. |
| amount | number | Conditional | Default amount for recipients without their own amount (min 1). |
| airtime_type | string | No | VTU (default), Share and Sell or awuf4U. Each type is priced separately; check airtime_type on the airtime billers in List billers. |
Responses
202 Accepted — Accepted
{
"status": "pending",
"message": "Bulk airtime order received. 2 number(s) are being processed.",
"data": {
"id": 58,
"reference": "BULK-AIRTIME-0008",
"category": "airtime",
"status": "processing",
"total_items": 2,
"successful": 0,
"pending": 2,
"failed": 0,
"total_charged": "0.00",
"created_at": "2026-10-05T10:20:00+01:00",
"completed_at": null
}
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| TOO_MANY_RECIPIENTS | 400 | More numbers than allowed in one order (100 by default). |
| INVALID_RECIPIENTS | 400 | One or more phone numbers are invalid (positions are listed in the message). |
| INSUFFICIENT_BALANCE | 402 | Your wallet does not cover the full order estimate. |
| DUPLICATE | 409 | This bulk reference was already used. The existing order is returned in data. |
| AMOUNT_REQUIRED | 400 | A recipient has no amount and no default amount was sent. |
| BILLER_NOT_FOUND | 404 | Unknown or inactive biller / network. |
Notes
- Each number is vended as its own transaction with reference
<reference>-1,<reference>-2, … so retries never double-charge. Look them up with GET /transactions/{reference}. - Your wallet must cover the full estimated order up front, but each number is only debited when it is vended.
- Track progress with GET /bulk/{id}.