Account Details & Balance API

This section provides technical documentation for the Account Details & Wallet Balance API, which allows developers using the Statum Developer Hub to query essential dashboard information. By integrating this endpoint, developers can programmatically retrieve their organization's active profile, registered contact information, available balance metrics, and active service configurations.

To query your organizational profile, subscription settings, and current financial balances in real-time, developers must submit an authenticated HTTP GET request to the RESTful endpoint specified below.

Automating Wallet and Float Management

Running out of your digital wallet balance will cause all subsequent transactional SMS dispatches and automated airtime recharges to fail immediately with a 402 Payment Required status code, making proactive monitoring crucial for production operations. You can implement automated balance monitoring workflows using the programmatic endpoints detailed in this section:

• Low-Balance Alerting: We recommend scheduling an automated cron job or daemon on your backend servers to query this balance endpoint at hourly intervals. If the returned available_balance parameter falls below your defined safety threshold, such as KES 2,000, your system should automatically trigger real-time notifications to your engineering or finance channels via Slack, Microsoft Teams, or custom email alerts.
• Automated M-Pesa Top-Ups: Every developer account is assigned a unique, persistent identifier known as the mpesa_account_top_up_code. When depositing operational funds to your balance via our official M-Pesa Paybill number, simply provide this alphanumeric code as the M-Pesa account number, and our financial reconciliation engine will verify the deposit and credit your digital wallet balance 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

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:

Sample Response Payload

{
    "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"
            }
        ]
    }
}