Send Airtime

You need your AfricasTalking username and APIKey for any request to our API. If you don't have an APIKey, you can generate one from your applications settings page.

The Ruby and Rails code snippet below shows how to send airtime using our API.

The code uses our Ruby and Rails gateway class: AfricasTalkingGateway.rb [ Download]

# Include the helper gateway class
require './AfricasTalkingGateway'

# Specify your login credentials
username = "MyAppUsername";
apikey   = "MyAppAPIKey";

#Create an array to hold all the recipients
recipients =

#Add the first recipient
recipients[0] = {"phoneNumber" => "+254711XXXYYY", "amount" => "KES XX"}

#Another reciepient
recipients[1] = {"phoneNumber" => "+254733YYYZZZ", "amount" => "KES YY"}

# Create a new instance of our awesome gateway class
gateway =, apikey)

# Any gateway errors will be captured by our custom Exception class below,
# so wrap the call in a try-catch block
  # Thats it, hit send and we'll take care of the rest.
  results = gateway.sendAirtime(recipients)
  results.each {|x|
    # Note that only the Status "Success" means the airtime was sent
    puts 'number=' + x.phoneNumber + '; status=' + x.status + '; requestId=' + x.requestId + '; amount=' + x.amount + "; discount=" +
	#incase the status is not equal to success, it is important to list the error message
	puts 'ErrorMessage=' + x.errorMessage
rescue AfricasTalkingGatewayException => ex
  puts 'Encountered an error: ' + ex.message


To send airtime you will need to make a HTTP POST request to the following url:


We however have a limit of the amount you can send as shown below:

Minimum amount Maximum amount
KES 10 KES 10,000
The server expects:
Parameter Location Description Required
API key Header API key generated from your account settings Yes
Accept Header This is the format you would like your data formatted. It may be application/xml or application/json. The default is application/xml. The gateway classes provided uses appliaction/json. No
username Body This is your Africa'sTalking username Yes
recipients Body Contains the a list of airtime recipients in JSON format. It should look like:
[{"phoneNumber":"+254711XXXYYY","amount":"KES X"},{"phoneNumber":"+254733YYYZZZ","amount":"KES Y"}]
Upon successful processing, the server shall respond in the following format:
<?xml version="1.0"?>
    <totalAmount>KES XXX</totalAmount>
    <totalDiscount>KES YYY</totalDiscount>
        <amount>KES 1000.0000</amount>
        <amount>KES 2000.0000</amount>

 "numSent": n,
 "totalAmount": "KES XXX",
 "totalDiscount" : "KES YYY",
 "responses" : [
        "amount":"KES 1000",
        "amount":"KES 2000",