- Introduction
- Get Started
- Authorization
- Get API Credentials
- How It Works
- Making API Calls
- Airtime
- Send Airtime
- Buy Airtime
- Agent Float
- Send Agent Float
- Messaging
- Send SMS
- Channels
- Get Balance
- Get Product
Tops up the mobile of the recipient with airtime. The recipient receives the airtime and an SMS upon successful recharge.
Once completed, an Instant Callback Notification or webhook status event is sent to the endpoint URLs set to listen.
Once completed, an Instant Callback Notification or webhook status event is sent to the endpoint URLs set to listen.
Endpoint
POST https://app.topups.co.ke/api/send_airtime LIVE
Request
Parameter Example | |
---|---|
Headers | |
Accept
application/json
String | Optional The format of the response body. Options are:
|
|
Authorization
Bearer a12f4f9a99be83f1e631e379834864e7
String | Required The API token used for authorizing the API call as Bearer token. |
|
Content-Type
application/json
String | Optional The format of the request body. Options are:
|
|
Body | |
country
KE
String | Optional Country code of the recipient. In 2 letter international ISO format. Options are:
|
|
network
Safaricom
String | Optional Mobile network of the recipient. Options are:
|
|
name
Jane Wanjiku
String | Optional Name of the recipient. Useful for auto updating your contacts list. |
|
mobile
254722000000
Integer | Required Mobile number of the recipient to airtime transaction. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX |
|
email
jane.wanjiku@example.com
String | Optional Email address of the recipient. Useful for auto updating your contacts list. |
|
currency
KES
String | Optional Currency code of the airtime transaction. In 3 letter international ISO format. Options are:
|
|
amount
100
Integer | Required Amount of airtime to top up the recipient with. Digits only. Decimals not supported. |
|
note
AIR0000001
String | Optional A reference number or code to help identify the airtime transaction. Ideally should be unique. |
Code Scripts
POST /api/send_airtime HTTP/1.1
Host: app.topups.co.ke
Accept: application/json
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: application/json
Content-Length: 205
{
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
}
curl --request POST 'https://app.topups.co.ke/api/send_airtime' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer a12f4f9a99be83f1e631e379834864e7' \
--header 'Content-Type: application/json' \
--data-raw '{
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://app.topups.co.ke/api/send_airtime',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Authorization: Bearer a12f4f9a99be83f1e631e379834864e7',
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
#!/usr/bin/python
import http.client
import json
conn = http.client.HTTPSConnection("app.topups.co.ke")
payload = json.dumps({
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
})
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
'Content-Type': 'application/json'
}
conn.request("POST", "/api/send_airtime", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require "uri"
require "json"
require "net/http"
url = URI("https://app.topups.co.ke/api/send_airtime")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Authorization"] = "Bearer a12f4f9a99be83f1e631e379834864e7"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
})
response = https.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"country\": \"KE\",\r\n \"network\": \"Safaricom\",\r\n \"name\": \"Jane Wanjiku\",\r\n \"mobile\": \"254722000000\",\r\n \"email\": \"jane.wanjiku@example.com\",\r\n \"currency\": \"KES\",\r\n \"amount\": \"100\",\r\n \"note\": \"AIR0000001\"\r\n}");
Request request = new Request.Builder()
.url("https://app.topups.co.ke/api/send_airtime")
.method("POST", body)
.addHeader("Accept", "application/json")
.addHeader("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7")
.addHeader("Content-Type", "application/json")
.build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://app.topups.co.ke/api/send_airtime");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7");
request.AddHeader("Content-Type", "application/json");
var body = @"{
" + "\n" +
@" ""country"": ""KE"",
" + "\n" +
@" ""network"": ""Safaricom"",
" + "\n" +
@" ""name"": ""Jane Wanjiku"",
" + "\n" +
@" ""mobile"": ""254722000000"",
" + "\n" +
@" ""email"": ""jane.wanjiku@example.com"",
" + "\n" +
@" ""currency"": ""KES"",
" + "\n" +
@" ""amount"": ""100"",
" + "\n" +
@" ""note"": ""AIR0000001""
" + "\n" +
@"}";
request.AddParameter("application/json", body, ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://app.topups.co.ke/api/send_airtime',
'headers': {
'Accept': 'application/json',
'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"country": "KE",
"network": "Safaricom",
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com",
"currency": "KES",
"amount": "100",
"note": "AIR0000001"
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://app.topups.co.ke/api/send_airtime"
method := "POST"
payload := strings.NewReader(`{`+"
"+`
"country": "KE",`+"
"+`
"network": "Safaricom"`+"
"+`
"name": "Jane Wanjiku",`+"
"+`
"mobile": "254722000000",`+"
"+`
"email": "jane.wanjiku@example.com",`+"
"+`
"currency": "KES",`+"
"+`
"amount": "100",`+"
"+`
"note": "AIR0000001",`+"
"+`
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Accept", "application/json")
req.Header.Add("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
if err != nil {
fmt.Println(err)
return
}
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
if err != nil {
fmt.Println(err)
return
}
fmt.Println(string(body))
}
Response
Parameter Example | ||
---|---|---|
status | ||
type
SUCCESS
String Indication of whether the API call executed successfully or failed. Options are:
|
||
code
0000
Numeric Identifier of the API call result status |
||
message
Airtime Requested
String Description of the API call result status |
||
data | ||
error
[]
Array of Strings A list of errors found when the API call fails. Returns empty if none are found. |
||
sender | ||
name
Demo Limited
String Name of the sender. Typically the name of the business. |
||
mobile
254733000000
Integer Mobile number of the sender. Typically the mobile number of the business. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX |
||
email
admin@demo.com
String Email address of the sender. Typically the email address of the business. |
||
recipient | ||
name
Jane Wanjiku
String Name of the recipient. |
||
mobile
254722000000
Integer Mobile number of the recipient. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX |
||
email
jane.wanjiku@example.com
String Email address of the recipient. |
||
transaction | ||
type
Airtime
String Type of the transaction. Options are:
|
||
reference
G3DEFJKRWU
String Unique code identifying the airtime transaction. Useful when correlating webhook events. |
||
date
2022-09-24 09:45:35
String Date when the airtime transaction was requested. |
||
status
Requested
String Status of the airtime transaction. Options are:
|
||
currency
KES
String Currency code of the airtime transaction. In 3 letter international ISO format. Options are:
|
||
amount
100
Integer Amount of airtime sent to the recipient. |
||
note
AIR0000001
String A reference number or code to help identify the airtime transaction. Ideally should be unique. |
||
code
R220925.0018.220016
String Unique identifier from the mobile airtime provider. Usually blank unless the transaction was cancelled. |
||
source
API
String Origin of the transaction request. Options are:
|
||
country
KE
String Country code of the recipient. In 2 letter international ISO format. Options are:
|
||
network
Safaricom
String Mobile network of the recipient. Options are:
|
||
messaging | ||
sender
DEMO
String Alpha-numeric sender id of the business. This is likely to be blank for airtime transactions. |
||
recipient
254722000000
Integer Mobile number of the recipient. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX. This is likely to be blank for airtime transactions. |
||
message
Jane, thank you for repaying your loan.
String Text message sent to the recipient. This is likely to be blank for airtime transactions. |
||
channel | ||
type
Airtime
String Type of channel. Options are:
|
||
currency
KES
String Currency of your balance |
||
balance
41126.00
Numeric Balance of the specified channel |
Success Example
{
"status": {
"type": "SUCCESS",
"code": "0000",
"message": "Airtime Requested"
},
"data": {
"errors": [],
"sender": {
"name": "Demo Limited",
"mobile": "254733000000",
"email": "admin@demo.com"
},
"recipient": {
"name": "Jane Wanjiku",
"mobile": "254722000000",
"email": "jane.wanjiku@example.com"
},
"transaction": {
"type": "Airtime",
"reference": "G3DEFJKRWU",
"date": "2022-09-24 09:45:35",
"status": "Requested",
"currency": "KES",
"amount": "100",
"note": "AIR0000001",
"code": "",
"source": "API",
"country": "KE",
"network": "Safaricom"
},
"messaging": {
"sender": "",
"recipient": "",
"message": ""
},
"channel": {
"type": "Airtime",
"currency": "KES",
"balance": "41126.00"
}
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<status>
<type>SUCCESS</type>
<code>0000</code>
<message>Airtime Requested</message>
</status>
<data>
<errors/>
<sender>
<name>Demo Limited</name>
<mobile>254733000000</mobile>
<email>admin@demo.com</email>
</sender>
<recipient>
<name>Jane Wanjiku</name>
<mobile>254722000000</mobile>
<email>jane.wanjiku@example.com</email>
</recipient>
<transaction>
<type>Airtime</type>
<reference>G3DEFJKRWU</reference>
<date>2022-09-24 09:45:35</date>
<status>Requested</status>
<currency>KES</currency>
<amount>10</amount>
<note>AIR0000001</note>
<code/>
<source>API</source>
<country>KE</country>
<network>Safaricom</network>
</transaction>
<messaging>
<sender/>
<recipient/>
<message/>
</messaging>
<channel>
<type>Airtime</type>
<currency>KES</currency>
<balance>41126.00</balance>
</channel>
</data>
</xml>
Status
Code |
---|
0000
SUCCESS
Balance Found |
1000
FAIL
Invalid API Request |
2000
FAIL
Invalid Request Method |
3000
FAIL
Missing or Invalid Parameters |
4000
FAIL
Invalid API Token |
5000
FAIL
Request Not Allowed |
6000
FAIL
Invalid Account |
7000
FAIL
Insufficient Balance |
8000
FAIL
Airtime Cancelled |
9000
FAIL
Gateway Error |
Fail Example
{
"status": {
"type": "FAIL",
"code": "3000",
"message": "Missing or Invalid Parameters"
},
"data": {
"errors": [
"'mobile is invalid'",
"'amount is required.'"
]
}
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
<status>
<type>FAIL</type>
<code>3000</code>
<message>Missing or Invalid Parameters</message>
</status>
<data>
<errors>
<error>'mobile is invalid'</error>
<error>'amount is required.'</error>
</errors>
</data>
</xml>