Airtime Topup
The Airtime Top-Up API allows you to integrate airtime recharge functionality into your applications. It enables users to automatically send mobile airtime to a specified phone number across supported
Endpoint
POST https://backendapi.sayswitchgroup.com/api/v1/airtime/topup
Sample cURL Request
curl -X POST https://backendapi.sayswitchgroup.com/api/v1/airtime/topup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-d '{
"provider": "MTN",
"number": "08012345678",
"amount": "100",
"reference": "merchant-order-10001"
}'Sample Response
{
"success": true,
"code": "00000",
"message": "SUCCESSFUL",
"data": {
"orderNo": "17484753663740358984353674",
"reference": "2022009802414346",
"status": "delivered",
"errorMsg": "TRANSACTION SUCCESSFUL",
"amount": 100,
"discount": 0,
"fee": 0,
"totalDebited": 100
}
}Response Explanation
| Key | Type | Description |
|---|---|---|
| success | boolean | Indicates whether the top-up was successful (true or false). |
| code | string | A system-generated status code. “00000” means the transaction was OK. |
| message | string | General message about the transaction result. |
| data | object | Contains the transaction result details. |
| orderNo | string | Unique transaction ID for internal tracking. |
| reference | string | A unique reference ID for the user or client to track the transaction. |
| status | string | Delivery status (delivered, pending, failed). |
| errorMsg | string | Description of the result, useful for debugging or user messaging. |
| amount | number | Airtime face value delivered to the recipient. |
| discount | number | Discount granted to the merchant. |
| fee | number | Bill-payment fee charged to the merchant. |
| totalDebited | number | Authoritative amount removed from the NGN wallet: amount + fee - discount. |
A pending purchase returns HTTP 202 with status: "pending". Do not submit it again; query the original reference using Status and reconciliation.