Statum Developer API Quick Start Guide

Welcome to the Statum Developer Hub! This guide will walk you through registering a developer workspace, retrieving sandbox keys, formatting authentication headers, and initiating your first API requests to connect to our Bulk SMS gateway, Airtime disbursement system, and Safaricom integrations.

Step 1: Create Your Developer Workspace

To begin integrating, you need a developer account on our portal. Visit the Statum Registration Portal and sign up using your name, organization details, and a secure password. Verify your email to activate your developer dashboard.

Step 2: Retrieve API Keys & Credentials

Once authenticated, navigate to the API Settings tab on your developer dashboard. This console acts as your control center where you can generate and manage your unique Consumer Key and Consumer Secret. These credentials are required to authenticate every HTTP request sent to our gateway.

Official SDKs & Developer Tools

System Architecture & API Flow

The diagram below represents a typical transaction session lifecycle. Your software routes requests to the Statum API gateway securely. Our gateway handles validation, routes queries to the corresponding mobile operator (Safaricom, Airtel, Telkom), and returns asynchronous status updates to your configured callback webhook handler:

Mandatory API HTTP Headers

Every transaction request sent to the Statum gateway must include the following request headers to resolve authorization checks successfully:

-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

Ensure that endpoints are structured as https://api.statum.co.ke/api/v2/{command}, where {command} corresponds to the API resource (such as sms or airtime).

Sample Request Payload (JSON)

The code below demonstrates a typical request payload structure targeting the Bulk SMS resource endpoint.

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

Synchronous API Responses

Our API gateway utilizes a consistent response format for all operations. This structural design simplifies error parsing and response mapping inside your codebase.

Key parameters in every returned response include:

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

Sample Success Response Payload

{
    "status_code": 200,
    "description": "Operation successful.",
    "request_id": "9V7NcW1QMvWkQcceMnn3MKfmczdBeE1a"
}

Asynchronous Webhooks & Callbacks

Asynchronous operations (such as carrier delivery tracking, M-Pesa updates, or airtime top-ups) trigger callback notifications to verify transaction states. Once resolved, our gateway routes an HTTP POST payload containing final outcomes to your registered callback webhook URL.

{
    "result_code": "200",
    "result_desc": "Success",
    "request_id": "9V7NcW1QMvWkQcceMnn3MKfmczdBeE1a"
}