PHPackages                             ysg/laravel-mpesa - 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. ysg/laravel-mpesa

ActiveLibrary

ysg/laravel-mpesa
=================

Official Safaricom Daraja M-Pesa integration for Laravel built on ysg/payment-core.

v1.1.0(1mo ago)05↓66.7%MITPHPPHP ^8.3

Since Jul 13Pushed 1mo agoCompare

[ Source](https://github.com/Jdeu-ND/ysg-laravel-mpesa)[ Packagist](https://packagist.org/packages/ysg/laravel-mpesa)[ RSS](/packages/ysg-laravel-mpesa/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (6)Versions (3)Used By (0)

YSG Laravel M-Pesa
==================

[](#ysg-laravel-m-pesa)

Official Laravel integration for Safaricom Daraja M-Pesa built on **ysg/payment-core**.

`ysg/laravel-mpesa` provides a production-ready implementation of the shared `PaymentProcessor` contract, allowing Laravel applications to initiate M-Pesa STK Push payments while remaining decoupled from provider-specific APIs.

---

Features
--------

[](#features)

- Laravel 11+
- Safaricom Daraja STK Push
- Provider-agnostic payment architecture
- Immutable readonly DTOs
- OAuth token caching with automatic refresh
- Automatic callback routing and parsing
- Strongly typed configuration
- SOLID, service-oriented architecture
- PHPUnit test coverage
- Verified against the Safaricom Daraja Sandbox

---

Requirements
------------

[](#requirements)

- PHP 8.3+
- Laravel 11+

---

Installation
------------

[](#installation)

Install the package via Composer.

```
composer require ysg/laravel-mpesa
```

The shared **`ysg/payment-core`** package will be installed automatically as a dependency.

---

Publish Configuration
---------------------

[](#publish-configuration)

Publish the configuration file.

```
php artisan vendor:publish --tag=mpesa-config
```

This creates:

```
config/mpesa.php

```

The package also automatically registers the callback endpoint:

```
POST /mpesa/callback

```

---

Configuration
-------------

[](#configuration)

Configure your `.env` file.

```
MPESA_DRIVER=daraja

MPESA_ENVIRONMENT=sandbox

MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=

MPESA_SHORTCODE=
MPESA_PASSKEY=

MPESA_CALLBACK_URL=https://example.com/mpesa/callback

MPESA_TIMEOUT=30
MPESA_RETRY_TIMES=3
MPESA_RETRY_SLEEP=500
```

### Configuration Options

[](#configuration-options)

KeyDescription`driver`Payment provider implementation. Defaults to `daraja`.`environment``sandbox` or `production`.`consumer_key`Daraja Consumer Key.`consumer_secret`Daraja Consumer Secret.`shortcode`Business shortcode.`passkey`STK Push passkey.`callback_url`Public callback endpoint.`timeout`HTTP request timeout (seconds).`retry_times`Number of HTTP retry attempts.`retry_sleep`Delay between retries (milliseconds).---

Initiating an STK Push
----------------------

[](#initiating-an-stk-push)

```
use Ysg\LaravelMpesa\Processors\MpesaPaymentProcessor;
use Ysg\PaymentCore\DTOs\Money;
use Ysg\PaymentCore\DTOs\Payer;
use Ysg\PaymentCore\DTOs\PaymentRequest;

$processor = app(MpesaPaymentProcessor::class);

$response = $processor->initiatePayment(
    new PaymentRequest(
        money: new Money('100.00', 'KES'),

        payer: new Payer(
            phone: '0712345678',
        ),

        reference: 'INV-1001',

        description: 'Invoice Payment',
    ),
);

if ($response->pending()) {
    // STK Push accepted by Daraja.
}
```

---

Handling Callbacks
------------------

[](#handling-callbacks)

Incoming callbacks are automatically received through:

```
POST /mpesa/callback

```

The package parses the Daraja payload into a strongly typed `CallbackRequest` and dispatches it through Laravel's event dispatcher.

Applications can listen for the callback and perform their own payment reconciliation.

```
use Illuminate\Support\Facades\Event;
use Ysg\LaravelMpesa\DTOs\CallbackRequest;

Event::listen(function (CallbackRequest $callback) {

    if ($callback->failed()) {
        return;
    }

    $receipt = $callback->receiptNumber;

    $reference = $callback->providerReference();

    // Perform your business logic...
});
```

The package intentionally does not update your database or perform payment reconciliation. Those responsibilities remain within your application.

---

Payment Core Integration
------------------------

[](#payment-core-integration)

`ysg/laravel-mpesa` implements the shared `PaymentProcessor` contract from **ysg/payment-core**.

Depending on the shared payment abstractions rather than provider-specific implementations allows applications to introduce additional payment providers in the future without changing their payment workflows.

---

Testing
-------

[](#testing)

Run the test suite.

```
vendor/bin/phpunit
```

The package includes:

- Unit tests
- Feature tests
- End-to-end verification against the Safaricom Daraja Sandbox

---

Contributing
------------

[](#contributing)

Contributions are welcome.

Please ensure that:

- Code follows PSR-12.
- New functionality includes appropriate tests.
- Public APIs remain backwards compatible where practical.
- The package remains lightweight and provider-agnostic.

---

License
-------

[](#license)

This package is open-sourced under the MIT License.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance90

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 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

Every ~1 days

Total

2

Last Release

47d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/7213a6c1f672e2bd2be046a5bc833b9813b0d755a90310ef61d811075c679f5b?d=identicon)[Jdeu-ND](/maintainers/Jdeu-ND)

---

Top Contributors

[![Jdeu-ND](https://avatars.githubusercontent.com/u/202858785?v=4)](https://github.com/Jdeu-ND "Jdeu-ND (2 commits)")

---

Tags

laravelpaymentsmpesakenyafintechsafaricomdaraja

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ysg-laravel-mpesa/health.svg)

```
[![Health](https://phpackages.com/badges/ysg-laravel-mpesa/health.svg)](https://phpackages.com/packages/ysg-laravel-mpesa)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3365.5M359](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

80732.6M270](/packages/laravel-mcp)[api-platform/laravel

API Platform support for Laravel

58190.1k22](/packages/api-platform-laravel)[intervention/image-laravel

Laravel Integration of Intervention Image

16210.8M228](/packages/intervention-image-laravel)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1346.4k29](/packages/fleetbase-core-api)

PHPackages © 2026

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