Topups

Once you have your API credentials, you are now able to make an API call. This is a 2-step process as follows:

Make a HTTP request to the required API endpoint with the appropriate HTTP header and body parameters.
Process the HTTP response containing the status and data content returned after making the HTTP request.

APIs can be made and processed natively or using any of the client libraries we have made available for different programming or scripting languages.

The HTTP URL for the API endpoint is structured as follows:

https://app.topups.co.ke/api/[function_name]

Where [function_name] is the endpoint of the particular API function you would like to call e.g. send_airtime or get_balance

The HTTP header contains authentication, content type and acceptable response format parameters

Authentication

The HTTP request MUST be authenticated using the API token as an Authorization header in the form of a Bearer token.

Authorization: Bearer a12f4f9a99be83f1e631e379834864e7

Content-Type

The HTTP request MUST also specify the format of the content it is sending to the server as a Content-Type header.

Supported formats include:

application/json
text/xml

Content-Type: application/json

Accept

The HTTP request MUST also specify the format of the content it would like to receive from the server as an Accept header.

Supported formats include:

application/json
text/xml

Accept: application/json

JSON
XML

POST /api/get_balance HTTP/1.1
Host: app.topups.co.ke
Accept: application/json
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: application/json
Content-Length: 35

{
    "channel_type": "Airtime"
}

POST /api/get_balance HTTP/1.1
Host: app.topups.co.ke
Accept: text/xml
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: text/xml
Content-Length: 89

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <channel_type>Airtime</channel_type>
</xml>

Once the HTTP request has been made, the API endpoint will synchronously return a HTTP response.

The HTTP response will typically consist of 2 parts:

Status Content
Data Content

The HTTP response returned will depend on the acceptable response format specified in the Accept header of the HTTP request.

Supported formats include:

JSON (application/json)
XML (text/xml)

The status contains feedback on whether the HTTP request was successful or failed.

Here are some typical status your API call may return after your request is processed:

Code
0000 SUCCESS API call executed and returned success status.
1000 FAIL The API request is invalid. Endpoint may not exist or may be incorrectly spelt.
2000 FAIL The API method used is invalid e.g using a GET instead of a POST
3000 FAIL The API request is missing or has invalid parameters.
4000 FAIL The API token is missing, invalid or has been revoked.
5000 FAIL The API token does not have permission to call the specified endpoint.
6000 FAIL The account was not found or does not exist.
7000 - 10000 FAIL Typically errors specific to the endpoint called.

JSON
XML

{
    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Balance Found"
    },
    "data": {
        "errors": [],
        "channel": {
            "type": "Airtime",
            "currency": "KES",
            "balance": "41226.00"
        }
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>SUCCESS</type>
        <code>0000</code>
        <message>Balance Found</message>
    </status>
    <data>
        <errors/>
        <channel>
            <type>Airtime</type>
            <currency>KES</currency>
            <balance>41226.00</balance>
        </channel>
    </data>
</xml>

Across All Networks!

Developers \ HTTP REST API

API

API Reference

API Changelog

Download SDKs

Download Postman

Making API Calls

How to make and process an API call in 2 easy steps

1. Making a HTTP request

HTTP URL

HTTP Header

Authentication

Content-Type

Accept

HTTP Body

Example HTTP request

2. Processing the HTTP response

Status Content

Data Content

Example HTTP response