Airtime Purchase

Send airtime top-up to any supported mobile number.

Endpoint

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

You can optionally append a reference for idempotency:

POST https://example.com/api/topup/{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
amount	numeric	Yes	Airtime amount in Naira. Minimum: 50, Maximum: 5,000
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

{
  "amount": 200,
  "mobile_number": "08101234567",
  "network": 1
}

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

Response

Success (200)

{
  "data": {
    "id": 1,
    "network": 1,
    "ident": "AT20260318123045123456",
    "amount": "200.00",
    "api_response": "Success",
    "description": "200 MTN Airtime to 08101234567",
    "plan_network": "N/A",
    "Status": "successful",
    "balance_before": "2,000.00",
    "balance_after": "1,800.00",
    "create_date": "18/03/2026 10:30 AM"
  }
}

Response Fields

Field	Type	Description
id	integer	Transaction ID
network	integer	Mobile network ID
ident	string	Unique transaction reference (prefixed with AT)
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": {
    "amount": ["The amount field is required."],
    "mobile_number": ["The mobile number field is required."],
    "network": ["The network field is required."]
  }
}

Error	Cause
"The amount field is required."	Missing amount parameter
"The amount must not be greater than 5000."	Amount exceeds ₦5,000 maximum
"The amount must be at least 50."	Amount is below ₦50 minimum
"The amount must be a number."	Non-numeric value provided
"The mobile number field is required."	Missing mobile_number parameter
"The network field is required."	Missing network parameter

Business Logic Errors (422)

If the purchase fails after processing, the error is thrown as a ValidationException:

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Something Went Wrong! Try again Letter"]
  }
}

Error Message	Field	Cause
"Insufficient wallet balance!"	amount	Not enough funds in your wallet
"Service unavailable!."	status	Airtime 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 airtime 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
"Something Went Wrong! Try again Letter"	status	Provider-level failure (generic)

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

• Airtime amount must be between ₦50 and ₦5,000
• Airtime discounts may apply based on your account level and the selected network
• Transaction amounts are deducted from your wallet balance
• If the transaction fails at validation, your wallet will not be debited