Laravel M-Pesa STK Push Sandbox

A modern, open-source Laravel package for integrating M-Pesa STK Push (sandbox/testing) with best practices. Focused on developer experience, security, and easy integration.

Table of Contents

• Requirements
• Quick Start
• Configuration
• Usage Example
• Callback Handling
• Testing
• Contributing & Feedback
• Support
• Author
• License

Requirements

• PHP >= 8.0
• Laravel >= 9.0

Quick Start

composer require me12free/laravel-mpesa-stkpush-sandbox

Publish Config & Migration

php artisan vendor:publish --provider="MpesaSandbox\MpesaSandboxServiceProvider" --tag=config
php artisan vendor:publish --provider="MpesaSandbox\MpesaSandboxServiceProvider" --tag=migrations

Configuration

Add to your .env:

MPESA_CONSUMER_KEY=your_sandbox_consumer_key
MPESA_CONSUMER_SECRET=your_sandbox_consumer_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_sandbox_passkey
MPESA_CALLBACK_URL=https://your-ngrok-url/api/mpesa/callback?secret=your_shared_secret
MPESA_CALLBACK_SECRET=your_shared_secret

Usage Example

use MpesaSandbox\MpesaSandbox;

$mpesa = app(MpesaSandbox::class);
$response = $mpesa->initiateStkPush('2547XXXXXXXX', 10);

Callback Handling

See README-callback.md for a full example controller and route.

Security: Always verify the shared secret in your callback controller:

if ($request->query('secret') !== env('MPESA_CALLBACK_SECRET')) {
    abort(403, 'Invalid secret');
}

Testing

This package uses Pest and Orchestra Testbench for isolated, modern package testing.

composer install
vendor/bin/pest

Contributing & Feedback

Pull requests are welcome! Please see the CONTRIBUTING.md guide (or open an issue for questions).

• Star this repo: If you like this package, please star it on GitHub to show your support!
• Rate on Packagist: Leave a rating or review on Packagist if you find it useful.
• Become a contributor: Open a pull request or issue to join the contributors list. See CONTRIBUTING.md for full guidelines.

Support

If you find this package useful, consider supporting development:

For help or questions, open an issue or email johnewoi72@gmail.com.

Author

John Ekiru (johnewoi72@gmail.com)

License

MIT — see LICENSE