Download the PHP package j-muiruri/daraja-php-sdk without Composer

j-muiruri/daraja-php-sdk

A modern, fully typed PHP 8.2+ SDK built for the Safaricom Daraja 3.0 M-Pesa API.

Index

• System Requirements
• Installation & Setup
• Integration Guides
• Initialization
• Feature Matrix
• API Reference
  • STK Push (Lipa na M-Pesa Online)
  • C2B (Customer to Business)
  • B2C (Disbursements)

System Requirements

• PHP 8.2 or higher
• Composer dependency manager
• Extensions: ext-openssl, ext-json
• HTTP Client: Guzzle 7.x

Installation & Setup

Pull the package into your project via Composer:

Quick Start

1. Create the client

Or read directly from environment variables:

Feature Matrix

API Reference

STK Push (Lipa na M-Pesa Online)

Initiates a payment prompt on the customer's phone. The customer enters their M-Pesa PIN to confirm.

STK Push Callback payload (POST to your callbackUrl):

C2B — Register URLs

Register validation and confirmation URLs before your customers start paying.

⚠️ WARNING

B2C, B2B, Reversals, and Account Balance operations explicitly require you to supply an initiatorName and valid securityCredential string within your initialization configuration. Safely disburse outbound capital transfers from your operational utility wallets.

B2C — Disbursements

Send money to customers (salaries, promotions, refunds).

Requires initiatorName and securityCredential in Config.

B2C Result callback payload (async, POST to resultUrl):

B2C Account Top Up

Moves funds from your paybill's Working account into a B2C shortcode's Utility account, so that shortcode has balance available to disburse. Same underlying /mpesa/b2b/v1/paymentrequest endpoint as B2B, restricted to CommandID: BusinessPayToBulk.

Callback payload matches the standard B2B result shape — handle it via onB2B() / parseB2B().

Business To Pochi

Pays a customer's "Pochi La Biashara" business wallet instead of their personal M-Pesa account. Amounts are constrained to 10–250,000 KES per transaction.

Callback payload matches the standard B2C result shape — handle it via onB2C() / parseB2C().

M-Pesa Ratiba — Standing Orders

Sets up a recurring payment: the customer approves once via a PIN prompt, then M-Pesa auto-executes on your schedule with no further customer action.

⚠️ Commercial API — sandbox testing is self-serve, but going live requires a commercial agreement with Safaricom (email [email protected]) before this is attached to your shortcode.

Handle the callback (its own responseHeader/responseBody envelope) with:

Pull Transactions

Recovers C2B transactions that never reached your callback URLs — one-time register(), then query() per reconciliation window (max 48 hours of history).

⚠️ Safaricom's own docs are inconsistent about whether query() is GET or POST — see the docblock on PullTransaction::query() for details. This SDK sends POST with a JSON body; verify against your sandbox app.

B2B — Pay Suppliers

B2B Express Checkout (USSD Push to Till)

Prompts a fellow merchant to pay you from their own till, via a USSD PIN prompt. Unlike other operator APIs, this endpoint does not use initiatorName/securityCredential — auth is handled entirely by your app's consumer key/secret.

Handle the callback with CallbackProcessor:

⚠️ This is a merchant-to-merchant product — the receiver must have a paybill able to receive B2B Express Checkout payments, and the payer must have a till number. See the official docs for onboarding requirements.

Transaction Status

Reconcile transactions when callbacks were missed.

Account Balance

Transaction Reversal

Dynamic QR Code

SIM Swap

Query the last date a customer's SIM was swapped — a fraud/risk signal for banking due diligence. Returns a default date of 01-01-1900 00:00 if the SIM has not swapped in the last 3 months.

⚠️ Commercial API — requires a signed commercial agreement with Safaricom before onboarding (email [email protected] or your account manager). Won't function on a plain sandbox app without it. KES 50,000 connection fee; first 200,000 requests free, then KES 1 each.

IMSI

Returns a hashed IMSI, network registration date, and last SIM swap date for a Safaricom number — a fuller fraud/risk-check signal set than SIM Swap alone.

⚠️ Commercial API — same onboarding requirements as SIM Swap above. KES 20 per call.

IoT SIM Management

Manages Safaricom IoT SIM cards — activation, suspension, status checks, renaming — and their messaging channel, via the /simportal/* product family.

⚠️ Requires the separate Safaricom IoT SIM Management platform product — not unlocked by a standard M-Pesa Daraja app. Uses the same OAuth Bearer token as the rest of this SDK.

See IotSimManagement's docblock for the full endpoint list (13 operations across SIM lifecycle and messaging).

Phone Number Formats

The PhoneNumber value object accepts any common Kenyan format:

Invalid numbers throw Daraja\Exceptions\ValidationException.

Security Credentials (B2C, B2B, Reversal, Balance)

These APIs require the initiator password to be encrypted with Safaricom's public certificate.

Step 1 — Download the certificate from the Daraja portal:

• Sandbox: https://developer.safaricom.co.ke/sites/default/files/cert/sandbox/cert.cer
• Production: https://developer.safaricom.co.ke/sites/default/files/cert/prod/cert.cer

Step 2 — Generate the credential once and store it:

Error Handling

Laravel Integration

Testing

Contributing

1. Fork the repo and create a feature branch
2. Write tests first — every new feature needs passing tests
3. Run composer test and composer analyse before opening a PR
4. Follow PSR-12 coding style

License

MIT — see LICENSE.