Api reference
Send Airtime / Top-up
Send airtime or top-up mobile credit via the Bridge API
Send Airtime / Top-up
Send airtime to a customer number on a supported mobile network. The API accepts the request and processes it asynchronously; final status is delivered to your callback URL.
Endpoint
POST https://api.bridgeagw.com/send_airtimeRequest Headers
Authorization: Basic <base64_encoded_credentials>
Content-Type: application/jsonRequest Body
{
"service_id": 55,
"reference": "Test payment",
"transaction_id": "ksnyew2kei4a-alnlapk-uou",
"trans_type": "ATP",
"amount": 5,
"customer_number": "0244000001",
"nw": "MTN",
"callback_url": "https://webhook.site/0b429e73-ce5c-420b-af82-a346fb577c43",
"request_time": "2025-10-03 23:50"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
service_id | integer | Yes | Your service identifier |
reference | string | Yes | Transaction reference or description |
transaction_id | string | Yes | Unique transaction identifier |
trans_type | string | Yes | Must be ATP for airtime / top-up |
amount | number | Yes | Airtime amount |
customer_number | string | Yes | Recipient phone number (MSISDN) |
nw | string | Yes | Mobile network code (e.g. MTN, VOD, AIR) |
callback_url | string | Yes | URL for asynchronous status notifications |
request_time | string | Yes | Request timestamp |
Supported Networks (nw)
Use the same network codes as mobile money collections:
| Network | Code |
|---|---|
| MTN Mobile Money | MTN |
| Telecel Cash | VOD |
| AirtelTigo Money | AIR |
Response
Accepted (202)
{
"response_message": "Request successfully received for processing",
"response_code": "202"
}Example Usage
curl -X POST "https://api.bridgeagw.com/send_airtime" \
-H "Authorization: Basic <your_credentials>" \
-H "Content-Type: application/json" \
-d '{
"service_id": 55,
"reference": "Test payment",
"transaction_id": "ksnyew2kei4a-alnlapk-uou",
"trans_type": "ATP",
"amount": 5,
"customer_number": "0244000001",
"nw": "MTN",
"callback_url": "https://your-site.com/webhook/airtime-status",
"request_time": "2025-10-03 23:50"
}'const response = await fetch('https://api.bridgeagw.com/send_airtime', {
method: 'POST',
headers: {
'Authorization': 'Basic <your_credentials>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
service_id: 55,
reference: "Test payment",
transaction_id: "ksnyew2kei4a-alnlapk-uou",
trans_type: "ATP",
amount: 5,
customer_number: "0244000001",
nw: "MTN",
callback_url: "https://your-site.com/webhook/airtime-status",
request_time: "2025-10-03 23:50"
})
});
const result = await response.json();
console.log(result);import requests
url = "https://api.bridgeagw.com/send_airtime"
headers = {
"Authorization": "Basic <your_credentials>",
"Content-Type": "application/json"
}
data = {
"service_id": 55,
"reference": "Test payment",
"transaction_id": "ksnyew2kei4a-alnlapk-uou",
"trans_type": "ATP",
"amount": 5,
"customer_number": "0244000001",
"nw": "MTN",
"callback_url": "https://your-site.com/webhook/airtime-status",
"request_time": "2025-10-03 23:50"
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)Sandbox testing
In sandbox mode, airtime (trans_type: "ATP") uses the same MSISDN allowlist as mobile money payments. Only the allowlisted numbers below work; real or non-allowlisted numbers return 019. See the API Reference sandbox overview for the full list.
| Scenario | customer_number | nw | Expected response_code | Callback sent? |
|---|---|---|---|---|
| Success (MTN) | 0244000001 | MTN | 202 | Yes → 000/SUCCESS |
| Success (Vodafone) | 0200000002 | VOD | 202 | Yes → 000/SUCCESS |
| Success (AirtelTigo) | 0270000003 | AIR | 202 | Yes → 000/SUCCESS |
| Failure | 0244000009 | MTN | 015 | No |
| Invalid | 0540010000 | MTN | 019 | No |
| Limit exceeded | 0244000001 | MTN | 016 (amount > 10000) | No |
Example sandbox request:
{
"service_id": 12345,
"reference": "Airtime top-up",
"transaction_id": "ATP-SANDBOX-001",
"trans_type": "ATP",
"amount": 5,
"customer_number": "0244000001",
"nw": "MTN",
"callback_url": "https://your-site.com/webhook/airtime-status",
"request_time": "2026-01-15T14:30:00Z"
}Callbacks
After you receive 202, rely on your callback_url for final status. See Callbacks.