Getting Started

Statum Developer API Quick Start Guide

Connect to the Statum SMS gateway, airtime top-up, and Safaricom integration services in Kenya. Register, authenticate, and test your first request.

Welcome to the Statum Developer Hub. This guide covers account registration, credentials, authentication headers, and the first requests for the Bulk SMS gateway, Airtime disbursement system, and Safaricom integrations.

Step 1: Create Your Developer Workspace

Start by creating a developer account in the Statum Registration Portal. Enter your name and organization details, choose a secure password, and verify your email address before using the dashboard.

Step 2: Retrieve API Keys & Credentials

After signing in, open API Settings in the dashboard. This is where you generate and manage the Consumer Key and Consumer Secret used to authenticate requests to the gateway.

Official SDKs & Developer Tools

If you prefer to work from an SDK, visit the Statum GitHub organization. The available libraries provide a starting point for using the API without writing every request wrapper yourself.

PHP SDK Java SDK
Visit Statum on GitHub

System Architecture & API Flow

The diagram shows the usual path of a transaction. Your application sends a request to the Statum gateway, the gateway validates it and passes it to the relevant mobile operator (Safaricom, Airtel, or Telkom), and later sends an asynchronous update to the callback URL you configured:

Statum API Architecture and Transaction Flow Diagram

Mandatory API HTTP Headers

Include the following headers with each transaction request. The gateway uses them to identify your account and read the request body correctly:

Parameter Type Description Example
Authorization String Base64 encoded string of consumerKey:consumerSecret prefixed with Basic . Basic MmJlOTg5...
Content-Type String Specifies that request body payload is formatted as JSON. application/json
Accept String Indicates that the client accepts JSON formatted responses. application/json
Header Implementation 
-H "Authorization: Basic <base64_credentials>" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
[
    'Authorization' => 'Basic <base64_credentials>',
    'Content-Type'  => 'application/json',
    'Accept'        => 'application/json'
]
headers: {
    'Authorization': 'Basic <base64_credentials>',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

Making API Requests

API Endpoint Base URL

Use the following base endpoint for transaction requests:

https://api.statum.co.ke/api/v2/

Requests follow the pattern https://api.statum.co.ke/api/v2/{command}. Replace {command} with the resource you are calling, such as sms or airtime.

Sample Request Payload (JSON)

The example below shows the request body used for the Bulk SMS resource.

SMS Request Payload 
{
    "sender_id": "Statum",
    "phone_number": "254712345678",
    "message": "This is a transaction notification via the Statum API."
}

Synchronous API Responses

Responses use the same top-level structure across the documented operations, which makes it easier to handle success and failure in one place.

The main fields to inspect are:

  • status_code: Numerical representation of transaction outcome (200 = OK).
  • description: Details containing outcome messages or input validation failure summaries.
  • request_id: A unique UUID string used to map asynchronous webhooks and callbacks.

Sample Success Response Payload

JSON Response Structure 
{
    "status_code": 200,
    "description": "Operation successful.",
    "request_id": "9b11ac7b-08bf-4cb1-96ca-eb5f8805985f"
}

Asynchronous Webhooks & Callbacks

Some operations finish after the initial response, including carrier delivery tracking, M-Pesa updates, and airtime top-ups. When the final state is available, the gateway sends an HTTP POST payload to your registered callback URL.

Sample Webhook Notification 
{
    "result_code": 200,
    "result_desc": "Successfully delivered",
    "request_id": "9b11ac7b-08bf-4cb1-96ca-eb5f8805985f"
}