How to Add M-Pesa Payments to a WooCommerce Store (STK Push Explained)

Short answer: to add M-Pesa to a WooCommerce store, you need a Safaricom Paybill or Till number, an app on Safaricom’s Daraja developer portal with M-Pesa Express (STK Push) enabled, an HTTPS website, and a WooCommerce payment gateway that sends the payment request and listens for Safaricom’s confirmation. When it works properly, the customer types their phone number at checkout, gets a prompt on their phone, enters their M-Pesa PIN, and the order marks itself as paid.

This guide explains how STK Push works, what you need, the steps from sandbox to live payments, and the mistakes that leave shops with “paid” customers and “pending” orders. If you’d rather have it done for you, see our WooCommerce shops with M-Pesa service.

What is M-Pesa STK Push?

STK Push is the payment prompt that pops up on a customer’s phone asking them to confirm a payment with their M-Pesa PIN. Safaricom calls the API M-Pesa Express, and you’ll also see it called Lipa na M-Pesa Online. It runs on Daraja, Safaricom’s developer platform for M-Pesa APIs (currently Daraja 3.0).

For an online shop, STK Push is the smoothest option because the customer never has to type your Paybill number, account number or amount. Your shop fills those in and sends the request. It works with both:

• Paybill numbers (transaction type CustomerPayBillOnline), and
• Till / Buy Goods numbers (transaction type CustomerBuyGoodsOnline).

How STK Push works at checkout, step by step

1. The customer chooses M-Pesa at checkout and enters their Safaricom number.
2. Your shop’s server sends a request to Daraja. It includes your shortcode (Paybill or Till), the amount, the customer’s number in 2547XXXXXXXX format, an order reference, and a callback URL on your website. The request is authenticated with an access token and a password made from your shortcode, a passkey and a timestamp.
3. Daraja replies immediately to say it has accepted the request. This is not a payment confirmation, only an acknowledgement.
4. The customer gets the prompt on their phone and enters their PIN, or cancels, or ignores it.
5. Safaricom sends the result to your callback URL. A result code of 0 means the payment succeeded, and the message includes the M-Pesa receipt number, amount and phone number. Other codes mean it failed; for example, 1032 means the customer cancelled.
6. Your shop updates the order. On success, the order is marked paid, the receipt number is saved against it, and the customer sees a thank-you page. On failure, the customer can try again.

The key point is step 5. An order should only be marked paid when Safaricom’s callback confirms it, never on the first acknowledgement in step 3. Daraja also has a query endpoint, so your shop can check the status of a payment if a callback is delayed.

What you need before you start

• A Safaricom Paybill or Till number for your business. You need one of these for live payments. (Testing uses Safaricom’s shared sandbox shortcode, 174379.)
• A Daraja developer account at developer.safaricom.co.ke, with an app that has M-Pesa Express enabled. The app gives you a consumer key and consumer secret. For live payments you also get a passkey for your shortcode.
• Access to your M-Pesa business portal, because the go-live process links your Daraja app to your live shortcode and needs an authorised business user.
• A WooCommerce store on HTTPS. Callback URLs must be public and secure; a site on localhost or plain http won’t receive Safaricom’s confirmations. (Our hosting includes SSL.)
• A payment gateway for WooCommerce that handles the request, the callback and the order update. That can be a direct Daraja integration, or a payment provider such as PesaPal or iPay that includes M-Pesa among its methods.

Three ways to take M-Pesa on WooCommerce

We set up all three, and we usually recommend based on where your customers are and how you want to reconcile payments. For non-WooCommerce sites and systems, see M-Pesa integration.

Step by step: adding M-Pesa STK Push to WooCommerce

Step 1: Confirm your Paybill or Till and who can access it

Check which shortcode payments should go to, and that someone with admin or manager rights on the M-Pesa business portal will be available for the go-live step.

Step 2: Create your Daraja app

Sign up on the Safaricom developer portal, create an app and enable M-Pesa Express. Note the sandbox consumer key, consumer secret and the sandbox passkey.

Step 3: Install and configure the gateway in WooCommerce

Install your chosen M-Pesa gateway, add it under WooCommerce payment settings and enter the sandbox credentials. Set the order reference format (for example, your WooCommerce order number) so every payment can be matched to an order.

Step 4: Set and test the callback URL

Make sure the callback URL is public, on HTTPS and not blocked by a security plugin, firewall or caching rule. This is the single most common reason payments succeed but orders stay “pending”.

Step 5: Test in the sandbox

Run test orders for success, cancellation and no response. Check that each one ends in the right order status, that the receipt number is saved, and that stock and emails behave correctly.

Step 6: Go live

From your Daraja app, apply to go live and link your live Paybill or Till. Once approved, replace the sandbox credentials with the live consumer key, secret and passkey, and switch the gateway to production.

Step 7: Make small live payments and reconcile

Make a few small real payments, then compare WooCommerce orders with your M-Pesa statement. Only announce the new checkout once every test payment matches.

Common mistakes that cost shops money

• Marking orders paid on the first response. The acknowledgement only means Safaricom received your request. Wait for the callback.
• Callbacks blocked by the site itself. Caching, firewalls and “hide WordPress” security plugins can block Safaricom’s confirmation. Exclude the callback URL from caching and security rules.
• Phone number format. Numbers entered as 07XX… need converting to 2547XX… before they are sent.
• Decimals in the amount. M-Pesa amounts are whole shillings, so round correctly and make sure the total the customer approves matches the order.
• No plan for cancellations. If a customer cancels or ignores the prompt, show a clear “try again” option instead of a dead end.
• Sandbox credentials left in production. After go-live, check every key, the passkey and the environment setting.
• No one watching updates. WordPress, WooCommerce and gateway plugins need updating and re-testing. A care plan covers this.

Want us to set it up for you?

We build WooCommerce shops with M-Pesa checkout (direct, iPay or PesaPal), plus PayPal and cards, and test everything from sandbox through to live payments before launch. We also fix existing shops where payments go through but orders don’t update. See our e-commerce website design page for full shop builds.

Talk to us about M-Pesa for your shop

During working hours (Monday to Friday, 8am to 6pm EAT) we reply within minutes on phone or WhatsApp at +254 705 828 000. Schedule a discovery call to discuss your project.

Written by Vincent Ochieng, founder of Butterfly Prime Solutions (since 2012). Last updated: 16 October 2026.