DOCUMENTATION: Enhanced Lipa Na M-PESA for WooCommerce

Plugin Version: 2.5.1

1. Overview

This plugin integrates Safaricom’s M-PESA mobile money service directly into your WooCommerce store using the STK Push (Sim Toolkit Push) method. It is engineered for speed and reliability, utilizing a unique Dual Confirmation System to prevent lost or delayed orders.

Key Features:

• STK Push: Sends a payment prompt directly to the customer's phone screen.

• Real-time Speed: Payment verification typically occurs in 2–5 seconds.

• Race Condition Proof: Prevents duplicate payments or double order updates.

• Enterprise Security: Uses OAuth 2.0 authentication via Safaricom Daraja API.

• HPOS Compatible: Fully compatible with WooCommerce High-Performance Order Storage.

2. The Core Advantage: Dual Confirmation System

Standard M-PESA plugins often rely solely on "Polling" (asking Safaricom if payment is done), which can be slow. This plugin uses a Hybrid Approach to ensure the fastest possible checkout experience.

How It Works: The plugin runs two verification methods simultaneously. Whichever confirms the payment first "wins" and completes the order.

Method A: Callback (Primary)

• Action: Safaricom automatically sends the result to your server.

• Speed: Very fast (~2–5 seconds).

Method B: Polling (Backup)

• Action: The plugin actively queries Safaricom's API every 3 seconds.

• Speed: Slower (~5–30 seconds).

• Role: Acts as a fail-safe if the Callback fails or is delayed.

Note on Safety: The system includes "Race Condition Protection." If both methods attempt to verify the payment at the exact same time, the system logic ensures the order is only processed once.

3. Customer Payment Flow

Here is what your customer experiences:

1. Checkout: Customer enters their M-PESA number (format: 254XXXXXXXXX) and clicks "Place Order."

2. Pending: The order is created with "Pending" status. The plugin contacts Safaricom.

3. The Prompt: The customer sees a notification on their phone asking for their PIN.

4. Processing: Customer enters their PIN.

5. Verification: Our Dual Confirmation System detects the payment via Callback or Poll.

6. Completion: The order moves to "Processing," stock is reduced, and the success page loads.

4. Setup Guide: Getting Safaricom Credentials

To use the plugin, you must get API keys from the Safaricom Daraja Portal.

Phase 1: For Testing (Sandbox)

Use this mode to test without spending real money.

1. Register: Go to the Safaricom Developer Portal and create an account.

2. Create App: Click "My Apps" -> "Create New App". Name it "MyShop Test" and check the box for Lipa Na M-PESA Sandbox.

3. Get Key & Secret: Open your new app to see your Consumer Key and Consumer Secret.

4. Get Passkey: Go to "APIs" -> "M-PESA Express (STK Push)" -> "Simulate". Select your app. The Passkey will be shown (usually starts with bfb279...).

Phase 2: Going Live (Production)

Use this mode to accept real money.

1. Go Live: Log in to the Developer Portal and click "Go Live" in the menu. Submit your Business Shortcode (Paybill/Till) and documents.

2. Approval: Wait for Safaricom to approve your request via email.

3. Create Production App: Once approved, go to "My Apps" and create a new app. Ensure you uncheck "Sandbox" or select the Production profile.

4. Get Production Credentials: Copy the Consumer Key and Consumer Secret from this new Production App.

5. Get Passkey: This is usually emailed to you by Safaricom after approval.

5. Plugin Configuration

Enter these settings in your WooCommerce Payment Settings.

Essential Settings:

• Environment: Select Sandbox for testing or Production for live sales.

• Business Shortcode: Your M-PESA Paybill or Till number (e.g., 174379 for testing).

• Consumer Key: The key you copied from Daraja.

• Consumer Secret: The secret you copied from Daraja.

• Passkey: The Lipa Na M-PESA passkey.

Timing Settings (Recommended):

• Polling Interval: 3 seconds.

• Payment Timeout: 120 seconds.

• Max Status Checks: 50.