M-Pesa (Safaricom Daraja)

The M-Pesa driver supports Kenya Daraja workflows including STK Push collections, B2C/B2B transfers, account balance, transaction status, and Ratiba standing orders. Its payment flow is asynchronous: initiate the request, then wait for a callback or query the transaction.

Setup

MPESA_CONSUMER_KEY=your_consumer_key
MPESA_CONSUMER_SECRET=your_consumer_secret
MPESA_SHORTCODE=your_business_shortcode
MPESA_PASSKEY=your_stk_passkey
MPESA_INITIATOR_NAME=your_initiator_name
MPESA_SECURITY_CREDENTIAL=your_security_credential
MPESA_BASE_URL=https://api.safaricom.co.ke
MPESA_CALLBACK_URL=https://example.com/webhooks/payment-gateways/mpesa
MPESA_RESULT_URL=https://example.com/webhooks/payment-gateways/mpesa
MPESA_TIMEOUT_URL=https://example.com/webhooks/payment-gateways/mpesa

For sandbox testing, use the Safaricom sandbox API URL and sandbox-issued credentials. The driver obtains an OAuth token. Configure callback/result/timeout URLs reachable by Safaricom.

STK Push collection

use Alphabalex\PaymentMadeEasy\Facades\Payment;

$driver = Payment::driver('mpesa');
$pending = $driver->initializePayment([
    'phone'            => '254712345678', // international digits; leading + is optional
    'amount'           => 500,
    'reference'        => 'ORDER_123',
    'account_reference'=> 'ORDER_123',
    'description'      => 'Order 123',
]);

// Save the returned checkout_request_id; the provider callback is asynchronous.
// Query/verify the resulting transaction before fulfilling the order.

Amounts are KES major units and the driver sends whole KES values to Daraja. It normalizes an optional leading + on the phone number.

Transfers and standing orders

The driver implements shared balance, disbursement, and subscription contracts. Provider-specific methods include b2bTransfer(), C2B URL registration, dynamic QR generation, and transaction-status queries. Safaricom must enable the relevant Daraja products and shortcode permissions.

Callback security

M-Pesa callbacks do not use a shared HMAC signing secret through this integration. Require HTTPS, restrict callback access where feasible (for example, provider IP controls at your edge), and verify transaction status with Daraja before crediting an order. The package endpoint is POST /webhooks/payment-gateways/mpesa; see webhook guidance.

See M-Pesa in the API reference for the transfer, QR, Ratiba, and balance methods.