Installation · Configuration · Daraja Credentials Guide · Payment Flow · Order Statuses · Sandbox Testing · Going Live Checklist · Troubleshooting · FAQ · Changelog
Installation
From a ZIP file:
- Log in to your WordPress admin dashboard.
- Go to Plugins → Add New → Upload Plugin.
- Choose
boochy-mpesa-gateway-v1.0.2.zipand click Install Now. - Click Activate Plugin when installation completes.
Manual (FTP / cPanel): extract the ZIP, upload the boochy-mpesa folder to wp-content/plugins/, then activate it from the Plugins screen.
Configuration
After activation, go to WooCommerce → Settings → Payments, find Boochy M-Pesa and click Manage, fill in the fields below, then click Save changes.
| Field | Description |
|---|---|
| Enable/Disable | Master toggle. Must be enabled for the gateway to appear at checkout. |
| Payment Title | Label shown to customers at checkout (default: “M-Pesa”). |
| Description | Short note shown below the title. |
| Payment Mode | PayBill, Buy Goods, or Phone Number. Each shows its own fields. |
| Environment | Sandbox for testing; Live for real payments. |
| Callback URL | Read-only display. Register this URL in your Daraja app. |
| Debug Log | Writes detailed API events to WooCommerce → Status → Logs. Disable in production. |
| Restrict Callback to Safaricom IPs | Only accepts requests from Safaricom’s published IP range. Recommended for production; disable during local/ngrok testing. |
PayBill mode fields
Business Shortcode (your PayBill number), Account Reference (enter ORDER_ID to use the WooCommerce order number automatically, max 12 characters), Consumer Key, Consumer Secret, Lipa Na M-Pesa Passkey (all three from your Daraja app, see below).
Buy Goods (Till) mode fields
Till Number, Consumer Key, Consumer Secret, Lipa Na M-Pesa Passkey. Note: the Safaricom sandbox shortcode only supports PayBill; test Buy Goods mode with your own sandbox till or against live credentials.
Phone Number mode fields
M-Pesa Phone Number only – no Daraja credentials needed. Orders are placed On Hold until you mark them verified from the Order Actions dropdown on the order screen.
Daraja Credentials Guide
- Create a Safaricom Daraja account. Visit developer.safaricom.co.ke and sign up for a free account.
- Create an app. Log in, go to My Apps → Add a New App, enter a name and description, enable Lipa Na M-Pesa Online (STK Push) under APIs, then click Create App.
- Get Consumer Key and Consumer Secret. On the app detail page, expand the credentials panel and copy both into the plugin settings.
- Get the Passkey. For sandbox testing, it is published on the Daraja portal under Sandbox → Lipa Na Mpesa → Passkey. For live, request your passkey from Safaricom support after going live.
- Register the Callback URL. In your Daraja app settings, find the LNM/STK Push Callback URL field and paste the URL shown in the plugin’s Callback URL field. It must be publicly reachable over HTTPS – Safaricom will not accept
http://or localhost URLs.
Payment Flow
STK Push (PayBill / Buy Goods): customer clicks Place Order → plugin calls the Daraja STK Push API → Safaricom sends a PIN prompt to the customer’s phone → customer enters their PIN → Safaricom posts the result to the callback URL → the plugin moves the order to Processing and saves the receipt on success, or Failed on failure → the Thank You page polls every 4 seconds for up to 5 minutes and redirects automatically once the order moves to Processing.
Phone Number (manual): customer sends payment manually to the displayed number → enters the transaction code at checkout → order is placed On Hold → an admin verifies it in WooCommerce admin and the order moves to Processing.
Order Statuses
| Status | Meaning |
|---|---|
| Pending Payment | STK Push sent; waiting for the customer’s PIN and Safaricom’s callback. |
| On Hold | Phone Number mode: payment not yet verified by an admin. |
| Processing | Payment confirmed; the receipt number is saved to the order. |
| Completed | Order fulfilled by the store. |
| Failed | The customer cancelled the prompt, entered the wrong PIN, or the callback reported a non-zero result code. |
Sandbox Testing
Use Safaricom’s published sandbox PayBill shortcode 174379, your own sandbox Consumer Key and Secret from your Daraja app, and the Safaricom sandbox test phone number 254708374149. Safaricom cannot reach localhost, so expose your site with a tunnel such as ngrok during local testing, or test on a staging server with a real domain. Debug Log can be switched on and checked under WooCommerce → Status → Logs → source boochy-mpesa.
Going Live Checklist
- Your WordPress site is on a live domain with a valid SSL certificate (HTTPS).
- A production Safaricom Daraja account is approved and active.
- Live Consumer Key, Consumer Secret and Lipa Na M-Pesa Passkey are entered in the plugin settings.
- Your live Business Shortcode (PayBill or Till) is entered and verified with Safaricom.
- The Callback URL is registered in your live Daraja app.
- Environment is switched to Live in the plugin settings.
- Restrict Callback to Safaricom IPs is enabled.
- Debug Log is disabled (logs can expose transaction data).
- A real test transaction has been placed and confirmed end to end.
- WooCommerce email notifications are configured for Processing/Completed orders.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| “M-Pesa credentials are not configured” at checkout | Consumer Key, Consumer Secret or Shortcode is empty. | Re-enter credentials in settings. |
| “Invalid CallBackURL” in logs | Safaricom cannot reach the callback URL (localhost or non-HTTPS). | Use ngrok on localhost, or deploy to a live HTTPS domain. |
| “Invalid TransactionType” in logs | The sandbox shortcode does not support Buy Goods mode. | Switch to PayBill mode for sandbox testing. |
| STK Push sent but order stays Pending | Callback URL not reachable by Safaricom, or the handler is returning a non-200 response. | Check your server firewall, confirm ngrok is running, check the debug log. |
| Gateway missing at checkout (Checkout Block) | Block integration not loaded or WooCommerce is below 9.0. | Confirm WooCommerce 9.0+, then deactivate and reactivate the plugin. |
| Gateway missing at checkout (classic) | Gateway disabled, or WooCommerce is not active. | Check the Enable/Disable toggle in settings. |
| “Callback rejected – IP not in Safaricom allowlist” | IP restriction is enabled but test traffic isn’t from Safaricom. | Disable Restrict Callback IPs during sandbox/ngrok testing. |
| Order confirmation email never arrives | Email notifications aren’t configured. | Check WooCommerce → Settings → Emails. |
| PHP fatal error on activation | PHP version below 8.0. | Upgrade your server’s PHP to 8.0 or later. |
Logs: WooCommerce → Status → Logs, source boochy-mpesa.
FAQ
Do I need a Safaricom Daraja account? Only for PayBill and Buy Goods modes. Phone Number mode needs no API credentials.
Can I accept both PayBill and Buy Goods? No, only one payment mode is active at a time. For both, run two stores or contact Boochy Tech for a custom solution.
Where does the M-Pesa receipt number appear? In the order notes and order meta, visible on the specific order in WooCommerce → Orders.
Is the customer’s PIN ever seen by the plugin? No. It is entered directly on the customer’s phone through Safaricom’s own STK Push dialog and never reaches your server.
Are Daraja credentials stored securely? Yes, as WooCommerce gateway settings, which require WordPress admin access. The Consumer Secret and Passkey are never written to log files.
Does it work with the Checkout Block? Yes, full Checkout Block integration alongside classic shortcode support.
What happens if Safaricom’s callback is delayed? The Thank You page keeps polling for up to 5 minutes and redirects automatically once it arrives. If it arrives after the customer has left the page, the order still updates.
Is HPOS supported? Yes.
Can I modify the code? Yes – Boochy M-Pesa is released under GPL v2 or later, so the code itself can always be modified. The one-website licence describes the support and downloads we sell for it, not a technical restriction on the code.
Changelog
1.0.2 – Class constants for all order meta keys and Daraja API URLs. PHP 8.0 version check with an admin notice. Try/catch wrapper and a 1 MB input limit in the callback handler. Daraja token invalidation on 401 responses. Added this documentation.
1.0.1 – WooCommerce Checkout Block integration. Improved payment mode field visibility in admin settings. Fixed the enabled default for fresh activations.
1.0.0 – Initial release.