Internal Services

Airtime API Kenya - Instant Mobile Top-up for Developers

Integrate instant Safaricom, Airtel, and Telkom airtime top-ups in Kenya with Statum API. Real-time recharge, webhook notifications, and discount pricing for developers.

With Statum's Airtime API, you can recharge mobile numbers across Kenya instantly. Whether you’re building apps to reward users, integrate airtime payments, or create innovative payment solutions, our API provides a fast, reliable, and seamless experience. Receive real-time SMS confirmations and detailed transaction reporting for complete visibility.

POST
https://api.statum.co.ke/api/v2/airtime

Why Developers Choose Statum Airtime API

Our API is optimized for reliability and high-speed fulfillment. We partner with the leading mobile network operators in Kenya to ensure your users get recharged instantly.

Competitive Discounts

Benefit from built-in discounts on every airtime purchase, allowing you to increase your profit margins when reselling.

Instant Fulfillment

Recharge Safaricom, Airtel, and Telkom numbers with sub-second delivery latency from our direct carrier hooks.

Unified Wallet

Use a single balance for all mobile operators. No need to manage separate accounts for Safaricom or Airtel.

Detailed Webhooks

Receive real-time delivery notifications for your transaction database without polling our API.

Use Cases

  • Micro-Payments: Efficient virtual airtime payments in emerging markets.
  • Incentivizing Users: Use airtime rewards for surveys, campaigns, or promotions.
  • Reselling: Build and scale airtime distribution businesses easily.
  • Rewards & Loyalty Programs: Offer airtime to reward loyal customers.
  • Emergency Services: Enable instant airtime top-ups in critical situations.

Idempotency

Airtime API Request

Make a POST request to the above endpoint with the following fields:

Parameter Type Required Description
phone_number String Yes Phone number in international format (e.g., 254722199199)
amount String Yes Top-up amount in KES

Implementation Example

PHP Implementation 
<?php
                $consumerKey = "568473daf6614cb196caeb5f8805985f";
                $consumerSecret = "5a07f41de16e40e4b08b4001142a5a10";
                $auth = base64_encode($consumerKey . ":" . $consumerSecret);

                $curl = curl_init();
                curl_setopt_array($curl, [
                CURLOPT_URL => 'https://api.statum.co.ke/api/v2/airtime',
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_FOLLOWLOCATION => true,
                CURLOPT_CUSTOMREQUEST => 'POST',
                CURLOPT_POSTFIELDS => json_encode([
                "phone_number" => "254721553678",
                "amount" => "50"
                ]),
                CURLOPT_HTTPHEADER => [
                "Authorization: Basic $auth",
                "Content-Type: application/json"
                ],
                ]);

                $response = curl_exec($curl);
                curl_close($curl);
                echo $response;
                ?>

Airtime API Response Format

Every request to the Statum Airtime API returns a structured JSON response. This allows your application to handle transaction states programmatically and provide immediate feedback to users.

Parameter Type Description Example
status_code Number Transaction status code 200
description String Status description Operation successful
request_id String Transaction reference ID 35235f08c981474abd388755ed43a427

Sample Response Payload

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

Real-time Airtime API Notifications (Webhooks)

To support high-volume transaction processing, Statum utilizes asynchronous webhooks. Configure a callback URL to receive instant notifications once an airtime top-up is finalized on the carrier network. The notification payload includes:

Parameter Type Description Example
request_id String Transaction reference ID 35235f08c981474abd388755ed43a427
charge Decimal Applied transaction charge 1.50
account_balance Decimal Balance after the transaction 5000.00
result_code String Transaction result code 200
result_desc String Description of transaction result You have topped up 254721553678 with Ksh. 50.

Sample Notification Payload

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

Sample PHP Callback Handler

Callback Handler 
<?php
                // Endpoint: /api/airtime/callback
                $input = file_get_contents('php://input');
                $payload = json_decode($input, true);

                // Log for audit
                file_put_contents('airtime_callback.log', print_r($payload, true), FILE_APPEND);

                // Process callback
                if ($payload['result_code'] === '200') {
                // Update transaction as successful
                echo json_encode(['status' => 'success']);
                } else {
                // Update transaction as failed
                echo json_encode(['status' => 'failed', 'reason' => $payload['result_desc']]);
                }
                ?>