The M-Pesa Checkout plugin by Finacc provides a secure and streamlined way to accept M-Pesa payments directly within your WooCommerce store checkout. Key features include:

• Direct STK Push initiation to the customer's phone.
• Real-time status updates via M-Pesa callbacks.
• Integration with WooCommerce order statuses.
• A dedicated M-Pesa Transaction Dashboard for monitoring and reporting.
• Easy configuration and license management.

This documentation will guide you through setting up and using the plugin effectively.

Ensure your environment meets the following minimum requirements for the M-Pesa Checkout plugin to function correctly:

• WordPress: Version 5.8 or higher
• WooCommerce: Version 7.1 or higher. Ensure WooCommerce is installed and activated.
• PHP: Version 7.4 or higher. PHP 8.0+ is strongly recommended for better performance and security.
• SSL Certificate (HTTPS): Absolutely required for connecting to the Live M-Pesa API. Your site's Callback URL MUST be HTTPS.
• Outgoing Connections: Your server must be able to make outgoing HTTPS connections to Safaricom API endpoints (https://sandbox.safaricom.co.ke and https://api.safaricom.co.ke) and the Finacc license server (https://finachub.com). Verify no firewalls or hosting settings block these connections.
• M-Pesa PayBill or BuyGoods Till Number: An active M-Pesa business account with Lipa Na M-Pesa Online (STK Push) enabled.
• Safaricom Developer Portal Account: Access to developer.safaricom.co.ke to obtain API credentials and set up callback URLs.

Follow these steps to install the M-Pesa Checkout plugin on your WordPress site:

1. Step 1: Download the Plugin File

   Obtain the plugin ZIP file from your purchase confirmation email or the Finacc Hub website dashboard. Save it to your computer.

   

2. Step 2: Upload to WordPress

   Log in to your WordPress admin dashboard.

   Navigate to Plugins > Add New from the left-hand menu.

   Click the Upload Plugin button located at the top of the "Add Plugins" page.

   Click Choose File, select the mpesa-checkout.zip file you downloaded, and then click Install Now.

   

3. Step 3: Activate the Plugin

   WordPress will upload and unpack the plugin.

   Once installation is complete, you will see a success message.

   Click the blue Activate Plugin button to enable the plugin functionality.

   You should now see "Mpesa" added to your WordPress admin menu.

   

After activating the plugin, you need to configure the M-Pesa gateway settings and activate your license.

Gateway Settings

Connect your plugin to the M-Pesa API using credentials from the Safaricom Developer Portal.

1. Step 1: Access Gateway Settings

   Go to WooCommerce > Settings in your WordPress admin.

   Click on the Payments tab.

   Find M-Pesa in the list and click on it (or click 'Manage').

   

2. Step 2: Enter API Credentials

   Fill in the form fields with the API credentials you obtained from your Safaricom Developer Portal App. Ensure they are for a "Lipa Na M-Pesa Online" enabled Short Code.

   • Enable/Disable: Check to activate M-Pesa checkout.
   • Title: How the payment method appears on checkout (e.g., "M-Pesa Payment").
   • Consumer Key: Your Safaricom API Consumer Key.
   • Consumer Secret: Your Safaricom API Consumer Secret.
   • Short Code: Your M-Pesa PayBill or BuyGoods Till Number.
   • Passkey: Your Lipa na M-Pesa Online Passkey.

   Select the correct Environment (Sandbox or Live) that matches your credentials.

   

   Sandbox Testing Credentials

   To test the setup without using real money, use the Safaricom Sandbox. You'll need a Sandbox App on their portal to get a Consumer Key and Secret. Use the official Safaricom Sandbox Short Code, Passkey, and test phone numbers:

   Example Sandbox Short Code (PayBill): 174379
Example Sandbox Passkey: bfb279f914cd29cf9fd9b6cb583c73ab742279e93d1e6a67cf505bd00e7fc136
Test Phone Numbers: Use the numbers listed in your Safaricom Sandbox account (typically 254700000000 through 254700000009).
Test M-Pesa PIN: 1234 (for Sandbox test numbers)

   Note: Consumer Key and Secret are unique to your Sandbox App.

3. Step 3: Configure Callback URL

   The plugin needs a URL to receive payment confirmations from Safaricom. The default Callback URL is:

   [YOUR_SITE_URL_HERE]/?wc-api=finacc_callback

   Copy the URL shown in the plugin settings and paste it into the Callback URL field.

   Crucially: You MUST also register this *exact* URL in your App's settings on the Safaricom Developer Portal under the "Callbacks" or "APIs" section. Select "Lipa Na M-Pesa Online (STK Push)" as the product.

   HTTPS Required for Live

   If you are in the Live M-Pesa environment, your Callback URL MUST begin with https://. Ensure your website has a valid SSL certificate installed.

4. Step 4: Save Changes

   Scroll to the bottom of the payment gateway settings page and click the Save changes button.

License Activation

Activating your plugin license is essential for accessing updates, support, and ensuring continued functionality after the trial period.

1. Step 1: Access License Settings

   In your WordPress admin sidebar, navigate to the custom menu item: Mpesa > Settings & License.

   

2. Step 2: Enter and Verify License Key

   Find the "License Activation" section.

   Enter your unique License Key (sometimes referred to as a purchase code) that you received when you bought the plugin from Finacc Hub.

   Click the Verify & Save License button.

   The plugin will communicate securely with Finacc Hub to verify the key. Wait for the process to complete.

   

3. Step 3: Confirm License Status

   A status message will be displayed (e.g., "License is active and valid.", "In Trial", "License key is invalid"). Ensure the status shows as "Valid" for full access. If not, double-check the key or consult the troubleshooting section.

Learn about the customer checkout experience and the administrative dashboard.

Customer Checkout Experience

This is how a customer pays using M-Pesa on your store:

1. On the checkout page, the customer selects "M-Pesa" as their payment method.
2. A field appears asking for their M-Pesa registered phone number (e.g., 0712345678 or 254712345678). They enter their number.
3. Upon clicking "Place Order", the plugin initiates an STK Push request to Safaricom using the entered phone number.
4. The customer receives a standard M-Pesa STK Push prompt directly on their phone (usually requires entering their M-Pesa PIN).
5. Once the customer completes the prompt (by entering PIN or cancelling), Safaricom sends a real-time notification (callback) to your website's Callback URL.
6. The plugin's callback handler processes this notification and automatically updates the WooCommerce order status (e.g., to "Processing" for successful payments, "Failed" for cancellations/failures).
7. The customer is shown a waiting screen which automatically updates or redirects them to the Order Received page, displaying the final payment status.

Transaction Dashboard

Monitor all M-Pesa payment attempts and their statuses using the plugin's built-in dashboard.

Access the dashboard by navigating to Mpesa > Dashboard in your WordPress admin.

• Overview Stats: At the top, view key statistics like Total Transactions, Successful Payments, Pending Payments, Failed Payments, and Total Value Processed.
• Filters: Use the filter options to search for transactions by phone number, date range, or specific status (Completed, Pending, Failed, etc.).
• Transaction List: A table lists individual transactions. Click the "+" icon next to each row to expand and view detailed information, including the associated WooCommerce order details, the amount paid, the M-Pesa Transaction ID, and the raw callback response from Safaricom (useful for debugging).
• Export: Click the "Export CSV" button to download a spreadsheet of the transactions currently displayed based on your filters.

Encountering issues? Here are some common problems and their solutions:

STK Push Not Received or Timeout

• Incorrect Credentials: This is the most common cause. Carefully re-enter your Consumer Key, Secret, Short Code, and Passkey in WooCommerce > Settings > Payments > M-Pesa. Ensure there are no typos and that the Environment setting (Sandbox/Live) matches the credentials used.
• Phone Number Format: Verify the customer entered their phone number correctly (e.g., starting with 254 or 07...). The plugin attempts formatting, but invalid input can still fail.
• Safaricom App/Service Status: Check the Safaricom Developer Portal to ensure your App is active and the Lipa Na M-Pesa Online service is functioning correctly for your Short Code.
• Customer's Phone Issues: The customer's phone might have poor network signal, low battery, insufficient balance (sometimes affects prompt delivery), or issues with their SIM card/SIM Toolkit.
• Server Outgoing Connections Blocked: Your server must be able to initiate connections to Safaricom's API URLs (https://sandbox.safaricom.co.ke or https://api.safaricom.co.ke). Check your hosting provider, firewall settings, or security plugins for blocked outgoing connections on port 443 (HTTPS).
• Plugin/Theme Conflicts: Temporarily deactivate other plugins and switch to a default theme (like Storefront) to see if the issue is caused by a conflict.

Callback Not Received / Order Status Not Updating

• Incorrect Callback URL: The URL you registered on the Safaricom Developer Portal *must* exactly match the one in your plugin settings. Any difference will prevent Safaricom's success/failure notifications from reaching your site.
• Callback URL Accessibility: Your Callback URL must be publicly accessible from the internet. Firewalls, security plugins (e.g., blocking IPs, rate limiting), or even hosting configurations can block these incoming requests from Safaricom's servers. Temporarily disabling security measures (with caution) can help diagnose this.
• HTTPS for Live: If you are in the Live environment, your Callback URL *must* start with https://.
• Server Errors: Check your website's server-side PHP error logs for any fatal errors that occur when processing incoming requests to your Callback URL.
• Plugin Deactivation: If the plugin was recently deactivated and reactivated, the callback handler might not be properly registered with WordPress until plugins_loaded runs.
• Check Dashboard Raw Callback: View the transaction details in the M-Pesa Dashboard. The "Raw Callback" data might contain an error message from Safaricom indicating why the callback failed on their end or was rejected by your server.

License Activation Issues

• Typo in Key: Double-check that you have copied and pasted the license key accurately, without any extra spaces before or after it.
• Connectivity to Finacc Hub: Your server needs to be able to make an outgoing HTTPS connection to https://finachub.com on port 443 to verify the license. Ensure this is not blocked by firewalls or hosting rules.
• License Status/Limits: Log in to your Finacc Hub account to confirm that your license is currently active and has not exceeded the number of allowed website installations.

If you have gone through this documentation and the troubleshooting steps but still need help, please contact our dedicated support team. We are here to assist you.

To help us resolve your issue quickly, please provide the following information when you contact support:

• A clear, detailed description of the issue you are experiencing.
• The exact steps you took leading to the problem.
• Any error messages you saw on screen.
• Error messages found in your website's logs (WooCommerce > Status > Logs, and your server's PHP error logs).
• Relevant screenshots or screen recordings.
• Your WooCommerce System Status Report (Go to WooCommerce > Status, click "Get system report", then "Copy for support").
• Your M-Pesa Checkout License Key (this helps us verify your premium support entitlement).
• The exact version of the M-Pesa Checkout plugin you are using.