Topups

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

Developers \ Webhooks via Instant Callback Notification

Webhooks

Webhook Reference

Webhook Changelog

Download Scripts

Processing Callbacks

How to receive and process webhook callbacks in 2 easy steps

Once you have registered your webhook endpoints, you are now able to process callbacks. This is a 2-step process as follows:

  1. A HTTP request will be made to the registered webhook endpoints with the appropriate HTTP header and body parameters.
  2. The registered endpoint will then return a HTTP response containing the status after receiving the HTTP request.

API protocol

Callbacks can be processed natively or using any of the webhook scripts we have made available for various programming or scripting languages.

1. Making a HTTP request

To call the API, your application must make a HTTP request with parameters appropriate to the relevant API endpoint.

The HTTP request will typically consist of 3 parts:

  1. HTTP URL
  2. HTTP Header
  3. HTTP Body

HTTP URL

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

HTTP Header

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

HTTP Body

The HTTP body contains the required parameters for the specific API call in the specified acceptable response format

The HTTP body can then be sent depending on the content type specified in the HTTP header.

Supported formats include:

  • application/json
  • text/xml

Example HTTP request

POST /airtime/callback.php HTTP/1.1
Host: example.com
Accept: application/json
Signature-Algorithm: HMAC-SHA256
Signature-Hash: MmIDhgCA9l4xQIvLV4JSHGZKhDtCBLjm5HY76gte2r0=
Signature-Timestamp: 1664001935
Content-Type: application/json
Content-Length: 1071

{
    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Airtime Delivered"
    },
    "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": "R221004.1813.21007e",
            "source": "API",
            "country": "KE",
            "network": "Safaricom"
        },
        "messaging": {
            "sender": "",
            "recipient": "",
            "message": ""
        },
        "channel": {
            "type": "Airtime",
            "currency": "KES",
            "balance": "41126.00"
        }
    }
}

POST /airtime/callback.php HTTP/1.1
Host: example.com
Accept: application/json
Signature-Algorithm: HMAC-SHA256
Signature-Hash: MmIDhgCA9l4xQIvLV4JSHGZKhDtCBLjm5HY76gte2r0=
Signature-Timestamp: 1664001935
Content-Type: text/xml
Content-Length: 1230

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>SUCCESS</type>
        <code>0000</code>
        <message>Airtime Delivered</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>R221004.1813.21007e</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>

2. Processing the HTTP response

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:

  1. Status 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)

Status Content

The status contains acknowledgement that the HTTP request of the callback was processed.

Code
0000 SUCCESS
Callback Processed

Example HTTP response

{
    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Callback Processed"
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>SUCCESS</type>
        <code>0000</code>
        <message>Callback Processed</message>
    </status>
</xml>
  Register Webhooks
Get Started