Data Purchase

Purchase data bundles for any supported mobile network.

Endpoint

POST https://example.com/api/data

You can optionally append a reference for idempotency:

POST https://example.com/api/data/{ref}

Rate Limit: 30 requests per minute.

Request Headers

{
  "Accept": "application/json",
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}

Request Body

Field	Type	Required	Description
plan	integer	Yes	Data plan ID from the database — see Data Plans
mobile_number	string	Yes	Recipient phone number (e.g., "08101234567")
network	integer	Yes	Network ID: 1 = MTN, 2 = Glo, 3 = 9mobile, 4 = Airtel

Example Request

{
  "plan": 12,
  "mobile_number": "08101234567",
  "network": 1
}

curl -X POST https://example.com/api/data \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "plan": 12,
    "mobile_number": "08101234567",
    "network": 1
  }'

Response

Success (200)

{
  "data": {
    "id": 1,
    "network": 1,
    "ident": "DT20260318123045123456",
    "amount": "230.00",
    "api_response": "Success",
    "description": "1GB Data MTN to 08101234567",
    "plan_network": "N/A",
    "Status": "successful",
    "balance_before": "2,000.00",
    "balance_after": "1,770.00",
    "create_date": "18/03/2026 10:30 AM"
  }
}

Failed Transaction (422)

If the purchase is processed but fails at the provider level:

{
  "data": {
    "id": 2,
    "network": 1,
    "ident": "DT20260318123045789012",
    "amount": "230.00",
    "api_response": "Provider error message",
    "description": "1GB Data MTN to 08101234567",
    "plan_network": "N/A",
    "Status": "failed",
    "balance_before": "2,000.00",
    "balance_after": "1,770.00",
    "create_date": "18/03/2026 10:31 AM"
  }
}

Response Fields

Field	Type	Description
id	integer	Transaction ID
network	integer	Mobile network ID
ident	string	Unique transaction reference (prefixed with DT)
amount	string	Amount charged (formatted with 2 decimals)
api_response	string	Provider response message, or "N/A"
description	string	Human-readable transaction description
plan_network	string	Always "N/A"
Status	string	"successful", "pending", or "failed"
balance_before	string	Wallet balance before transaction
balance_after	string	Wallet balance after transaction
create_date	string	Transaction timestamp (format: DD/MM/YYYY hh:mm AM/PM)

Error Handling

Validation Error (422)

Returned when request fields fail validation:

{
  "message": "The given data was invalid.",
  "errors": {
    "plan": ["The plan field is required."],
    "mobile_number": ["The mobile number field is required."],
    "network": ["The network field is required."]
  }
}

Error	Cause
"The plan field is required."	Missing plan parameter
"The selected plan is invalid."	Plan ID does not exist in the database
"The mobile number field is required."	Missing mobile_number parameter
"The network field is required."	Missing network parameter

Business Logic Errors (422)

These errors are returned under the errors key with a status or amount field:

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Insufficient wallet balance!"]
  }
}

Error Message	Field	Cause
"Insufficient wallet balance!"	amount	Not enough funds in your wallet
"Service unavailable!."	status	Data service is currently disabled
"Your account has been restricted for transaction, Please submit your KYC to activate your account or contact support!."	status	Account KYC restriction
"Sorry, your daily data spending limit exceeded! Limit: ₦X"	status	Daily spending limit reached
"Your account has been temporarily restricted due to a negative wallet balance."	status	Negative balance on account

Unauthorized (401)

Returned when the Bearer token is missing or invalid.

IP Whitelist Denied (403)

{
  "status": false,
  "message": "Access Denied: Your IP (x.x.x.x) or Origin is not whitelisted for this API token."
}

Notes

• Use the Data Plans endpoint to retrieve available plan IDs
• The plan value must be a valid integer ID from the data plans table
• Transaction amounts are deducted from your wallet balance
• If the transaction fails at validation, your wallet will not be debited