PHPackages botnetdobbs/laravel-mpesa-sdk - 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. [API Development](/categories/api) 4. / 5. botnetdobbs/laravel-mpesa-sdk ActiveLibrary[API Development](/categories/api) botnetdobbs/laravel-mpesa-sdk ============================= Laravel M-Pesa Integration Package 1.1.1(2w ago)64832MITPHPPHP ^8.2|^8.3|^8.4CI passing Since Dec 7Pushed 1mo ago1 watchersCompare [ Source](https://github.com/botnet-dobbs/laravel-mpesa-sdk)[ Packagist](https://packagist.org/packages/botnetdobbs/laravel-mpesa-sdk)[ RSS](/packages/botnetdobbs-laravel-mpesa-sdk/feed)WikiDiscussions main Synced 4d ago READMEChangelog (4)Dependencies (21)Versions (8)Used By (0) Laravel M-Pesa Integration Package ================================== [](#laravel-m-pesa-integration-package) [![build](https://github.com/botnet-dobbs/laravel-mpesa-sdk/actions/workflows/main.yml/badge.svg)](https://github.com/botnet-dobbs/laravel-mpesa-sdk/actions/workflows/main.yml) [![Packagist Downloads](https://camo.githubusercontent.com/e338e0634c72734def6d4b7e4634169a7cc43bd1255f391d23401c603f276258/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626f746e6574646f6262732f6c61726176656c2d6d706573612d73646b)](https://camo.githubusercontent.com/e338e0634c72734def6d4b7e4634169a7cc43bd1255f391d23401c603f276258/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626f746e6574646f6262732f6c61726176656c2d6d706573612d73646b) Laravel package for integrating with Safaricom"s M-Pesa payment gateway. Supports STK Push, B2C, B2B, balance queries, transaction status checks, and payment reversals. For the most current API documentation and updates, always refer to the [Safaricom Developer Portal](https://developer.safaricom.co.ke/APIs). Requirements ------------ [](#requirements) - PHP 8.2+ Laravel VersionLaravel 10.xLaravel 11.xLaravel 12.xLaravel 13.xInstallation ------------ [](#installation) Install the package via Composer: ``` composer require botnetdobbs/laravel-mpesa-sdk ``` Publish the configuration file: ``` php artisan vendor:publish --tag=mpesa-config ``` Configuration ------------- [](#configuration) Add the following variables to your `.env` file: ``` MPESA_CONSUMER_KEY=your_consumer_key MPESA_CONSUMER_SECRET=your_consumer_secret MPESA_LIPA_NA_MPESA_PASSKEY=your_lipa_na_mpesa_passkey MPESA_INITIATOR_NAME=your_initiator_name MPESA_INITIATOR_PASSWORD=your_initiator_password MPESA_CERTIFICATE_PATH=your_downloaded_mpesa_certificate_path MPESA_ENV=sandbox # or "live" for production ``` More can be added as per the config file below. ### Configuration Options [](#configuration-options) The published config file (`config/mpesa.php`) contains the following options: For the certificate, [download it](https://developer.safaricom.co.ke/apis/GettingStarted) under M-Pesa API Certificates. ``` return [ "consumer_key" => env("MPESA_CONSUMER_KEY"), "consumer_secret" => env("MPESA_CONSUMER_SECRET"), "lipa_na_mpesa_passkey" => env( "MPESA_LIPA_NA_MPESA_PASSKEY", "bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919" ), "certificate_path" => env("MPESA_CERTIFICATE_PATH"), "environment" => env("MPESA_ENV", "sandbox"), "initiator" => [ 'name' => env("MPESA_INITIATOR_NAME"), 'password' => env("MPESA_INITIATOR_PASSWORD"), ], "callbacks" => [ "base_url" => env("MPESA_CALLBACK_BASE_URL", "https://example.com"), "paths" => [ "stk" => [ "result" => "/api/mpesa/callback/stk", ], "b2c" => [ "result" => "/api/mpesa/callback/b2c", "timeout" => "/api/mpesa/callback/b2c/timeout", ], // Add more callback paths here ] ], "business" => [ "short_codes" => [ "default" => env("MPESA_SHORT_CODE"), "till" => env("MPESA_TILL_NUMBER"), "paybill" => env("MPESA_PAYBILL_NUMBER"), ], ], "defaults" => [ "timeout" => 60, "connect_timeout" => 15, ] ]; ``` Usage ----- [](#usage) ``` use Botnetdobbs\Mpesa\Contracts\Client; use Botnetdobbs\Mpesa\Exceptions\MpesaException; use Illuminate\Http\JsonResponse; class PaymentController extends Controller { public function __construct( private readonly Client $mpesaClient ) {} public function initiatePayment(): JsonResponse { try { $response = $this->mpesaClient->stkPush([...]); if ($response->isSuccessful()) { $data = $response->getData(); // Persist CheckoutRequestID against your order/payment record. // Your callback handler uses it to match the async notification back to this transaction and to guard against duplicate processing. // e.g. $payment->update(['checkout_request_id' => $data->CheckoutRequestID]); return response()->json(['message' => 'Payment initiated successfully.']); } // M-Pesa accepted the request but returned a business-level error. return response()->json(['message' => $response->getResponseDescription()], 422); } catch (MpesaException $e) { // Thrown on HTTP-level failures (4xx/5xx from the M-Pesa API). logger()->error('mpesa.stk_push.error', ['error' => $e->getMessage()]); return response()->json(['message' => 'Payment initiation failed. Please try again.'], 502); } catch (\InvalidArgumentException $e) { // Thrown when required fields are missing before the HTTP call is made. logger()->error('mpesa.stk_push.validation', ['error' => $e->getMessage()]); return response()->json(['message' => $e->getMessage()], 400); } } } ``` ### STK Push (Lipa Na M-Pesa Online) [](#stk-push-lipa-na-m-pesa-online) ``` $response = $this->mpesaClient->stkPush([ "BusinessShortCode" => "174379", // Organization's shortcode (Paybill or Buygoods - A 5 to 6-digit account number) used to identify an organization and receive the transaction. "TransactionType" => "CustomerPayBillOnline", // or CustomerBuyGoodsOnline "Amount" => 1, "PhoneNumber" => "254722000000", // The Mobile Number to receive the STK Pin Prompt. "CallBackURL" => config('mpesa.callbacks.base_url', "https://example.com") . config('mpesa.callbacks.paths.stk_push.result', "/callback"), // Valid secure URL that is used to receive notifications from M-Pesa API. "AccountReference" => "Test", "TransactionDesc" => "Test Payment" ]); ``` ### STK Push (check the status of a Lipa Na M-Pesa Online Payment.) [](#stk-push-check-the-status-of-a-lipa-na-m-pesa-online-payment) ``` $response = $this->mpesaClient->stkQuery([ "BusinessShortCode" => "174379", "CheckoutRequestID" => "ws_CO_260520211133524545" ]); ``` ### B2C Payment (Business to Customer) [](#b2c-payment-business-to-customer) ``` $response = $this->mpesaClient->b2c([ "OriginatorConversationID" => "unique-id", "InitiatorName" => "testapi", "CommandID" => "BusinessPayment", // Or "SalaryPayment", "PromotionPayment" "Amount" => 100, "PartyA" => "600000", // Your business shortcode "PartyB" => "254722000000", // Customer phone number "Remarks" => "Test payment", "QueueTimeOutURL" => "https://example.com/queue-timeout", // The URL to be specified in your request that will be used by API Proxy to send notification incase the payment request is timed out while awaiting processing in the queue. "ResultURL" => "https://example.com/result", // The URL to be specified in your request that will be used by M-PESA to send notification upon processing of the payment request. "Occasion" => "Test" ]); ``` ### B2B Payment (Business to Business) [](#b2b-payment-business-to-business) B2B parameter naming convention is camelCase instead of PascalCase like the other endpoints on the [Safaricom Developer Portal](https://developer.safaricom.co.ke/APIs/B2BExpressCheckout). Retained as is ``` $response = $this->mpesaClient->b2b([ "primaryShortCode" => "000001", // Sender business shortcode "receiverShortCode" => "000002", // Receiver business shortcode "amount" => 100, "paymentRef" => "INV001", // Your reference "callbackUrl" => "https://example.com/callback", "partnerName" => "Vendor Name", "RequestRefID" => "unique-id-123" // Unique identifier for the request ]); ``` ### C2B Register (Customer to Business) [](#c2b-register-customer-to-business) ``` $response = $this->mpesaClient->c2bRegister([ "ShortCode" => "600000", "ResponseType" => "Completed", // Or "Cancelled" "ConfirmationURL" => "https://example.com/confirmation", // The URL that receives the confirmation request from API upon payment completion. "ValidationURL" => "https://example.com/validation", // The URL that receives the validation request from the API upon payment submission. The validation URL is only called if the external validation on the registered shortcode is enabled. (By default External Validation is disabled). ]); ``` ### C2B Simulate Payment (Sandbox Environment Only) [](#c2b-simulate-payment-sandbox-environment-only) ``` $response = $this->mpesaClient->c2bSimulate([ "ShortCode" => "600000", "CommandID" => "CustomerPayBillOnline", // Or "CustomerBuyGoodsOnline" "Amount" => 100, "Msisdn" => "254722000000", // Customer phone number "BillRefNumber" => "INV001" // Optional reference ]); ``` ### Account Balance Query [](#account-balance-query) ``` $response = $this->mpesaClient->accountBalance([ "Initiator" => "testapi", // The credential/username used to authenticate the transaction request "CommandID" => "AccountBalance", "PartyA" => "600000", // Your business shortcode "IdentifierType" => "4", // 4 for organization shortcode "Remarks" => "Balance query", "QueueTimeOutURL" => "https://example.com/timeout", // The end-point that receives a timeout message. "ResultURL" => "https://example.com/result", // It indicates the destination URL which Daraja should send the result message to. ]); ``` ### Transaction Status Query [](#transaction-status-query) ``` $response = $this->mpesaClient->transactionStatus([ "Initiator" => "testapi", "CommandID" => "TransactionStatusQuery", "TransactionID" => "OEI2AK4Q16", // The M-Pesa transaction ID "PartyA" => "600000", // Your business shortcode "IdentifierType" => "4", // 4 for organization shortcode "ResultURL" => "https://example.com/result", "QueueTimeOutURL" => "https://example.com/timeout", "Remarks" => "Status check", "Occasion" => "Transaction query", // Optional parameter ]); ``` ### Transaction Reversal [](#transaction-reversal) ``` $response = $this->mpesaClient->reversal([ "Initiator" => "testapi", "CommandID" => "TransactionReversal", "TransactionID" => "OEI2AK4Q16", // The M-Pesa transaction ID to reverse "Amount" => 100, // Amount to reverse "ReceiverParty" => "600000", // Organization receiving the reversal "RecieverIdentifierType" => "4", // 4 for organization shortcode "ResultURL" => "https://example.com/result", "QueueTimeOutURL" => "https://example.com/timeout", "Remarks" => "Reversal request", "Occasion" => "Transaction reversal" ]); ``` ### Response Handling [](#response-handling) All methods return a standard Response with the following methods: ``` // Get the raw response data $data = $response->getData(): object // Check if the request was successful $isSuccessful = $response->isSuccessful(): bool // Get specific response fields $code = $response->getResponseCode(): int $description = $response->getResponseDescription(): string $resultCode = $response->getResultCode(): int // STK Query $resultDescription = $response->getResultDescription(): string // STK Query ``` ### Example Usage [](#example-usage) ``` $response = $this->mpesaClient->stkPush([...]); $data = $response->getData(); // Access properties using object syntax $merchantRequestId = $data->MerchantRequestID; $checkoutRequestId = $data->CheckoutRequestID; ``` Error Handling -------------- [](#error-handling) The package throws `MpesaException` for various error scenarios: ``` use Botnetdobbs\Mpesa\Exceptions\MpesaException; try { $response = $this->mpesaClient->stkPush([...]); if ($response->isSuccessful()) { $data = $response->getData(); } } catch (MpesaException $e) { // Handle the error logger()->error("M-Pesa error: " . $e->getMessage()); } ``` Callback Handling ----------------- [](#callback-handling) M-Pesa calls your `CallBackURL` / `ResultURL` asynchronously after processing a transaction. ### Recommended Processing Pipeline [](#recommended-processing-pipeline) ``` Safaricom Callback ↓ Log + persist raw request ← do this before anything else ↓ Return HTTP 200 + ResultCode 0 ← release Safaricom immediately ↓ Dispatch queue job ↓ Idempotency check ← skip if already handled ↓ Apply business logic ↓ Mark processed / failed / reconciled ``` Your callback endpoint has one job: confirm receipt and hand off. All actual processing happens in the background. ### Payment State Lifecycle [](#payment-state-lifecycle) Track each payment through clear, explicit states. Always set a status rather than guessing it from missing records. StateMeaning`received`Callback saved to the database, not yet processed`queued`Handed off to a background job`processed`Payment confirmed and order fulfilled`failed`M-Pesa reported a failure (wrong PIN, insufficient funds, cancelled)`reconciled`Status confirmed later via `transactionStatus()` after a timeout or mismatch### Production Rules [](#production-rules) - **Save the raw payload before doing anything else.** If something breaks after you respond to Safaricom, this saved copy is how you recover. Store `$request->getContent()` or `$request->all()` as-is. - **Write a log entry the moment the request arrives.** If a background job fails silently, the log confirms the callback was received and gives you enough context to replay it. - **Use `$responder->success()` even when a payment fails.** A wrong PIN or cancelled payment is not your server failing. It is Safaricom reporting the outcome. Use `$responder->failed()` only when your server itself could not handle the request, for example a broken payload or a failed security check. - **Callback handling must be idempotent.** Safaricom can send the same callback more than once. Before doing any work, check the `CheckoutRequestID` or `ConversationID` against your records and skip if it was already handled. ### Verify the Callback Source (IP Whitelisting) [](#verify-the-callback-source-ip-whitelisting) Your callback routes are public endpoints, anyone who finds the URL can send a fake request to it. Safaricom only sends callbacks from a small, fixed set of IP addresses, so checking the request's origin IP against that list is a cheap and reliable first line of defense. Safaricom publishes this IP list in the [Getting Started guide](https://developer.safaricom.co.ke/apis/GettingStarted). Store it in your own config (e.g. `config/mpesa.php` or an env-driven array) rather than hardcoding it, so it is easy to update if Safaricom ever adds an IP. A simple middleware applied to your callback routes: ``` namespace App\Http\Middleware; use Closure; use Illuminate\Http\Request; use Symfony\Component\HttpFoundation\Response; class VerifyMpesaIp { public function handle(Request $request, Closure $next): Response { if (! $request->ip() || ! in_array($request->ip(), config('mpesa.allowed_callback_ips', []), true)) { // Not from Safaricom. Treat this as a failed security check, // not a business outcome, so return failed() rather than success(). return app(\Botnetdobbs\Mpesa\Contracts\CallbackResponder::class)->failed('Forbidden'); } return $next($request); } } ``` Apply it only to your callback routes, the ones Safaricom calls into your app. It is not needed on the SDK's outbound calls (`stkPush`, `b2c`, etc.) since those are your app calling Safaricom and are already secured via the OAuth token. ### Route Setup [](#route-setup) Register callback routes in `routes/api.php`. Routes defined here are already exempt from CSRF verification. ``` use App\Http\Controllers\MpesaCallbackController; Route::prefix('mpesa/callback')->group(function () { Route::post('stk', [MpesaCallbackController::class, 'handleStkCallback']); Route::post('b2c/result', [MpesaCallbackController::class, 'handleB2cResult']); }); ``` ### MpesaCallbackController [](#mpesacallbackcontroller) ``` namespace App\Http\Controllers; use Botnetdobbs\Mpesa\Contracts\CallbackProcessor; use Botnetdobbs\Mpesa\Contracts\CallbackResponder; use Illuminate\Contracts\Support\Responsable; use Illuminate\Http\Request; use Illuminate\Support\Facades\Log; class MpesaCallbackController extends Controller { public function __construct( private readonly CallbackProcessor $processor, private readonly CallbackResponder $responder ) {} public function handleStkCallback(Request $request): Responsable { // 1. Log and save the raw request body before doing anything else. // If something breaks after you respond, this is how you recover. Log::info('mpesa.stk_callback.received', ['payload' => $request->all()]); // e.g. MpesaRawCallback::create(['payload' => $request->getContent(), 'type' => 'stk']); try { $result = $this->processor->handle($request); $data = $result->getData(); $checkoutRequestId = $data->Body->stkCallback->CheckoutRequestID ?? null; // 2. Idempotency check: verify this CheckoutRequestID has not been processed before. // Safaricom can send the same callback more than once, so skip duplicates. // e.g. if (Payment::where('checkout_request_id', $checkoutRequestId)->exists()) { ... } // 3. Hand off to a background job for all database writes and business logic. // Set the payment status to 'queued' now. The job will update it to // 'processed', 'failed', or 'reconciled' when it runs. // e.g. ProcessStkCallback::dispatch($request->all()); // e.g. $payment->update(['status' => 'queued']); if ($result->isSuccessful()) { // Safaricom confirmed the customer completed the payment. // Let the background job handle fulfillment. Log::info('mpesa.stk.completed', [ 'checkout_request_id' => $checkoutRequestId, 'merchant_request_id' => $data->Body->stkCallback->MerchantRequestID ?? null, ]); } else { // The payment did not go through. The customer may have cancelled, // entered the wrong PIN, or had insufficient funds. // Safaricom still delivered the notification successfully, so return // success() below. Mark the payment as 'failed' inside your job. Log::warning('mpesa.stk.business_failure', [ 'checkout_request_id' => $checkoutRequestId, 'result_code' => $result->getResultCode(), 'result_description' => $result->getResultDescription(), ]); } } catch (\Throwable $e) { Log::error('mpesa.stk_callback.error', [ 'error' => $e->getMessage(), 'payload' => $request->all(), ]); // Use failed() only when your server could not handle the request at all, // for example a broken payload or a failed security check. // For other errors like the database being temporarily down, return success() // and use your saved raw log to replay the callback once the issue is resolved. return $this->responder->failed('Internal server error'); } // Respond to Safaricom. All further processing runs in the background. return $this->responder->success(); } // Add handleB2cResult, handleReversalResult, etc. following the same pattern. } ``` ### Available `TransactionResult` Methods [](#available-transactionresult-methods) ``` $result->isSuccessful(): bool // true when ResultCode === 0 $result->getResultCode(): int // raw M-Pesa ResultCode $result->getResultDescription(): string $result->getData(): object // full payload as stdClass ``` ### Callback Response Format [](#callback-response-format) `CallbackResponder` returns JSON consumed by M-Pesa. The HTTP status code alone is not sufficient — M-Pesa reads `ResultCode` in the body. Method`ResultCode`HTTP Status`$responder->success($message)``0`200`$responder->failed($message, $statusCode)``1``$statusCode```` { "ResultCode": 0, "ResultDesc": "Accepted" } ``` For Contributors ---------------- [](#for-contributors) This package includes comprehensive testing capabilities: ### Running Tests [](#running-tests) Run all tests ``` composer test ``` ### Coverage Reports [](#coverage-reports) Generate HTML coverage report: ``` composer test:coverage ``` Then open `coverage/index.html` in your browser. Code Quality ------------ [](#code-quality) ``` # Check code style composer check-style # Fix code style issues composer fix-style # Run static analysis composer analyse ``` Credits ------- [](#credits) - [Lazarus Odhiambo](https://github.com/botnetdobbs) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 49 — FairBetter than 94% of packages Maintenance92 Actively maintained with recent releases Popularity22 Limited adoption so far Community9 Small or concentrated contributor base Maturity61 Established project with proven stability 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 ~92 days Total 7 Last Release 20d ago PHP version history (2 changes)1.0.0PHP ^8.2 1.0.2PHP ^8.2|^8.3|^8.4 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/35170812?v=4)[Lazarus Odhiambo](/maintainers/botnetdobbs)[@botnetdobbs](https://github.com/botnetdobbs) --- Top Contributors [![botnetdobbs](https://avatars.githubusercontent.com/u/35170812?v=4)](https://github.com/botnetdobbs "botnetdobbs (30 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/botnetdobbs-laravel-mpesa-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/botnetdobbs-laravel-mpesa-sdk/health.svg)](https://phpackages.com/packages/botnetdobbs-laravel-mpesa-sdk) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[defstudio/telegraph A laravel facade to interact with Telegram Bots 816334.2k3](/packages/defstudio-telegraph)[api-platform/laravel API Platform support for Laravel 58171.9k14](/packages/api-platform-laravel)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5022.0k](/packages/simplestats-io-laravel-client) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)