Weave Code
Mpesa Laravel Package
safaricom/mpesa
Laravel package for Safaricom M-Pesa integration, simplifying STK Push, C2B, B2C, transaction status, and callback handling. Configure credentials, initiate payments, and reconcile responses with clean, expressive PHP APIs built for Laravel applications.
safaricom/mpesa is a PHP SDK for integrating Safaricom M-PESA payment services into Laravel and standalone PHP applications. It wraps the official Daraja API with clean, expressive methods, so you can initiate payments, query transactions, and handle callbacks without wrestling with raw HTTP requests.
- STK Push (Lipa na M-PESA) for customer-initiated payments
- C2B, B2C, and B2B transaction support
- Transaction status and reversal queries
- Simple configuration for consumer key, secret, and passkey
- Framework-agnostic core with Laravel-friendly usage
Frequently asked questions about Mpesa
- What is safaricom/mpesa used for?
- It is a framework-agnostic PHP client for Safaricom's Daraja REST APIs, covering OAuth token generation and products such as STK Push, STK Query, C2B registration and simulation, B2C, B2B, reversal, balance and transaction status. In a Laravel application it is best treated as a transport or anti-corruption layer behind your own gateway interface, not called directly from controllers or models. Its main value is canonical request and response payload shapes rather than Laravel-specific features.
- Is safaricom/mpesa a Laravel package?
- No. It is a thin PHP SDK and ships no service provider, facade, publishable config, queue integration or event hooks. Everything Laravel-shaped, including config, DI bindings, retries, jobs, webhook routes and persistence of CheckoutRequestID and MerchantRequestID, is work you own. You will typically wrap it in a first-party MpesaGateway service bound in a service provider.
- Does safaricom/mpesa support Laravel 10 or Laravel 11?
- Not out of the box. The last release was 2019-01-06 and its composer.json likely pins PHP around 7.0 to 7.2 and Guzzle 5 or 6, while Laravel 9 and later ship Guzzle 7 and require PHP 8.0 or newer. A composer require may fail outright or force a downgrade of the whole application. The practical route is to fork or vendor the client and rebuild it against Guzzle 7 and PHP 8.x.
- How do I install safaricom/mpesa in a Laravel app?
- You can attempt composer require safaricom/mpesa, but expect dependency conflicts on modern Laravel versions because of its 2019-era PHP and Guzzle constraints. Most teams instead vendor the source into app/Services/Mpesa or an internal package, drop unused sub-clients, and pin it to Guzzle 7 and PHP 8.x. After that, bind a config-driven MpesaGateway in a service provider and read credentials from config() backed by a secret manager.
- Does the SDK handle M-Pesa authentication and access tokens?
- It covers the Daraja OAuth token flow, but token lifecycle management is left to you. Tokens are short-lived, so cache them in the Laravel cache store with an expiry margin and never mint a new token per request. Credential handling for the consumer secret, passkey, initiator password and RSA security credential is also your responsibility, so keep them in a secret manager and never log payloads containing MSISDN or credentials.
- How should I handle M-Pesa callbacks and idempotency in Laravel?
- The SDK provides no idempotency or callback verification primitives, so implement them at the domain layer. Deduplicate on CheckoutRequestID, MerchantRequestID and TransID at the database level, and verify that callbacks actually originate from Safaricom. A queued listener behind a webhook route, writing to an mpesa_transactions table, gives you a reliable reconciliation source of truth.
- Is safaricom/mpesa actively maintained?
- No. The project shows roughly 197 stars and zero dependents, with the last release dated 2019-01-06, so there are no security patches or updates for Daraja changes. Daraja has since evolved with dynamic QR, Bill Manager, ratiba or standing orders and new result codes, and a 2019 client may cover only the core products. Treat it as a canonical reference implementation rather than a long-term dependency, and plan to own a fork.
- What M-Pesa products does the SDK cover?
- The client targets the Daraja REST surface: OAuth token, STK Push and STK Query, C2B register and simulate, B2C, B2B, reversal, balance and transaction status. Whether each product's current request and response schema is fully covered is a separate question, because the SDK predates several Daraja additions. Confirm which products are in scope for v1 and validate their payloads against current Safaricom documentation before committing.
- How do I test an M-Pesa integration in Laravel without hitting production?
- Use Safaricom's Daraja sandbox and make the base URL configurable so sandbox and production differ only by environment. In tests, fake the underlying HTTP client or bind a fake MpesaGateway so you can assert on typed DTOs rather than raw arrays. Because the SDK has untested error and result-code paths, build a result-code map covering codes such as 0, 1, 1032, 1037 and 2001, and test each mapped domain outcome explicitly.
- Should I use safaricom/mpesa or build my own M-Pesa client?
- Given the abandoned upstream, outdated dependencies and missing idempotency and retry primitives, a small in-house client of roughly 400 lines or a maintained community Laravel package often wins on total cost. The SDK is still valuable as a reference for payload shapes and endpoint structure. If you do adopt it, fork it under your namespace, wrap it with Laravel HTTP retry policies and explicit timeouts, and assign clear ownership and a review cadence.
Weaver
How can I help you explore Laravel packages today?