Airtime Disbursement API

Statum's Airtime Disbursement API enables developers to programmatically distribute airtime to mobile subscribers in Kenya. Supporting Safaricom, Airtel, and Telkom carriers from a unified balance, our API facilitates automatic customer rewards, promotional payouts, micro-loans, and automated top-up services with sub-second fulfillment latency.

Integrate our RESTful API endpoint to automate your virtual airtime top-up flows. Send HTTP POST requests securely authenticated using Basic Auth headers.

Why Developers Choose Statum Airtime API

Our top-up gateway is optimized for maximum uptime, high volume, and speed. We hook directly into telco core systems, ensuring transactions are settled instantly.

Use Cases

• Marketing & User Incentives: Distribute airtime instantly to reward users who complete surveys, download mobile apps, or participate in marketing campaigns.
• Micro-Disbursements: Offer virtual value payouts in gaming, digital finance, or lottery applications.
• Corporate Utility Allocation: Automate weekly or monthly airtime top-ups for sales reps, field staff, or support teams directly from your system.
• Retail Reselling Networks: Build and scale your own airtime selling websites, Android apps, or WhatsApp bots to retail top-ups.

Mobile Number Portability (MNP) in Kenya

Kenya supports Mobile Number Portability, meaning a subscriber can migrate from Airtel to Safaricom while keeping their original prefix (e.g. 0733* or 0722*). Statum's intelligent routing engine automatically queries carrier portability registries. We route the top-up transaction to the correct active carrier network without requiring manual intervention from your team.

Transaction Safety & Idempotency

Airtime API Request Parameters

Send a POST request containing a JSON body with the following parameters:

Request Implementation Example

curl -X POST https://api.statum.co.ke/api/v2/airtime \
  -H "Authorization: Basic MmJlOTg5ZD...==" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "254721553678",
    "amount": "50"
  }'

$consumerKey = "YOUR_CONSUMER_KEY";
$consumerSecret = "YOUR_CONSUMER_SECRET";
$auth = base64_encode($consumerKey . ":" . $consumerSecret);

$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.statum.co.ke/api/v2/airtime', [
    'headers' => [
        'Authorization' => 'Basic ' . $auth,
        'Content-Type'  => 'application/json'
    ],
    'json' => [
        'phone_number' => '254721553678',
        'amount'       => '50'
    ]
]);

$result = json_decode($response->getBody()->getContents(), true);

const axios = require('axios');
const auth = Buffer.from('YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET').toString('base64');

axios.post('https://api.statum.co.ke/api/v2/airtime', {
    phone_number: '254721553678',
    amount: '50'
}, {
    headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Airtime API Response Format

Upon receiving your request, the gateway replies synchronously with a JSON status structure indicating the transaction has been queued:

Sample Response Payload

{
    "status_code": 200,
    "description": "Operation successful.",
    "request_id": "35235f08c981474abd388755ed43a427"
}

Asynchronous Webhook Callbacks

Once the mobile network operator confirms the top-up fulfillment, our gateway pushes an HTTP POST webhook containing the details to your callback URL:

Sample Webhook Payload

After an airtime disbursement is processed on the mobile networks (Safaricom, Airtel, or Telkom), our system sends a POST request containing a JSON payload to your registered callback URL. This allows your app to verify final delivery, audit charges, and update local user balances dynamically.

{
    "request_id": "35235f08c981474abd388755ed43a427",
    "charge": 48.5,
    "account_balance": 5000,
    "result_code": "200",
    "result_desc": "You have topped up 254721553678 with Ksh. 50."
}

Sample Callback Handler Implementation

Your callback listener must be set up to accept incoming HTTP POST payloads with a Content-Type: application/json header. The script should verify the transaction using the request_id, update database ledger details, and return an HTTP status code 200 OK within 3 seconds to confirm successful webhook handling.

<?php
// Route target: https://yourdomain.com/api/airtime/callback
$input = file_get_contents('php://input');
$payload = json_decode($input, true);

if (!$payload) {
    http_response_code(400);
    exit();
}

$requestId = $payload['request_id'];
$resultCode = $payload['result_code'];

if ($resultCode === '200') {
    // Airtime disbursement completed successfully. Update local wallet ledger.
    updateTransactionStatus($requestId, 'success', $payload['charge']);
} else {
    // Airtime disbursement failed. Reverse client action and log error.
    updateTransactionStatus($requestId, 'failed', 0, $payload['result_desc']);
}

http_response_code(200);
echo json_encode(['status' => 'acknowledged']);
?>