Send Airtime

Sending airtime sample code

The PHP code snippet below shows how to send airtime.

The code uses our PHP SDK.

<?php
require 'vendor/autoload.php';
use AfricasTalking\SDK\AfricasTalking;

// Set your app credentials
$username = "MyAppUsername";
$apikey   = "MyAppAPIKey";

// Initialize the SDK
$AT       = new AfricasTalking($username, $apiKey);

// Get the airtime service
$airtime  = $AT->airtime();

// Set the phone number, currency code and amount in the format below
$recipients = [[
    "phoneNumber"  => "+254711XXXYYY",
    "currencyCode" => "KES",
    "amount"       => 100
], [
    "phoneNumber"  => "+254733YYYZZZ",
    "currencyCode" => "KES",
    "amount"       => 1000
]];

try {
    // That's it, hit send and we'll take care of the rest
    $results = $airtime->send([
        "recipients" => $recipients
    ]);

    print_r($results);
} catch(Exception $e) {
    echo "Error: ".$e->getMessage();
}

Send airtime by making a HTTP POST request to one of the following endpoints:

Endpoints

Live: https://api.africastalking.com/version1/airtime/send
Sandbox: https://api.sandbox.africastalking.com/version1/airtime/send

Request Parameters

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

Parameter Description
username
String
Required
Your Africa's Talking application username.
recipients
String
Required
A url encoded json list of Recipient, the format of this string is: '[{"phoneNumber":"+254711XXXYYY","amount":"KES X"}]'
Recipient is a Map with the following parameters:
  • phoneNumberString
    Required: The phone number that will be topped up in international format (e.g +234811222333).
  • amount String
    Required: The value of airtime to send together with the currency code. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g 'KES 1.50'

API Response

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

Parameter Description
numSent
Integer
The number of requests sent to the provider
totalAmount
String
The total value of airtime sent to the provider. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g 'KES 1000.00'
totalDiscount
String
The total discount applied on the airtime. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g 'KES 40.00'
responses
List
A list with multiple Entry each corresponding to an individual airtime transaction result.
Entry is a Map with details of an airtime transaction result.
  • phoneNumber: String The phone number for this transaction.
  • amount: String The value of airtime requested. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g 'KES 500.00'
  • discount: String The discount applied to the requested airtime amount. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g 'KES 1.50'
  • status: String The status of the request associated to this phone number. Will either be Sent or Failed.
  • requestId: String A unique id for the request associated to this phone number. This is only generated if the status of the request is Sent. If the status is Failed this will have the special value "None"
  • errorMessage: String The error message for the request associated to this phone number. This is only generated if the status of the request is Failed. If the status is Sent this will have the special value "None"
errorMessage
String
Optional
Error message if the ENTIRE request was rejected by the API.
Upon successful processing, the server shall respond in the following format:
{
    "errorMessage": "None",
    "numSent": 1,
    "totalAmount": "KES 1000.0000",
    "totalDiscount": "KES 40.0000",
    "responses": [{
        "phoneNumber": "+254711XXXYYY",
        "errorMessage": "None",
        "amount": "KES 1000.0000",
        "status": "Sent",
        "requestId": "ATQid_1be914ac47845eef1a1dab5d89ec50ff",
        "discount": "KES 40.0000"
    }]
}

Request Limits

There are a number of limits implemented on our airtime APIs.

Value Limits

Limits on the value of each airtime transaction. They are as follows:

Country Limit
Kenya Lower - KES 5
Upper - KES 10,000
Uganda Lower - UGX 50
Upper - UGX 200,000
Tanzania Lower - TZS 500
Upper - TZS 200,000
Nigeria Lower - NGN 50
Upper - NGN 5,000

Recipient Limits

Limits on the number of airtime recipients you can send in one request. Our APIs will only accept up to 1,000 recipients in a single request.

Idempotency Limits

In order to prevent unintentional duplicates, our APIs will reject similar airtime requests that are sent within 5 Minutes of each other. If you actually want to send duplicate requests within the 5 minute window, you can use the Idempotency Keys in the requests header to force subsequent requests through.

Rate Limits

Our APIs allow a maximum of 500 simulteneous connections from each IP Address. There are no per-second rate limiting on the requests.