On this page
M-Pesa STK push is the payment prompt that pops up on a customer's phone asking for their M-Pesa PIN. On a website, it means the buyer types only their phone number at checkout, your site asks Safaricom to send the prompt, and Safaricom tells your site whether the payment went through. No Paybill number to copy, no confirmation SMS to forward.
You have used it if you have bought tokens or paid for a ride through an app. This article explains what happens behind that prompt in terms a business owner can follow, and the awkward cases (a cancelled prompt, a wrong PIN, a customer whose phone is off) that separate a dependable checkout from a frustrating one.
STK push in plain English
STK stands for SIM Toolkit, the small menu system built into every SIM card. That is where the old M-Pesa menu lives. "Push" means the request comes to the customer instead of the customer starting it. Safaricom's developer documentation calls the service M-Pesa Express; you will also see it called Lipa Na M-Pesa Online.
Think of it like a waiter bringing the card machine to your table instead of you walking to the till. The business starts the transaction with the amount already filled in. The customer only confirms.
Three parties are involved:
- Your website or system, which knows the order and amount.
- Safaricom's Daraja platform, the gateway that receives requests from businesses and sends results back.
- The customer's phone, which shows the prompt and collects the PIN. Your website never sees the PIN.
The payment flow step by step
Here is the flow as a sequence. Each arrow is a message between two of the three parties.
| Step | From → To | What happens |
|---|---|---|
| 1 | Customer → Website | Places an order and enters a Safaricom number, e.g. 07XX XXX XXX. |
| 2 | Website → Daraja | Requests an access token, then sends the payment request: shortcode, amount, phone, reference, callback URL. |
| 3 | Daraja → Website | Replies at once: "request accepted for processing", with a request ID. Not a payment yet. |
| 4 | Daraja → Phone | Prompt appears showing your business name and the amount. |
| 5 | Customer → Phone | Enters PIN, cancels, or ignores it. |
| 6 | Daraja → Website | Sends the final result to your callback URL: success with an M-Pesa receipt number, or a failure code. |
| 7 | Website → Customer | Marks the order paid and shows a confirmation, or explains what went wrong and offers a retry. |
The point most people miss is the gap between steps 3 and 6. Step 3 only says Safaricom received the request. The money has not moved. A checkout that says "Payment successful!" at step 3 is lying to the customer and to your staff.
While waiting for step 6, a good checkout shows a holding screen ("Check your phone and enter your M-Pesa PIN") and quietly checks every few seconds whether the callback has arrived.
What you need from Safaricom
The technical work belongs to your developer. The paperwork belongs to you. Before STK push can take real money you need:
- A Till or Paybill registered to the business. Both support STK push. Our Till vs Paybill comparison helps you choose.
- An administrator on the M-Pesa organisation portal for that shortcode, who can receive a one-time code during the go-live step.
- A Daraja account at developer.safaricom.co.ke, where your developer creates an app and tests with sandbox credentials.
- Production credentials after go-live: a consumer key, a consumer secret and a passkey specific to Lipa Na M-Pesa Online. These are sensitive and should be held by the business, then shared with the developer securely.
We cover who does what during go-live, and how to keep those credentials safe, in Daraja API explained for business owners.
Callbacks and confirming payment
The callback is a web address on your server that Safaricom calls with the outcome. It must be public, on HTTPS with a valid certificate, and respond quickly. If Safaricom cannot reach it, your site never hears the result, even though the customer paid.
A sound callback handler does four things:
- Matches the result to the right order using the request ID saved at step 3.
- Checks the details. Is the amount what the order expected? Is the result a success?
- Records the M-Pesa receipt number (the code customers know, like the ones in their SMS), so staff can look it up on the statement later.
- Ignores duplicates. If the same result arrives twice, the order should not be fulfilled twice.
When the callback never comes
Callbacks occasionally go missing: a server restart, a network blip, a firewall rule. A careful integration does not just wait forever. After a set time it uses Daraja's query service to ask Safaricom directly what happened to that request. Combined with a staff screen listing "payments awaiting confirmation", this catches almost every stuck case. If you are already facing this, our runbook on M-Pesa payments not reflecting on a website goes through the diagnosis.
Failure cases your site must handle
Most prompts succeed. The ones that do not are where customers decide whether to trust your checkout. Safaricom returns a result code for each outcome, and its documentation lists them. The common cases look like this:
| What happened | What the customer should see | What the system should do |
|---|---|---|
| Customer pressed cancel | "You cancelled the payment. Try again?" | Keep the order open, allow a fresh prompt |
| Wrong PIN entered | "The PIN was not accepted. Please try again." | Allow a retry; do not lock the order |
| Prompt timed out (phone off, no network, ignored) | "We didn't get a response from your phone." | Offer resend and a manual Paybill/Till option |
| Insufficient M-Pesa balance | "Your M-Pesa balance was too low for this payment." | Keep the order open so the customer can top up and retry |
| Number not on M-Pesa | "This number isn't registered for M-Pesa." | Prompt for another number or another method |
| Customer taps "Pay" twice | One prompt only | Block duplicate requests for the same order for a short window |
Two design habits help a lot. First, write the messages in plain language, not "Error 1032". Second, always offer a way out: a manual payment option with your shortcode and the order number as reference, or a WhatsApp link to your team. Customers upcountry on weak 3G will hit timeouts more than someone in Westlands on fibre, and they should not be stranded.
What the customer actually sees
It helps to look at the prompt from the buyer's side, because small details decide whether they trust it. The prompt names the business that will receive the money and the amount. If your website says "Mama Njeri's Kitchen" but the prompt says the name of a holding company or an old trading name, a careful customer will cancel. Fix the display name on the shortcode, or explain it on the checkout page ("You will see JN Foods Ltd on the M-Pesa prompt").
After a successful payment the customer gets the usual M-Pesa confirmation SMS with a receipt code. Your own confirmation, on screen and by email or SMS, should quote that same code. When a buyer later calls to ask about an order, that shared code is the fastest way for your staff to find it.
Testing before going live
Daraja provides a sandbox: a practice environment with test credentials and a test shortcode where no real money moves. Development should happen there first. But the sandbox is not your customers' reality, so plan a short live test once production credentials arrive.
A live test script
- Pay a small real amount from a staff phone and confirm the order turns paid, the receipt number is stored and the customer email or SMS goes out.
- Start a payment and press cancel. Check the message and that a retry works.
- Start a payment and enter a wrong PIN deliberately.
- Start a payment, then switch the phone to flight mode. Watch what the website does when the prompt times out.
- Pay with an Airtel or non-M-Pesa number, if you accept other methods, to see the fallback.
- Pay from the M-Pesa menu instead of the prompt using the order number, and check it lands in the unmatched or matched list as expected.
- Download the M-Pesa statement from the organisation portal and confirm every test transaction appears in your website's records too.
Refund the test payments through your normal process, which tests that process as well.
Is STK push right for you?
If your buyers are mostly Kenyan and on Safaricom, STK push is the checkout they expect. It is not the only route: aggregators and card gateways have their place, which we weigh up in our comparison of M-Pesa payment options for online business. We build STK push into business websites and stores through our web development service, and into fee, booking and invoicing platforms through custom system development.
