Statum Company Logo

Airtime API

Top-up mobile users in Kenya and in real-time!

The Airtime API recharges or tops up the airtime credit on your customer's phone from the float in your developer account. The customer gets an airtime top up SMS confirmation on their phone on recharge.

We have a simple integration which does not require any setup on your end, you can literally top up numbers in minutes. Create an account, load float and start topping up!

The API can be used in Payment Solutions where you pay people with Airtime allowance, you just send it directly to their phone! They can also be used as incentives in platforms such as those that do surveys. This attracts people to participate in the survey.

Idempotency

Our APIs protect your application against cases where you might end up sending unintended repeat requests. In order to prevent unintentional duplicates, our APIs will reject similar airtime requests that are sent within 5 Minutes of each other. This could be caused by a communication breakdown (mainly network issues) or your application having broken logic.

HTTP POST Resource URL

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

API Request

Buy airtime through your application by making a HTTP POST request to the endpoint above.

In addition to the API standard request headers , the body of the request should contain the following fields:

Parameter Type Description Example
phone_number String The phone number that will be topped up in international format. 254722199199
amount String Amount of airtime to buy in Kenya Shillings. 50

Sample Airtime API request

<?php

$curl = curl_init();

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

$response = curl_exec($curl);

curl_close($curl);
echo $response;

API response

The body of the response will be a JSON object containing the following fields:

Parameter Type Description Example
status_code Number The status code of the transaction. 200
description String The status description of the transaction. Operation successful
request_id String The unique reference number as assigned by the Statum API 35235f08c981474abd388755ed43a427

Sample API response payload

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

API result

The Airtime API sends a notification when a specific event happens. For example, when the airtime is delivered to the recipient successfully, we immediately let you know via a notification with the details of that transaction. To receive these notifications you need to setup a callback URL on your developer account.

The POST parameters that will be passed will be as follows:

Parameter Type Description Example
request_id String The unique reference number as assigned by the Statum API 35235f08c981474abd388755ed43a427
result_code String The result code of the transaction. 200
result_desc String The result description of delivery status. You have topped up 254721553678 with Ksh. 50.

Sample API result payload

{
  "result_code": "200",
  "result_desc": "You have topped up 254721553678 with Ksh. 50.",
  "request_id": "35235f08c981474abd388755ed43a427"
}
Copyright © 2021 Statum Ltd