Topups

Across All Networks!
Get Started
Topup Airtime
Developer API
Create Account
Log In

Developers \ HTTP REST API

API

API Reference

API Changelog

Download SDKs

Download Postman

Buy Airtime
Triggers the purchase of airtime by the payer to the mobile of the recipient.

The payer receives a prompt to authorize payment from the payment network. The recipient then receives the airtime and an SMS upon successful recharge.

Endpoint

POST https://app.topups.co.ke/api/buy_airtime LIVE

Request

Parameter Example
Headers
Accept application/json
String | Optional
The format of the response body. Options are:
  • application/json
  • text/xml
Defaults to application/json if not specified.
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:
  • application/json
  • text/xml
Defaults to application/json if not specified.
Body
country KE
String | Optional
Country code of the recipient. In 2 letter international ISO format. Options are:
  • KE (Kenya)
Automatically detected if not specified.
network Safaricom
String | Optional
Mobile network of the recipient. Options are:
  • Safaricom
  • Airtel
  • Telkom
Automatically detected if not specified.
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:
  • KES (Kenya Shilling)
Automatically detected if not specified.
amount 100
Integer | Required
Amount of airtime to top up the recipient with. Digits only. Decimals not supported.
note PAY0000001
String | Optional
A reference number or code to help identify the airtime transaction. Ideally should be unique.
payment_network M-Pesa
String | Required
Payment network of the payer. Options are:
  • M-Pesa
  • Airtel Money
  • T-Kash
  • Equitel
payment_name Joe Omondi
String | Optional
Name of the payer. Useful for auto updating your contacts list.
payment_mobile 254722002000
Integer | Required
Mobile number of the payer who will be prompted to authorize payment. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
payment_email joe.omondi@example.com
String | Optional
Email address of the payer. Useful for auto updating your contacts list.

Code Scripts

POST /api/buy_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": "PAY0000001",
    "payment_network": "M-Pesa",
    "payment_name": "Joe Omondi",
    "payment_mobile": "254722002000",
    "payment_email": "joe.omondi@example.com"
}

curl --request POST 'https://app.topups.co.ke/api/buy_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": "PAY0000001",
    "payment_network": "M-Pesa",
    "payment_name": "Joe Omondi",
    "payment_mobile": "254722002000",
    "payment_email": "joe.omondi@example.com"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://app.topups.co.ke/api/buy_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": "PAY0000001",
        "payment_network": "M-Pesa",
        "payment_name": "Joe Omondi",
        "payment_mobile": "254722002000",
        "payment_email": "joe.omondi@example.com",
    }',
    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": "PAY0000001",
    "payment_network": "M-Pesa",
    "payment_name": "Joe Omondi",
    "payment_mobile": "254722002000",
    "payment_email": "joe.omondi@example.com"
})
headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
    'Content-Type': 'application/json'
}
conn.request("POST", "/api/buy_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/buy_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": "PAY0000001",
    "payment_network": "M-Pesa",
    "payment_name": "Joe Omondi",
    "payment_mobile": "254722002000",
    "payment_email": "joe.omondi@example.com",
})

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\": \"PAY0000001\"\r\n, \"payment_network\": \"M-Pesa\",\r\n    \"payment_name\": \"Joe Omondi\",\r\n    \"payment_mobile\": \"254722002000\",\r\n    \"payment_email\": \"joe.omondi@example.com\"}");
Request request = new Request.Builder()
    .url("https://app.topups.co.ke/api/buy_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/buy_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"": ""PAY0000001"",
    " + "\n" +
    @"    ""payment_network"": ""M-Pesa"",
    " + "\n" +
    @"    ""payment_name"": ""Joe Omondi"",
    " + "\n" +
    @"    ""payment_mobile"": ""254722002000"",
    " + "\n" +
    @"    ""payment_email"": ""joe.omondi@example.com""
    " + "\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/buy_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": "PAY0000001",
        "payment_network": "M-Pesa",
        "payment_name": "Joe Omondi",
        "payment_mobile": "254722002000",
        "payment_email": "joe.omondi@example.com"
    })
};
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/buy_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": "PAY0000001",`+"
"+`
    "payment_network": "M-Pesa"`+"
"+`
    "payment_name": "Joe Omondi",`+"
"+`
    "payment_mobile": "254722002000",`+"
"+`
    "payment_email": "joe.omondi@example.com",`+"
"+`
}`)

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:
  • SUCCESS
  • FAIL
code 0000
Numeric
Identifier of the API call result status
message Purchase 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.
payment
network M-Pesa
String
Payment network of the payer. Options are:
  • M-Pesa
  • Airtel Money
  • T-Kash
  • Equitel
name Joe Omondi
String
Name of the payer.
mobile 254722002000
Integer
Mobile number of the payer who will be prompted to authorize payment. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
email joe.omondi@example.com
String
Email address of the payer.
transaction
type Airtime
String
Type of the transaction. Options are:
  • Airtime
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:
  • Requested
  • Cancelled
currency KES
String
Currency code of the airtime transaction. In 3 letter international ISO format. Options are:
  • KES (Kenya Shilling)
amount 100
Integer
Amount of airtime sent to the recipient.
note PAY0000001
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:
  • API
country KE
String
Country code of the recipient. In 2 letter international ISO format. Options are:
  • KE (Kenya)
network Safaricom
String
Mobile network of the recipient. Options are:
  • Safaricom
  • Airtel
  • Telkom
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:
  • Airtime
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"
        },
        "payment": {
            "network": "M-Pesa",
            "name": "Joe Omondi",
            "mobile": "254722002000",
            "email": "joe.omondi@example.com"
        },
        "transaction": {
            "type": "Airtime",
            "reference": "G3DEFJKRWU",
            "date": "2022-09-24 09:45:35",
            "status": "Requested",
            "currency": "KES",
            "amount": "100",
            "note": "PAY0000001",
            "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>
        <payment>
            <network>M-Pesa</network>
            <name>Joe Omondi</name>
            <mobile>254722002000</mobile>
            <email>joe.omondi@example.com</email>
        </payment>
        <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>PAY0000001</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
8000 FAIL
Purchase 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>
  Send Airtime
Send Agent Float