Check balance

Use GET /v1/credit-balance to retrieve your available USSD credit balance. This endpoint is served by the shared Topup API — the same service used by Airtime and other Beem products, with app_name=USSD. Endpoint: https://apitopup.beem.africa/v1/credit-balance?app_name=USSD See Check USSD credit balance for the interactive API reference.

Request parameters

Headers

Header	Required	Description
`Authorization`	Yes	Basic Auth or access token — see Authentication
`Content-Type`	Yes	`application/json`

Query parameters

Parameter	Required	Description
`app_name`	Yes	Must be `USSD`

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://apitopup.beem.africa/v1/credit-balance?app_name=USSD";

function checkBalance() {
  axios
    .get(url, {
      headers: {
        "Content-Type": "application/json",
        Authorization: "Basic " + btoa(api_key + ":" + secret_key),
      },
      httpsAgent: new https.Agent({ rejectUnauthorized: false }),
    })
    .then((response) => console.log(response.data))
    .catch((error) => console.error(error.response?.data || error.message));
}

checkBalance();

<?php
$api_key = '<api_key>';
$secret_key = '<secret_key>';
$url = 'https://apitopup.beem.africa/v1/credit-balance?app_name=USSD';

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

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

Success response

HTTP 200 OK

{
  "data": {
    "credit_bal": "5300.0000"
  }
}

Error responses

Invalid authentication
Missing authorization

HTTP 401 Unauthorized

{
  "code": 120,
  "message": "Invalid Authentication Parameters"
}

HTTP 400 Bad Request

{
  "error": "No authorization headers"
}

Getting Started

APIs

Request parameters

Headers

Query parameters

Sample implementations

Success response

Error responses

​Request parameters

​Headers

​Query parameters

​Sample implementations

​Success response

​Error responses

Request parameters

Headers

Query parameters

Sample implementations

Success response

Error responses