Getting Started

Welcome to the Statum Developer Hub! This guide will help you register an account, obtain API credentials, and start integrating our Payments and Communication APIs into your applications. Our step-by-step instructions are designed to help developers quickly implement Statum APIs and start testing their integrations efficiently.

Step 1: Register for a Developer Account

Accessing the Statum Developer Hub is simple. Register by providing your name, email, organization, and a secure password. After verifying your email, you'll have access to your developer dashboard.

Step 2: Dashboard Overview

Once logged in, your dashboard serves as the central hub for managing API projects, viewing API keys, and monitoring usage statistics. It provides a unified interface for all Statum APIs, including M-Pesa, Airtime, and SMS.

API Integration Flow

The diagram below illustrates a typical API request flow: your application sends a request to the Statum gateway, which forwards it to the service provider, and returns the response to your callback URL.

API Request Headers

To authenticate with Statum APIs, include the following standard headers:

-H "Authorization: Basic <credentials>" \
                -H "Content-Type: application/json" \
                -H "Accept: application/json"

[
                'Authorization' => 'Basic <credentials>',
                    'Content-Type' => 'application/json',
                    'Accept' => 'application/json'
                    ]

headers: {
                'Authorization': 'Basic <credentials>',
                    'Content-Type': 'application/json',
                    'Accept': 'application/json'
                    }

Making API Requests

Send all API requests to https://api.statum.co.ke/api/v2/{command}, where {command} is the API call, and parameters are included in the request body (POST) or URL (GET).

Sample SMS API Request

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

Understanding API Responses

Statum utilizes a standardized JSON response format for all API endpoints. This consistency allows developers to create reusable error-handling and response-parsing logic. Every API call returns an immediate synchronous response providing the current state of your request.

Key components of a Statum API response include:

• Status Codes: Standardized numerical codes indicating the success or failure of the request.
• Request ID: A unique, 32-character alphanumeric string used for transaction tracking and reconciliation with your internal systems.
• Description: A human-readable message explaining the result or any validation errors encountered.

Example JSON Response Payload

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

Asynchronous API Notifications & Webhooks

For operations that happen asynchronously—such as SMS delivery, M-Pesa payment confirmation, or Airtime top-up fulfillment—Statum uses Webhooks (HTTP Callbacks) to notify your system in real-time. This eliminates the need for inefficient polling and ensures your application stays updated instantly.

Real-time Transaction Results

Once a background process completes, our gateway sends a POST notification to your configured callback URL. This API Result payload contains final transaction statuses and updated balances where applicable.

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

We recommend implementing idempotency checks using the request_id to ensure your system handles potential duplicate notifications safely.