Legacy: buy airtime
Token ds_live_ / ds_test_POST
/api/topupAirtime top-up in MSORG or Adex format. The format is detected from the body: Adex if it contains request-id or data_plan, or phone without mobile_number; otherwise MSORG.
Language
curl -X POST "https://finaldatasub.com/api/topup" \
-H "Authorization: Token ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"network": 1,
"amount": 500,
"mobile_number": "08031234567",
"Ported_number": true,
"airtime_type": "VTU",
"ident": "ORDER-10022"
}'Authentication
Send your secret API key in the header. Authorization: Bearer … and X-API-Key: … are also accepted.
| Header | Value | Required |
|---|---|---|
| Authorization | Token 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 |
|---|---|---|---|
| network | integer | string | Yes | Network id (see the tables in Overview) or name. |
| amount | number | Yes | Airtime value in Naira. |
| mobile_number | string | Yes | Recipient Nigerian number (Adex: phone). |
| ident | string | No | Your reference for safe retries, max 128 (also request_id; Adex: request-id). |
| Ported_number | boolean | No | Accepted for compatibility; ignored. |
| airtime_type | string | No | VTU (default), Share and Sell or awuf4U. Adex-style requests can send plan_type instead. |
Responses
201 Created — MSORG · 200 OK — Adex · 400 Bad Request — Error
{
"id": 88232,
"ident": "DS261005101830M2N8QW1T",
"network": 1,
"mobile_number": "08031234567",
"balance_before": "24520.00",
"balance_after": "24035.00",
"Status": "successful",
"api_response": "You have successfully topped up ₦500.00 on 08031234567.",
"create_date": "2026-10-05T10:18:30+01:00",
"Ported_number": true,
"amount": "500.00",
"paid_amount": "485.00",
"airtime_type": "VTU"
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| “Invalid network.” | 400 | network is missing or not a known id / name. |
| “A valid phone number is required.” | 400 | Phone does not match the Nigerian number format. |
| “Amount is required.” | 400 | amount is missing or not greater than zero. |
| “Airtime is not available for this network.” | 400 | No active airtime biller for this network. |
| “Insufficient wallet balance.” | 400 | Wallet balance too low (reported as 400, not 402). |
| Other purchase errors | 404 / 409 / 429 / 503 | Same message and HTTP status as the merchant API (e.g. service unavailable, limits, wallet busy). |
| Failed vend | 400 | MSORG Status: failed / Adex status: fail, with the transaction body. |
Adex request body
JSON
{
"network": 1,
"amount": 500,
"phone": "08031234567",
"request-id": "ORDER-10022"
}Notes
- Adex
amountis what you paid; MSORG returns the airtime value inamountand what you paid inpaid_amount.