Payments
Safaricom M-Pesa Daraja STK Push Integration
Connect your Safaricom Daraja API credentials to trigger instant M-Pesa PIN prompts on customer phones during online storefront checkout and digital paylink settlement.
How M-Pesa STK Push Works
When a customer checks out or opens a digital paylink, entering their Kenyan mobile phone number (e.g. `0712345678` or `254712345678`) triggers an immediate SIM Toolkit (STK) push notification on their phone. The customer reviews the business name and amount, enters their M-Pesa PIN, and the transaction confirms in seconds.
Configuring Daraja Credentials in BusinessPlus
To connect M-Pesa, navigate to Dashboard -> Settings -> Integrations -> M-Pesa (`/dashboard/settings/organization/integrations`):
- 1. Shortcode & Shortcode Type: Enter your 6 or 7-digit Paybill Number or 5 to 7-digit Buy Goods Till Number, and select the corresponding Shortcode Type.
- 2. Consumer Key & Consumer Secret: Paste the Consumer Key and Consumer Secret generated in your Safaricom Developer Portal App.
- 3. Passkey (Lipa Na M-Pesa Online): Enter the Lipa Na M-Pesa Passkey issued for your shortcode.
- 4. Test Connection: Click "Test Daraja Connection" to run a live credential validation test against Safaricom APIs.
Callback & Webhook Processing
Safaricom dispatches asynchronous payment results to the BusinessPlus automated callback handler. The system verifies the transaction ID, checks for duplicate callback submissions, credits the customer's order, and updates the payment ledger.
Handling Common M-Pesa Failure Scenarios
If an STK push fails (e.g. user entered wrong PIN, cancelled prompt, or insufficient M-Pesa balance), the system captures the Safaricom error code (`ResultCode`), updates the transaction to `failed`, and allows the customer to retry or switch payment methods.