Internal Services

Account Details & Balance API

Query your Statum wallet balance and active services. Build low-balance alerts and track M-Pesa account top-up codes.

The Account Details & Wallet Balance API exposes the account information that is useful to an application running Statum transactions. It returns the organization profile, contact details, available balance, and active service configuration shown in the response example below.

Send an authenticated HTTP GET request to the endpoint below when your application needs to read the current account details or wallet balance.

GET
https://api.statum.co.ke/api/v2/account-details

Monitoring the wallet balance

A low balance can prevent later SMS and airtime requests from being completed. Many applications therefore check available_balance on a schedule and alert the people responsible for funding the account.

  • Low-balance alerts: Run the endpoint from a scheduled backend task and compare available_balance with the threshold used by your business. Notify your operations or finance team when the balance is getting low.
  • M-Pesa top-ups: Use the account's mpesa_account_top_up_code as the account number when funding the wallet through the documented M-Pesa Paybill process.

Account Details API Request

Send an HTTP GET request to the endpoint above with the standard Basic Auth headers. The header contains the Base64-encoded Consumer Key and Secret.

Request Implementation Example

Query Account Details 
curl -X GET https://api.statum.co.ke/api/v2/account-details \
  -H "Authorization: Basic MmJlOTg5ZD...==" \
  -H "Content-Type: application/json"
$consumerKey = "YOUR_CONSUMER_KEY";
$consumerSecret = "YOUR_CONSUMER_SECRET";
$auth = base64_encode($consumerKey . ":" . $consumerSecret);

$client = new \GuzzleHttp\Client();
$response = $client->get('https://api.statum.co.ke/api/v2/account-details', [
    'headers' => [
        'Authorization' => 'Basic ' . $auth,
        'Content-Type'  => 'application/json'
    ]
]);

$accountDetails = json_decode($response->getBody()->getContents(), true);
const axios = require('axios');
const auth = Buffer.from('YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET').toString('base64');

axios.get('https://api.statum.co.ke/api/v2/account-details', {
    headers: {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
    }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Account Details API Response Format

The endpoint returns a JSON payload containing the organization details and balance fields shown below:

Parameter Type Description Example
status_code Number Standard API response code (200 = Success). 200
description String Status message of the query. Operation successful.
request_id String A unique UUID transaction ID returned by the API. 5a45bc7b-bf99-49ae-b089-9daf5f4adbb0
organization.name String The registered organization name. Statum Test
organization.details.available_balance Decimal Your current available wallet balance in KES. 695.15
organization.details.location String Physical city or address registration. Nairobi - Westlands
organization.details.website String Corporate web URL. www.statum.co.ke
organization.details.office_email String Registered contact email address. [email protected]
organization.details.office_mobile String Corporate phone contact. +254722199199
organization.details.mpesa_account_top_up_code String Your unique M-Pesa paybill account matching code. B9E573
organization.accounts Array List of active product accounts registered. [{"account": "Statum", "service_name": "sms"}]

Sample Response Payload

Response JSON 
{
    "status_code": 200,
    "description": "Operation successful.",
    "request_id": "5a45bc7b-bf99-49ae-b089-9daf5f4adbb0",
    "organization": {
        "name": "Statum Test",
        "details": {
            "available_balance": 695.15,
            "location": "Nairobi - Westlands",
            "website": "www.statum.co.ke",
            "office_email": "[email protected]",
            "office_mobile": "+254722199199",
            "mpesa_account_top_up_code": "B9E573"
        },
        "accounts": [
            {
                "account": "Statum",
                "service_name": "sms"
            },
            {
                "account": "CONNECT",
                "service_name": "sms"
            }
        ]
    }
}