PHPackages                             mutebesi/safaricom-mpesa-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Payment Processing](/categories/payments)
4. /
5. mutebesi/safaricom-mpesa-php

ActiveLibrary[Payment Processing](/categories/payments)

mutebesi/safaricom-mpesa-php
============================

A full-featured M-Pesa PHP SDK with advanced callback routing and proxy capabilities.

v1.0.0(1mo ago)02↓100%MITPHPPHP >=7.4

Since May 9Pushed 1mo agoCompare

[ Source](https://github.com/mutebesi/Safaricom-Mpesa-PHP)[ Packagist](https://packagist.org/packages/mutebesi/safaricom-mpesa-php)[ RSS](/packages/mutebesi-safaricom-mpesa-php/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

M-Pesa PHP SDK Plus 🚀
=====================

[](#m-pesa-php-sdk-plus-)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![PHP Version](https://camo.githubusercontent.com/6c7e8ab59af0decb32b0637fa2ef48a9b15feb2682ccdaa5ce7bf6f8c5059849/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e342d3838393262662e737667)](https://php.net)

A robust, modern, and high-performance PHP SDK for Safaricom's M-Pesa Daraja API. This SDK is designed for developers who need more than just simple API wrappers.

### 🌟 Why "Plus"?

[](#-why-plus)

Unlike standard M-Pesa libraries, this SDK features an **Advanced Callback Router**. It allows you to use a **single Callback URL** to manage transactions for **multiple websites or services** by intelligently forwarding the transaction data based on custom rules.

📋 System Requirements
---------------------

[](#-system-requirements)

- **PHP:** 7.4 or higher (8.1+ recommended)
- **Extensions:** `php-curl`, `php-json`, `php-pdo` (if using Database storage)
- **Safaricom Credentials:** Consumer Key, Consumer Secret, and LNM Passkey.
- **Server:** A publicly accessible URL (for Callbacks) with SSL (recommended).

✨ Key Features
--------------

[](#-key-features)

- **Intelligent Callback Forwarding:** Proxy M-Pesa callbacks to different backend systems.
- **Lipa Na M-Pesa Online (STK Push):** Quick and easy integration for customer-initiated payments.
- **B2C & C2B Support:** Full support for business-to-customer and customer-to-business transactions.
- **Robust Logging:** Detailed logs for every transaction and callback attempt.
- **PSR-4 Compliant:** Easy integration with modern PHP frameworks (Laravel, Symfony, etc.).

🚀 Quick Start
-------------

[](#-quick-start)

### 1. Installation

[](#1-installation)

Clone this repository or include it in your project:

```
git clone https://github.com/mutebesi/safaricom-mpesa-php.git
```

If using Composer:

```
composer require mutebesi/safaricom-mpesa-php
```

### 2. Configuration

[](#2-configuration)

Edit `config/config.php` with your Daraja credentials:

```
'mpesa' => [
    'consumer_key'    => 'YOUR_CONSUMER_KEY',
    'consumer_secret' => 'YOUR_CONSUMER_SECRET',
    'shortcode'       => '174379',
    'passkey'         => 'bfb279...',
    'env'             => 'sandbox',
],
```

### 3. Setup Callback Routing

[](#3-setup-callback-routing)

Define where you want your callbacks to go based on the `AccountReference` or `BillRefNumber`:

```
'routing' => [
    'SITE_A' => 'https://website-a.com/api/mpesa-callback',
    'SITE_B' => 'https://website-b.com/payments/webhook',
],
```

### 4. Initiate a Payment (STK Push)

[](#4-initiate-a-payment-stk-push)

```
use MpesaSdk\Mpesa;

$mpesa = new Mpesa($key, $secret, 'sandbox');
$result = $mpesa->stkPush(
    $shortcode, $passkey, '100', '2547XXXXXXXX', 'SITE_A_REF123', 'Payment Desc', $callbackUrl
);
```

💾 Database Integration (Optional)
---------------------------------

[](#-database-integration-optional)

If you want to save every transaction automatically, use the built-in `DatabaseStore` class:

1. **Configure DB in `config/config.php`**
2. **Initialize and Setup Table:**

```
use MpesaSdk\DatabaseStore;

$db = new DatabaseStore($host, $dbname, $user, $pass);
$db->setupTable(); // Creates the 'mpesa_transactions' table automatically
```

3. **Save in your callback listener:**

```
$db->saveStkCallback($mpesaData);
```

📄 Understanding the Data
------------------------

[](#-understanding-the-data)

M-Pesa sends transaction notifications as JSON. For a detailed breakdown of the fields (like `MpesaReceiptNumber` and `ResultCode`), see the **Callback Data Structure Guide**.

🔄 How the Callback Proxy Works
------------------------------

[](#-how-the-callback-proxy-works)

When Safaricom sends a payment notification to your `callback.php`:

1. The **Callback Router** intercepts the JSON.
2. It looks at the `AccountReference` (e.g., `SITE_A_REF123`).
3. It finds the matching rule (e.g., `SITE_A`).
4. It **re-sends (proxies)** the exact JSON to the mapped target URL.
5. It logs the result of the forwarding attempt.

This solves the "Single Callback URL" limitation on the Daraja portal.

🛠 Advanced Usage
----------------

[](#-advanced-usage)

Check the `examples/` directory for detailed implementations of:

- STK Push Query
- Transaction Status
- Balance Inquiry

🔒 Security
----------

[](#-security)

- **SSL Verification:** Ensure you enable SSL verification in production.
- **IP Whitelisting:** It is recommended to whitelist Safaricom's IP addresses on your server.
- **Validation:** Always validate the `ResultCode` in your final target endpoints.

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License
---------

[](#-license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance94

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity31

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

31d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/94f8f511a2b8ee6afa6df6d5ea320da369600bff992b3f285a443b1cf8521bdb?d=identicon)[mutebesi](/maintainers/mutebesi)

---

Top Contributors

[![mutebesi](https://avatars.githubusercontent.com/u/63821642?v=4)](https://github.com/mutebesi "mutebesi (8 commits)")

### Embed Badge

![Health badge](/badges/mutebesi-safaricom-mpesa-php/health.svg)

```
[![Health](https://phpackages.com/badges/mutebesi-safaricom-mpesa-php/health.svg)](https://phpackages.com/packages/mutebesi-safaricom-mpesa-php)
```

###  Alternatives

[omnipay/coinbase

Coinbase driver for the Omnipay payment processing library

18570.2k1](/packages/omnipay-coinbase)[yenepay/php-sdk

YenePay SDK for PHP

112.7k](/packages/yenepay-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)