Internal Services

Account Details & Balance API

Query your Statum wallet balance and active service subscriptions programmatically. Build automated low-balance alerts and track M-Pesa account top-up codes.

Statum's Account Details API allows developers to programmatically check their organization's available wallet balance, location metadata, contact information, and active service accounts. Integrating this endpoint lets you build custom dashboard statistics, low-balance notification systems, and automated billing reconciliations.

Send an authenticated HTTP GET request to the REST endpoint below to query your account details in real-time.

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

Automating Wallet and Float Management

Running out of wallet balance will cause SMS dispatches and airtime recharges to fail with status code 402. You can automate monitoring using our API:

  • Low-Balance Alerting: Schedule a cron job on your backend to call this endpoint hourly. If the available_balance falls below your target safety threshold (e.g. KES 2,000), trigger Slack, Teams, or email notifications to alert your finance team.
  • Automated M-Pesa Top-Ups: Use your organization's unique mpesa_account_top_up_code. When depositing money via our M-Pesa Paybill, pass this code as the account number, and our system will credit your wallet instantly.

Account Details API Request

Send an HTTP GET request to the endpoint above. You must include your standard Basic Auth headers (base64-encoded Consumer Key & Secret) to authorize the request.

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 API responds synchronously with a detailed JSON payload containing organization data and billing balances:

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 32-character transaction ID. 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"
            }
        ]
    }
}