Marupurupu Checkout for M-Pesa

Description

Marupurupu Checkout for M-Pesa allows you to accept payments via M-Pesa (Safaricom) using the STK Push (Lipa Na M-Pesa Online) feature. This plugin integrates seamlessly with WooCommerce and supports both classic shortcode-based checkout and modern block-based checkout.

Independent plugin — no affiliation. This plugin is developed independently. It is not affiliated with, endorsed by, or sponsored by Safaricom, M-Pesa, WooCommerce or Automattic. M-Pesa, Safaricom and WooCommerce are trademarks of their respective owners, used here only to describe what the plugin works with.

Features

• STK Push Payments – Customers receive payment prompt directly on their phone
• Block Checkout Support – Works with WooCommerce block-based checkout (NEW in v1.1.0)
• Classic Checkout Support – Fully compatible with traditional shortcode checkout
• Automatic Detection – Automatically works with both checkout types
• Real-time Payment Status – Instant payment confirmation via callbacks
• Transaction Reports – Comprehensive admin dashboard for transaction tracking
• Secure Credentials – AES-256-GCM authenticated encryption for M-Pesa API credentials
• Test Mode – Sandbox environment for testing before going live
• Payment Callbacks – Automatic order status updates
• Order Tracking – Enhanced order received page with payment status
• Debug Logging – Detailed logs for troubleshooting
• Telemetry – Optional usage tracking (opt-in)

Requirements

• WordPress 5.3 or higher
• WooCommerce 3.0 or higher (5.5+ recommended for block checkout)
• PHP 7.4 or higher
• SSL Certificate (required for M-Pesa STK Push)
• M-Pesa Till Number and Daraja API credentials

Setup

1. Upload the plugin to /wp-content/plugins/marupurupu-checkout-for-mpesa/
2. Activate the plugin through the ‘Plugins’ menu in WordPress
3. Go to WooCommerce > Settings > Payments
4. Enable “M-Pesa Till Payment”
5. Click “Manage” to configure your M-Pesa credentials
6. Add your Business Short Code (Till Number), Consumer Key, Consumer Secret, and Passkey
7. Configure callback URL (auto-generated)
8. Save changes and test in Test Mode first

Configuration

Required Settings:
* Consumer Key (Production & Test)
* Consumer Secret (Production & Test)
* Business Short Code (Your Till Number)
* Passkey (From Daraja Portal)
* Test Mode toggle

Optional Settings:
* Payment instructions for customers
* Debug logging
* Telemetry (usage tracking)

External services

This plugin connects to the third-party services below. Nothing is sent to Safaricom until you configure the plugin and a payment is attempted, and nothing is sent to the usage-statistics collector unless you opt in.

Safaricom Daraja API (api.safaricom.co.ke, or sandbox.safaricom.co.ke when Test Mode is on) — the service that actually takes the M-Pesa payment.
* Used for: requesting an access token, sending an STK Push payment prompt to the customer’s phone, and checking the status of a payment. Safaricom also posts the payment result back to your site’s callback URL.
* Sent, and when: your Consumer Key and Consumer Secret (to obtain a token — whenever one is needed and when you click “Test M-Pesa Connection”); and, when a customer pays, your Business Short Code and Till Number, a request password derived from your Passkey, the order amount, the customer’s M-Pesa phone number, an order reference (“Order-” plus the order number) and your site’s callback URL.
* Provider: Safaricom PLC. Daraja developer portal: https://developer.safaricom.co.ke/ — Terms and Conditions and Privacy Policy: https://developer.safaricom.co.ke/terms

Plugin usage-statistics collector (telemetry.billtoolbox.com) — optional and off by default; used only if you tick “Help improve this plugin by sharing anonymous usage data” in the gateway settings. Exactly what is sent, and when, is listed field by field under “Privacy Policy” below. Operated by the plugin author. It has no separate terms document: the complete disclosure of what it receives, stores and for how long is the “Privacy Policy” section below.

WordPress.org secret-key generator (api.wordpress.org/secret-key/1.1/salt/) — only a link in an admin notice shown when your site’s security keys are missing. The plugin sends nothing to it; your browser opens it only if you click the link.

Technical Details

Compatibility

• WordPress: 5.3+
• WooCommerce: 3.0+ (5.5+ for block checkout)
• PHP: 7.4, 8.0, 8.1, 8.2
• WooCommerce Blocks: 11.0+

Security

• AES-256-GCM authenticated encryption for stored credentials (detects tampering/wrong-key decryption cryptographically, not by guessing)
• Nonce verification for all forms
• Input sanitization and output escaping
• SQL injection prevention
• XSS protection
• Callback authentication via a per-site secret token
• Callback payment amount verified against the original order before marking paid
• Rate limiting on the customer-facing payment-retry endpoint

Performance

• Minimal database queries
• Efficient caching
• Optimized asset loading
• No frontend JavaScript unless on checkout page

Privacy Policy

This plugin:
* Stores M-Pesa transaction data in your WordPress database
* Sends payment requests to Safaricom M-Pesa API
* Optionally tracks anonymous usage data (opt-in telemetry) — see below
* Does not share customer data with third parties (except Safaricom for payment processing)
* Encrypts sensitive credentials at rest

Telemetry (opt-in)

Anonymous usage telemetry is off by default. It only activates if you
check “Help improve this plugin by sharing anonymous usage data” under
WooCommerce > Settings > Payments > M-Pesa Till > Anonymous Usage Data, and
stops sending anything as soon as you uncheck it (any leftover scheduled
tasks then do nothing). If you had opted in, deactivating the plugin sends one final deactivation event (described below).

Site identifier: every event includes a site_id — a SHA-256 hash of
your site’s URL. This is a stable, unique-per-install pseudonymous
identifier, not full anonymity: because it’s stable, events from your site
can be correlated with each other over time (e.g. to see version-upgrade
history), even though your actual site URL, domain, or any other
identifying detail is never transmitted.

What’s sent, by event type (the feature_usage, error and performance events are supported by the code but the plugin does not currently trigger them; they are listed so the disclosure stays complete if that changes):

• heartbeat (weekly) — WordPress, WooCommerce, PHP, and MySQL version
  numbers; server software string; PHP memory limit and max execution
  time; whether OpenSSL and cURL are available; whether High-Performance
  Order Storage (HPOS) is enabled; site language and timezone; whether the
  site is a WordPress Multisite install; whether stored M-Pesa credentials
  are encrypted (a boolean only — never the credentials themselves).
• daily_stats (daily) — transaction counts by status (completed/pending/
  failed), success rate, minimum/maximum/average transaction amounts,
  and a distribution of M-Pesa result/failure codes. No order IDs, phone
  numbers, or customer identities are included — only aggregate numbers.
• feature_usage (weekly aggregate) — which plugin features were used and
  how many times, with no reference to which orders/customers triggered
  them.
• error — an error category and code (e.g. api_error / 1037), plus a
  short sanitized context string. The context field only ever contains the
  fixed category labels already used internally by the plugin’s error
  tracking — never raw request bodies, stack traces, or user input.
• performance (weekly aggregate) — timing metrics (count/min/max/average
  duration in milliseconds) for named internal operations, with no
  reference to which orders they came from.
• deactivation — sent once when the plugin is deactivated (and only if you
  had opted in): just the event name, the anonymous site identifier, the
  plugin version and a timestamp. No event is sent on activation.

Never included, in any event, ever: phone numbers, order details,
customer names or addresses, or M-Pesa credentials (Consumer Key/Secret,
Passkey, callback secret) in any form.

Telemetry, when enabled, is sent to a dedicated collector endpoint operated
by the plugin author (telemetry.billtoolbox.com) — a separate WordPress
install used only for this purpose, isolated from any other site.

Also recorded by the collector: like any web server, it receives the IP
address of the server that sends each event, and stores it with the event. It
is used only for rate limiting and abuse investigation and is not shown on the
collector’s dashboard. Events (including that IP address) are currently kept
until they are deleted manually — there is no automatic expiry. To have the
events for your site removed, ask in this plugin’s support forum on
WordPress.org and include your site’s identifier (site_id: the SHA-256 hash
of your site URL described above).

Credits

Developed by: Martin Mburu
Based on: Safaricom Daraja API
Uses: WooCommerce Payment Gateway API
Blocks Integration: WooCommerce Blocks API

Third-party libraries

• Chart.js 4.5.1 (MIT License) — draws the charts on the Reports page. Bundled locally as assets/js/chart.umd.js (the library’s own official minified build, unmodified). Human-readable source: https://github.com/chartjs/Chart.js (the v4.5.1 tag) or https://www.npmjs.com/package/chart.js/v/4.5.1.

Additional Information

• Source code: https://github.com/marto-karanja/marupurupu-checkout-for-mpesa
• API Reference: https://developer.safaricom.co.ke/docs
• WooCommerce Blocks: https://woocommerce.com/checkout-blocks/

This plugin is not officially affiliated with, endorsed by, or sponsored by Safaricom or M-Pesa. It integrates with Safaricom’s publicly documented Daraja API.

Support

Need help?
1. Read the FAQ above.
2. Turn on WordPress debug logging (WP_DEBUG_LOG) and check WooCommerce > Status > Logs (source “mpesa-till-callback”) and wp-content/debug.log.
3. Ask in this plugin’s support forum on WordPress.org, with your WordPress, WooCommerce and PHP versions and the relevant log lines. Never post your Consumer Key, Consumer Secret or Passkey.

Technical details