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

Send Agent Float
Loads float into a mobile money agent's account. The agent receives an SMS upon successful deposit.

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_agent_float 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 mobile money agent. In 2 letter international ISO format. Options are:
  • KE (Kenya)
Automatically detected if not specified.
network M-Pesa
String | Optional
Mobile money network of the mobile money agent. Options are:
  • M-Pesa
  • Airtel Money
  • T-Kash
Automatically detected if not specified.
name Jane Wanjiku
String | Optional
Name of the contact of the mobile money agent. Useful for auto updating your contacts list.
mobile 254722000000
Integer | Required
Mobile number of the contact of the mobile money agent. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
email jane.wanjiku@example.com
String | Optional
Email address of the contact of the mobile money agent. Useful for auto updating your contacts list.
agent_name JANE ENTERPRISES
String | Optional
Name of the mobile money agent as issued by the mobile money network.
agent_number 678910
Integer | Required (On Some Networks)
Agent number of the mobile money agent as issued by the mobile money network. Required by:
  • M-Pesa
store_number 678910
Integer | Required (On Some Networks)
Store number of the mobile money agent as issued by the mobile money network. Required by:
  • M-Pesa
currency KES
String | Optional
Currency code of the mobile money float. In 3 letter international ISO format. Options are:
  • KES (Kenya Shilling)
Automatically detected if not specified.
amount 100
Integer | Required
Amount of mobile money float to deposit into the mobile money agent. Digits only. Decimals not supported.
note FLT0000001
String | Optional
A reference number or code to help identify the deposit. Ideally should be unique.

Code Scripts

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

{
    "country": "KE",
    "network": "M-Pesa",
    "name": "Jane Wanjiku",
    "mobile": "254722000000",
    "email": "jane.wanjiku@example.com",
    "agent_name": "JANE ENTERPRISES",
    "agent_number": "678910",
    "store_number": "678910",
    "currency": "KES",
    "amount": "100",
    "note": "FLT0000001"
}

curl --request POST 'https://app.topups.co.ke/api/send_agent_float' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer a12f4f9a99be83f1e631e379834864e7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "country": "KE",
    "network": "M-Pesa",
    "name": "Jane Wanjiku",
    "mobile": "254722000000",
    "email": "jane.wanjiku@example.com",
    "agent_name": "JANE ENTERPRISES",
    "agent_number": "678910",
    "store_number": "678910",
    "currency": "KES",
    "amount": "100",
    "note": "FLT0000001"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://app.topups.co.ke/api/send_agent_float',
    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": "M-Pesa",
        "name": "Jane Wanjiku",
        "mobile": "254722000000",
        "email": "jane.wanjiku@example.com",
        "agent_name": "JANE ENTERPRISES",
        "agent_number": "678910",
        "store_number": "678910",
        "currency": "KES",
        "amount": "100",
        "note": "FLT0000001"
    }',
    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": "M-Pesa",
    "name": "Jane Wanjiku",
    "mobile": "254722000000",
    "email": "jane.wanjiku@example.com",
    "agent_name": "JANE ENTERPRISES",
    "agent_number": "678910",
    "store_number": "678910",
    "currency": "KES",
    "amount": "100",
    "note": "FLT0000001"
})
headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
    'Content-Type': 'application/json'
}
conn.request("POST", "/api/send_agent_float", 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_agent_float")

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": "M-Pesa",
    "name": "Jane Wanjiku",
    "mobile": "254722000000",
    "email": "jane.wanjiku@example.com",
    "agent_name": "JANE ENTERPRISES",
    "agent_number": "678910",
    "store_number": "678910",
    "currency": "KES",
    "amount": "100",
    "note": "FLT0000001"
})

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\": \"M-Pesa\",\r\n    \"name\": \"Jane Wanjiku\",\r\n    \"mobile\": \"254722000000\",\r\n    \"email\": \"jane.wanjiku@example.com\",\r\n    \"agent_name\": \"JANE ENTERPRISES\",\r\n    \"agent_number\": \"678910\",\r\n    \"store_number\": \"678910\",\r\n    \"currency\": \"KES\",\r\n    \"amount\": \"100\",\r\n    \"note\": \"FLT0000001\"\r\n}");
Request request = new Request.Builder()
    .url("https://app.topups.co.ke/api/send_agent_float")
    .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_agent_float");
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"": ""M-Pesa"",
    " + "\n" +
    @"    ""name"": ""Jane Wanjiku"",
    " + "\n" +
    @"    ""mobile"": ""254722000000"",
    " + "\n" +
    @"    ""email"": ""jane.wanjiku@example.com"",
    " + "\n" +
    @"    ""agent_name"": ""JANE ENTERPRISES"",
    " + "\n" +
    @"    ""agent_number"": ""678910"",
    " + "\n" +
    @"    ""store_number"": ""678910"",
    " + "\n" +
    @"    ""currency"": ""KES"",
    " + "\n" +
    @"    ""amount"": ""100"",
    " + "\n" +
    @"    ""note"": ""FLT0000001""
    " + "\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_agent_float',
    'headers': {
        'Accept': 'application/json',
        'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "country": "KE",
        "network": "M-Pesa",
        "name": "Jane Wanjiku",
        "mobile": "254722000000",
        "email": "jane.wanjiku@example.com",
        "agent_name": "JANE ENTERPRISES",
        "agent_number": "678910",
        "store_number": "678910",
        "currency": "KES",
        "amount": "100",
        "note": "FLT0000001"
    })
};
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_agent_float"
method := "POST"

payload := strings.NewReader(`{`+"
"+`
    "country": "KE",`+"
"+`
    "network": "M-Pesa"`+"
"+`
    "name": "Jane Wanjiku",`+"
"+`
    "mobile": "254722000000",`+"
"+`
    "email": "jane.wanjiku@example.com",`+"
"+`
    "agent_name": "JANE ENTERPRISES",`+"
"+`
    "agent_number": "678910",`+"
"+`
    "store_number": "678910",`+"
"+`
    "currency": "KES",`+"
"+`
    "amount": "100",`+"
"+`
    "note": "FLT0000001",`+"
"+`
}`)

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 Agent Float 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 sending mobile money agent. Typically the name of the business.
mobile 254722002222
Integer
Mobile number of the sending mobile money agent. 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 sending mobile money agent. Typically the email address of the business.
agent_name DEMO FLOAT
String
Name of the sending mobile money agent as issued by the mobile money network.
agent_number 012345
Integer
Agent number of the sending mobile money agent as issued by the mobile money network. Required for:
  • M-Pesa
store_number 012345
Integer
Store number of the sending mobile money agent as issued by mobile money network. Required for:
  • M-Pesa
recipient
name Jane Wanjiku
String
Name of the contact of the receiving mobile money agent.
mobile 254722000000
Integer
Mobile number of the contact of the receiving mobile money agent. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
email jane.wanjiku@example.com
String
Email address of the contact of the receiving mobile money agent.
agent_name JANE ENTERPRISES
String
Name of the receiving mobile money agent as issued by the mobile money network.
agent_number 678910
Integer
Agent number of the receiving mobile money agent as issued by the mobile money network. Required for:
  • M-Pesa
store_number 678910
Integer
Agent number of the receiving mobile money agent as issued by the mobile money network. Required for:
  • M-Pesa
transaction
type Agent Float
String
Type of the transaction. Options are:
  • Agent Float
reference G3DEFJKRWU
String
Unique code identifying the agent float transaction. Useful when correlating webhook events.
date 2022-09-24 09:45:35
String
Date when the agent float transaction was requested.
status Requested
String
Status of the agent float transaction. Options are:
  • Requested
  • Cancelled
currency KES
String
Currency code of the agent float transaction. In 3 letter international ISO format. Options are:
  • KES (Kenya Shilling)
amount 100
Integer
Amount of agent float sent to the recipient.
note FLT0000001
String
A reference number or code to help identify the agent float transaction. Ideally should be unique.
code QIQ0P5FL0E
String
Unique identifier from the mobile agent float provider. Usually blank unless the transaction was cancelled.
source API
String
Origin of the agent float transaction request. Options are:
  • API
country KE
String
Country code of the agent float transaction. In 2 letter international ISO format. Options are:
  • KE (Kenya)
network M-Pesa
String
Mobile money network of the agent float transaction. Options are:
  • M-Pesa
  • Airtel Money
  • T-Kash
messaging
sender DEMO
String
Alpha-numeric sender id of the business. This is likely to be blank for agent float 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 agent float transactions.
message Jane Enterprises, you have received KES 100.00 M-pesa Float.
String
Text message sent to the recipient. This is likely to be blank for agent float transactions.
channel
type Agent Float
String
Type of channel. Options are:
  • Agent Float
currency KES
String
Currency of your balance
balance 351786.00
Numeric
Balance of the specified channel

Success Example

{
    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Agent Float Requested"
    },
    "data": {
        "errors": [],
        "sender": {
            "name": "Demo Limited",
            "mobile": "254722002222",
            "email": "admin@demo.com",
            "agent_name": "DEMO FLOAT",
            "agent_number": "012345",
            "store_number": "012345"
        },
        "recipient": {
            "name": "Jane Wanjiku",
            "mobile": "254722000000",
            "email": "jane.wanjiku@example.com",
            "agent_name": "JANE ENTERPRISES",
            "agent_number": "678910",
            "store_number": "678910"
        },
        "transaction": {
            "type": "Agent Float",
            "reference": "G3DEFJKRWU",
            "date": "2022-09-24 09:45:35",
            "status": "Requested",
            "currency": "KES",
            "amount": "100",
            "note": "FLT0000001",
            "code": "",
            "source": "API",
            "country": "KE",
            "network": "M-Pesa"
        },
        "messaging": {
            "sender": "",
            "recipient": "",
            "message": ""
        },
        "channel": {
            "type": "Agent Float",
            "currency": "KES",
            "balance": "351786.00"
        }
    }
}

<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>SUCCESS</type>
        <code>0000</code>
        <message>Agent Float Requested</message>
    </status>
    <data>
        <errors/>
        <sender>
            <name>Demo Limited</name>
            <mobile>254722002222</mobile>
            <email>admin@demo.com</email>
            <agent_name>DEMO FLOAT</agent_name>
            <agent_number>012345</agent_number>
            <store_number>012345</store_number>
        </sender>
        <recipient>
            <name>Jane Wanjiku</name>
            <mobile>254722000000</mobile>
            <email>jane.wanjiku@example.com</email>
            <agent_name>JANE ENTERPRISES</agent_name>
            <agent_number>678910</agent_number>
            <store_number>678910</store_number>
        </recipient>
        <transaction>
            <type>Agent Float</type>
            <reference>G3DEFJKRWU</reference>
            <date>2022-09-24 09:45:35</date>
            <status>Requested</status>
            <currency>KES</currency>
            <amount>10</amount>
            <note>FLT0000001</note>
            <code/>
            <source>API</source>
            <country>KE</country>
            <network>M-Pesa</network>
        </transaction>
        <messaging>
            <sender/>
            <recipient/>
            <message/>
        </messaging>
        <channel>
            <type>Agent Float</type>
            <currency>KES</currency>
            <balance>351786.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
Agent Float 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 SMS