Sending airtime

Use POST /v1/transfer to send airtime credit to a mobile number on a supported network. Endpoint: https://apiairtime.beem.africa/v1/transfer

Request parameters

Headers

Header	Required	Description
`Authorization`	Yes	Basic Auth (`Basic base64(api_key:secret_key)`) or access token — see Authentication
`Content-Type`	Yes	`application/json`

Body

Parameter	Type	Required	Description
`dest_addr`	String	Yes	Mobile number in international format without a leading `+`. Example: `255784825785`
`amount`	Number	Yes	Airtime amount. Supports up to 2 decimal places
`reference_id`	String	Yes	Unique reference ID generated by your application. Example: `ref_id_215372`

Sample request body

{
  "dest_addr": "255784825785",
  "amount": 500,
  "reference_id": "ref_id_215372"
}

Sample implementations

Node.js
PHP
GitHub

const axios = require("axios");
const https = require("https");
const btoa = require("btoa");

const api_key = "<api_key>";
const secret_key = "<secret_key>";
const url = "https://apiairtime.beem.africa/v1/transfer";

const payload = {
  dest_addr: "<dest_addr>",
  amount: "<amount>",
  reference_id: "<reference_id>",
};

axios
  .post(url, payload, {
    headers: {
      "content-type": "application/json",
      Authorization: "Basic " + btoa(api_key + ":" + secret_key),
    },
    httpsAgent: new https.Agent({ rejectUnauthorized: false }),
  })
  .then((resp) => console.log(resp.data))
  .catch((err) => console.log(err.message));

<?php
$url = "https://apiairtime.beem.africa/v1/transfer";
$api_key = '<api_key>';
$secret_key = '<secret_key>';

$body = [
  'dest_addr' => '<dest_addr>',
  'amount' => '<amount>',
  'reference_id' => '<reference_id>',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Basic ' . base64_encode("$api_key:$secret_key"),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode($body),
  CURLOPT_SSL_VERIFYHOST => 0,
  CURLOPT_SSL_VERIFYPEER => 0,
]);

$response = curl_exec($ch);
if ($response === false) {
  die(curl_error($ch));
}
var_dump($response);
?>

Success response

On a valid request, the platform returns HTTP 200 or HTTP 201 with:

{
  "code": 200,
  "transaction_id": "1571324535091",
  "message": "Disbursement is in progress"
}

Field	Description
`code`	Response code (e.g. `200`)
`transaction_id`	Unique transaction ID generated by Beem
`message`	Transaction description (e.g. `Disbursement is in progress`)

Store the transaction_id — use it to check status via Transaction status or match against Callbacks.

Failure response

On an invalid request, the platform returns HTTP 400 Bad Request:

{
  "errors": [
    {
      "code": 102,
      "message": "Invalid phone number",
      "args": {
        "msisdn": "2556536795531"
      }
    }
  ]
}

See Response codes for all error codes.

Getting Started

APIs

Request parameters

Headers

Body

Sample request body

Sample implementations

Success response

Failure response

​Request parameters

​Headers

​Body

​Sample request body

​Sample implementations

​Success response

​Failure response

Request parameters

Headers

Body

Sample request body

Sample implementations

Success response

Failure response