laravel-mpesa-checkout

Drop-in M-Pesa STK Push checkout UI for Laravel — a Blade component + controller that handles the complete payment flow with JS polling.

Requirements

• PHP 8.1+
• Laravel 10 / 11 / 12 / 13
• felixmuhoro/laravel-mpesa ^1.2

Installation

composer require felixmuhoro/laravel-mpesa-checkout

The service provider registers automatically via Laravel's package discovery.

Publish the config:

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

Publish assets (JS):

php artisan vendor:publish --tag=mpesa-checkout-assets

Configuration

config/mpesa-checkout.php (with .env overrides):

Usage

Blade Component (modal flow)

Add to your layout — the button opens a modal, handles everything in-page:

{{-- In your layout head / bottom of body --}}
@stack('styles')
@stack('scripts')

{{-- Anywhere on the page --}}
<x-mpesa-button
    :amount="1500"
    reference="INV-2024-001"
    description="Order payment"
    :phone="auth()->user()->phone ?? ''"
    on-success="handleMpesaSuccess"
    on-fail="handleMpesaFail"
    label="Pay KES 1,500"
    size="lg"
/>

JavaScript callbacks (optional):

function handleMpesaSuccess(detail) {
    console.log('Paid! Receipt:', detail.receipt);
    window.location.reload();
}

function handleMpesaFail(detail) {
    console.log('Failed:', detail.reason || detail.status);
}

You can also listen to DOM events:

document.addEventListener('mpesa:success', e => {
    console.log('receipt:', e.detail.receipt);
});
document.addEventListener('mpesa:fail', e => {
    console.log('reason:', e.detail.reason);
});

Standalone Page Flow

Redirect the user to the checkout page:

return redirect()->route('mpesa-checkout.page', [
    'amount'      => 1500,
    'reference'   => 'INV-2024-001',
    'description' => 'Order payment',
    'phone'       => $user->phone,
]);

Set MPESA_CHECKOUT_SUCCESS_URL and MPESA_CHECKOUT_CANCEL_URL to control where the user lands after payment.

Programmatic API

use FelixMuhoro\MpesaCheckout\CheckoutManager;

class OrderController extends Controller
{
    public function pay(Request $request, CheckoutManager $checkout)
    {
        $session = $checkout->initiate(
            amount:      1500,
            phone:       '0712345678',
            reference:   'INV-001',
            description: 'Order #1234',
        );

        return response()->json([
            'session_id' => $session->sessionId,
            'status'     => $session->status->value,
        ]);
    }
}

Routes

Webhook / Callback URL

Point your Safaricom Daraja app's Confirmation URL to:

https://yourdomain.com/mpesa-checkout/webhook

This URL is automatically excluded from CSRF verification.

Checkout Flow

User clicks button
    -> JS POSTs /mpesa-checkout/initiate
    -> Safaricom sends STK Push to phone
    -> Modal shows "Check your phone" + countdown
    -> JS polls /mpesa-checkout/poll every 3 s
    -> On result: success or fail state shown
    -> Optional JS callback / DOM event fired

The poll endpoint also calls stkQuery against Safaricom on each poll, so it works even when the M-Pesa webhook callback is delayed or unreliable.

Customising Views

php artisan vendor:publish --tag=mpesa-checkout-views

Views are published to resources/views/vendor/mpesa-checkout/.

Testing

composer test

License

MIT - Felix Muhoro