README

A PHP 8.2+ Safaricom Daraja SDK for production payment, IoT SIM portal management, and GSM/network-level utility integrations across web and mobile apps. It provides a framework-agnostic PHP core with typed DTOs, Guzzle 7 transport, and optional Laravel support for M-Pesa, IoT, and GSM workflows.

Features & Supported Services

This SDK follows the current Safaricom developer portal and the verified endpoint contracts in this repository. It includes:

A framework-agnostic request() method for Daraja endpoints
Typed request DTOs for every covered endpoint
OAuth access token acquisition and bearer token handling
Helper methods for the supported Daraja and M-Pesa flows
STK password generation from shortcode, passkey, and timestamp
Security credential generation from Safaricom public certificates
PHPUnit coverage with Guzzle MockHandler

Installation

composer require statum/safaricom-daraja-sdk

Dependencies

PHP ^8.2
Guzzle ^7.13
PHPUnit ^11.5 for tests
PHPStan ^1.12 for static analysis

Getting Started

Install the package with Composer.
Put your consumer key, consumer secret, and environment in .env or your app config.
Create a SafaricomConfig in your application bootstrap, service container, or Laravel service provider.
Resolve a SafaricomClient from the container, or create it once and reuse it.
Call a typed helper or the generic request() method.

The SDK handles OAuth token acquisition automatically for helper calls.

Why this is structured this way:

SafaricomConfig is the immutable application-level input for Safaricom credentials, environment, timeouts, and default headers.
SafaricomClient is the reusable HTTP client facade that holds the config and manages bearer token acquisition for you.
Keeping config and client separate makes it easier to swap sandbox versus production, inject the client in tests, and reuse the same client across requests.

Plain PHP bootstrap example:

use Statum\Safaricom\Daraja\Client\SafaricomClient;
use Statum\Safaricom\Daraja\Config\SafaricomConfig;
use Statum\Safaricom\Daraja\Environment\Environment;

$environment = ($_ENV['SAFARICOM_ENVIRONMENT'] ?? 'sandbox') === 'production'
    ? Environment::Production
    : Environment::Sandbox;

$config = new SafaricomConfig(
    consumerKey: $_ENV['SAFARICOM_CONSUMER_KEY'] ?? '',
    consumerSecret: $_ENV['SAFARICOM_CONSUMER_SECRET'] ?? '',
    environment: $environment,
);

$client = SafaricomClient::create($config);

Flow overview:

flowchart LR
    A["Load env config"] --> B["Create SafaricomConfig"]
    B --> C["Create SafaricomClient"]
    C --> D["Build typed DTO"]
    D --> E["Call helper or request()"]
    E --> F["SDK gets OAuth token automatically"]
    F --> G["Send request through Guzzle"]
    G --> H["Inspect ApiResponse"]

Documentation Map

If you read one document first, read docs/endpoint-guide.md. It is the primary developer reference for helper-to-endpoint mapping, required fields, and request examples.

Use the docs in this order:

docs/endpoint-guide.md for the primary helper, DTO, and endpoint contract walkthrough
docs/examples.md for copy-paste-ready client, Laravel, and error-handling snippets
docs/api-reference.md for the exact required fields, optional fields, and wire-level payload notes

The rule is simple:

required API fields are required DTO constructor arguments
optional API fields are nullable constructor arguments
the DTO toArray() method shows the exact payload keys sent to Safaricom

If you are implementing a new flow, start with docs/endpoint-guide.md. If you are checking whether a field is required or optional, open docs/api-reference.md. If you need a working snippet, use docs/examples.md.

Quick start

See Examples for copy-paste-ready usage patterns.

Generating the STK Push password

Safaricom expects the password to be the Base64 encoding of the shortcode, passkey, and timestamp concatenated together.

See Examples for the generator pattern. The passkey is not part of SafaricomConfig; it is a flow-specific secret used only to derive the STK password.

Generating a security credential

Safaricom’s docs state that security credentials are generated by encrypting the initiator password with the M-Pesa public key certificate using RSA with PKCS#1.5 padding.

See Examples for the generator pattern.

Common Flows

Use the helper that matches the business flow. If a helper exists, prefer it over request() because the helper binds the DTO type and endpoint path together.

STK Push

Use stkPush() with StkPushRequest when initiating an M-Pesa Express payment. The flow is: build the DTO, generate the STK password, call the helper, then wait for the callback or query the checkout request ID. See Examples.

STK Push Query

Use stkPushQuery() with the checkout request ID returned by the initial STK push to confirm the final payment state.

C2B

Use c2bRegisterUrl() once to register the confirmation and validation URLs, then use c2bSimulate() in sandbox to test the callback flow. In production, Safaricom posts back to your registered endpoints.

B2B and B2C

Use b2bPaymentRequest() for business-to-business payouts and b2cPaymentRequest() for business-to-customer payouts. These are request-and-response flows, so you should persist the response payload before you move on to downstream reconciliation.

Transaction Queries

Use reversalRequest(), accountBalanceQuery(), and transactionStatusQuery() for the operational flows Safaricom exposes as account and transaction controls. These helpers are usually called after an operational event, not as the first step of a payment flow.

Generic Request

If you need to call a supported path directly, use request() with the raw endpoint and a DTO. See Examples.

Response Handling

SafaricomClient returns an ApiResponse wrapper.

Use json() when you expect valid JSON and want a strict array.
Use decoded() when you want a nullable array and do not want to throw on invalid JSON.
Use statusCode() to inspect the HTTP status.
Use headers() to inspect response headers.
Use body() when you need the raw response body for debugging.
Use response() if you need the underlying PSR-7 response object.

See Examples for a response inspection pattern.

If the body is not valid JSON, json() throws an ApiException.

Supported endpoint helpers

The SDK includes helpers for the collection items and corresponding Daraja endpoints:

OAuth token generation
M-Pesa Express / STK push and query
C2B simulate and register URL
B2B payment request
B2C payment request
B2Pochi payment request
Reversal
Account balance query
Transaction status query
Pull transaction registration and query
IMSI / SWAP / Age on Network checks
B2B Hakikisha
Mobile number validation
Standing order creation
SIM portal operations from the collection

Use request() if you want to call an endpoint that is not wrapped explicitly.

Laravel support

The SDK is framework-agnostic, but it also ships an optional Laravel service provider and publishable config file.

Auto-discovery provider: Statum\Safaricom\Daraja\Laravel\SafaricomServiceProvider
Publish tag: safaricom-daraja-config
Config file: config/safaricom-daraja.php
The published config reads SAFARICOM_* environment variables by default.

Installation

In a Laravel application:

composer require statum/safaricom-daraja-sdk
php artisan vendor:publish --tag=safaricom-daraja-config

The package auto-discovers the service provider, so no manual provider registration is required.

Configuration

Update your .env file with the required values:

SAFARICOM_CONSUMER_KEY=your-consumer-key
SAFARICOM_CONSUMER_SECRET=your-consumer-secret
SAFARICOM_ENVIRONMENT=sandbox
SAFARICOM_TIMEOUT=30
SAFARICOM_CONNECT_TIMEOUT=10

Set SAFARICOM_ENVIRONMENT to sandbox or production.

The published config uses these keys:

consumer_key
consumer_secret
environment
timeout
connect_timeout
default_headers

default_headers is an array and is merged into the outgoing request headers.

Usage

Resolve the client from Laravel’s container and use the typed helper methods. See Examples and Examples for usage patterns.

If you are not using Laravel, you can ignore the provider entirely.

Error Handling

The SDK throws three package-specific exceptions you should catch in application code:

ConfigurationException for invalid local configuration or invalid DTO values
TransportException for network, DNS, TLS, or Guzzle transport failures
ApiException for Safaricom HTTP errors or invalid API responses

See Examples for a catch-and-inspect pattern.

Notes:

SafaricomConfig throws if the consumer key or consumer secret is empty, or if timeouts are negative.
Most helper methods include bearer authentication automatically.
accessToken() uses HTTP Basic auth internally.
For invalid JSON responses, check decoded() before calling json() if you need to avoid an exception.

Running tests

composer install
composer test
composer analyse

Recommended release checks:

composer validate --strict --no-check-publish
composer audit
git diff --check

Research sources

Safaricom Daraja portal: https://developer.safaricom.co.ke/apis
PHP-FIG PSR-4: https://www.php-fig.org/psr/psr-4/
PHP-FIG PSR-12: https://www.php-fig.org/psr/psr-12/
Guzzle testing docs: https://docs.guzzlephp.org/en/stable/testing.html
PHPUnit 11 supported versions: https://phpunit.de/supported-versions.html

statum / safaricom-daraja-sdk

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

Features & Supported Services

Installation

Dependencies

Getting Started

Documentation Map

Quick start

Generating the STK Push password

Generating a security credential

Common Flows

STK Push

STK Push Query

C2B

B2B and B2C

Transaction Queries

Generic Request

Response Handling

Supported endpoint helpers

Laravel support

Installation

Configuration

Usage

Error Handling

Running tests

Research sources