Legacy: buy data
Token ds_live_ / ds_test_POST
/api/dataData purchase 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/data" \
-H "Authorization: Token ds_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"network": 1,
"plan": 212,
"mobile_number": "08031234567",
"Ported_number": true,
"ident": "ORDER-10021"
}'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 |
|---|---|---|---|
| plan | integer | Yes | Plan id (Adex: data_plan). |
| mobile_number | string | Yes | Recipient Nigerian number (Adex: phone). |
| network | integer | string | No | Network id (see the tables in Overview) or name. When sent, it must match the plan's network. |
| ident | string | No | Your reference for safe retries, max 128 (also request_id; Adex: request-id). |
| Ported_number | boolean | No | Accepted for compatibility; ignored. |
Responses
201 Created — MSORG · 200 OK — Adex · 400 Bad Request — Error
{
"id": 88231,
"ident": "DS261005101522K7Q2ZP4M",
"network": 1,
"mobile_number": "08031234567",
"balance_before": "25000.00",
"balance_after": "24520.00",
"Status": "successful",
"api_response": "You have successfully purchased MTN SME 1GB - 30 Days for 08031234567.",
"create_date": "2026-10-05T10:15:22+01:00",
"Ported_number": true,
"plan": 212,
"plan_name": "MTN SME 1GB - 30 Days",
"plan_amount": "480.00"
}Errors
Errors specific to this endpoint, in addition to the authentication and validation errors common to every request.
| Code | HTTP | When |
|---|---|---|
| “Plan id is required.” | 400 | plan / data_plan is missing or not numeric. |
| “A valid phone number is required.” | 400 | Phone does not match the Nigerian number format. |
| “Invalid data plan for the selected network.” | 400 | Unknown plan, or network does not match it. |
| “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,
"data_plan": 212,
"phone": "08031234567",
"request-id": "ORDER-10021"
}Notes
- MSORG responses: 201 for successful and processing, 400 for failed. Adex responses: 200 for success and process, 400 for fail.
- In MSORG responses
identis FinalDataSub's transaction reference, not the ident you sent. Useidwith GET /api/data/{id}.