M-Pesa Gateway for WooCommerce — User Guide

A WooCommerce payment plugin that accepts M-Pesa through Safaricom's Daraja API, with STK Push, a manual Paybill/Till fallback, payment analytics, and a transactions log.

Developed by Waweru — theewaweru.dev

Before you start

You need:

1. A working WooCommerce store on WordPress, served over HTTPS (Safaricom will not send payment confirmations to a non-secure site).
2. A Safaricom Daraja account at developer.safaricom.co.ke with a production app tied to your Paybill or Till, giving you a Consumer Key, Consumer Secret, and Passkey.
3. For testing first (recommended), the sandbox test credentials from the Daraja "Test Credentials" page — sandbox shortcode is 174379.

Installing the plugin

1. In WordPress admin, go to Plugins → Add New → Upload Plugin.
2. Choose the plugin .zip file and click Install Now.
3. If a previous version is already installed, WordPress will offer "Replace current with uploaded" — choose that. Your settings are kept.
4. Click Activate.

That's it — no separate setup wizard is required.

Configuring payments

Go to WooCommerce → Settings → Payments → M-Pesa (Daraja), or use the shortcut at M-Pesa → Configure M-Pesa in the sidebar.

Set the following:

• Enable M-Pesa — tick to switch the gateway on.
• Title / Description — what customers see at checkout.
• Environment — start with Sandbox for testing; switch to Live (production) when ready. In Sandbox, an orange "SANDBOX MODE" badge appears in admin and "(Test mode)" is added to the checkout title so no one mistakes a test for a real payment.
• Consumer Key / Consumer Secret / Passkey — from your Daraja app. Once saved, these fields show only the last 4 characters for safety.
• Identifier Type — Paybill or Till (Buy Goods).
• Business Shortcode — your Paybill (or Store number for Till). Sandbox uses 174379.
• Till Number — only if using Till and funds go to a separate Till number.
• Account Reference Prefix — a short tag shown on M-Pesa statements (e.g. SHOP produces SHOP1234). Keep it short; the prefix plus order number is trimmed to 12 characters.
• Order Status on Payment — set paid orders to Processing (physical goods) or Completed (virtual items/bookings).
• Manual Paybill/Till fallback — lets customers pay manually if the prompt fails; the order waits on hold until confirmed.
• C2B Auto-confirmation — optional; auto-confirms manual payments. Requires activating C2B on your shortcode with Safaricom first, then clicking the register-URLs link in settings.

Click Save changes.

Recommended: keep credentials out of the database

For better security you can define credentials in wp-config.php instead of the settings screen. When present, these override the saved fields:

define( 'MPESA_DARAJA_CONSUMER_KEY', 'your-key' );
define( 'MPESA_DARAJA_CONSUMER_SECRET', 'your-secret' );
define( 'MPESA_DARAJA_PASSKEY', 'your-passkey' );

Testing it works

1. With Environment = Sandbox, go to M-Pesa → Health Check and click Run health check. All rows should show a green tick (the Environment row will note you are in Sandbox).
2. Place a test order and choose M-Pesa at checkout. Enter a test phone number.
3. For a real end-to-end test, switch to Live, use a low-value product (e.g. KShs 10), and pay with your own phone. Confirm the order completes and appears under M-Pesa → Transactions with a receipt number.

If anything fails, turn on Debug Mode in settings and check WooCommerce → Status → Logs (source mpesa-daraja) for Safaricom's exact message.

Using the dashboards

Under the M-Pesa menu in the sidebar:

• Dashboard — totals, success rate, charts (revenue by day, outcomes, failure reasons, payments by hour), with date-range presets and Export CSV / Export PDF (PDF via your browser's print-to-PDF).
• Transactions — every M-Pesa event (push sent, paid, cancelled, timed out, etc.) with filters for status, mode, date, and a search box. Stalled or unconfirmed payments can be re-checked against Safaricom, and a verified payment can be applied to an order with a single click. Payments are never completed automatically by background checks — applying a payment is always a human decision.
• Health Check — the live diagnostic described above.

You'll also receive a short daily review email only when something needs attention (a verified-but-unapplied or stalled payment), and an alert email if payment callbacks start being rejected.

Background tasks (important)

The plugin runs scheduled jobs to reconcile missed payments, send the daily review, and prune old event records. These rely on WP-Cron. If your host has disabled WP-Cron (the Health Check will tell you), set up a real system cron — for example, in cPanel, a job every 5 minutes calling:

wget -q -O /dev/null "https://yourdomain.co.ke/wp-cron.php?doing_wp_cron"

Replace yourdomain.co.ke with your site's domain.

Trademark / logo notice

"M-PESA", "Lipa na M-Pesa", "Daraja", and "Safaricom" are trademarks of Safaricom PLC. The M-Pesa logo included with this plugin is the property of Safaricom PLC and is used only to identify the M-Pesa payment option to customers. This plugin is not affiliated with, endorsed by, or sponsored by Safaricom PLC. If you use this plugin you are responsible for ensuring your use of Safaricom's marks complies with Safaricom's terms and any agreement you hold with them. The plugin author claims no ownership of the M-Pesa name or logo.

License and updates

• This plugin is provided free of charge. There is no paid license, subscription, or activation key.
• It is provided as-is, without warranty of any kind. Use it at your own risk; test thoroughly before processing live payments.
• Updates are delivered from GitHub. From v0.7.0 the plugin checks github.com/theewaweru/mpesa-daraja-gateway for new releases and shows them under Dashboard → Updates like any other plugin. Update at your own discretion; neither the author nor Safaricom provides update support directly to end users.
• You may use and modify it for your own sites. Please keep the author credit (Waweru — theewaweru.dev) intact.

M-Pesa Gateway for WooCommerce · developed by Waweru · theewaweru.dev

Changelog

0.7.2

• New: Period comparison. Dashboard cards now show change badges against the previous equal-length period, and the revenue chart overlays the previous period as a dashed line.
• New: STK conversion funnel. The dashboard shows Prompts sent, Prompt answered, and Paid as a funnel with percentages, plus timeout counts and recovery-email results, so you can see exactly where checkout loses money.

0.7.1

• New: Payment recovery emails (opt-in). When an STK payment fails or stalls, the customer gets one email (never more) after a configurable delay, with a one-click link to WooCommerce's payment page that fires a fresh M-Pesa prompt. Enable it under the gateway settings. Recovered payments are tagged in Transactions and Reports.
• New: Reconciliation report. M-Pesa → Reports shows every collected payment matched to its M-Pesa receipt, with daily subtotals, a grand total, and a "needs attention" list (on-hold, mismatches, refunds). One-click CSV built for accountants.

0.7.0

• New: GitHub-powered updates. The plugin now checks the GitHub repository for new releases (cached, twice a day) and offers them through the standard WordPress update flow, including the "View details" changelog popup. No store, no license keys.
• Update packages keep the installed folder name, so upgrades replace the plugin cleanly instead of creating duplicates.

0.6.2

• Fix: removed an orphaned hook that called a non-existent method (audit_settings_change) on every settings save, which caused a "critical error" page and prevented saving the gateway configuration. Settings-change auditing continues to work via the operations module.

0.6.1

• Stability hardening for the settings-save path; operations module loads admin-side only.

0.6.0

• Health Check page (live OAuth test, callback-URL reachability, cron status), webhook-failure email alerts, daily digest email, and settings-change auditing.

0.5.0

• Events log with retention/pruning, top-level M-Pesa admin menu (Dashboard / Transactions / Configure), transactions list with filters and per-row re-check / apply-paid, replay protection, sandbox indicators.

0.4.0

• Cancellation feedback messages, webhook secret-token protection, verify-before-trust, amount-mismatch hold, resend cap, phone masking, and wp-config credential constants.

0.3.0

• Paybill/Till selector, resend STK button, debug logging, KES-only guard, HPOS declaration, C2B auto-confirmation, background reconciliation cron.

0.2.0

• Initial STK Push, manual Paybill fallback, thank-you page poller, analytics dashboard.