How M-Pesa STK Push and confirmations work

When a customer pays by M-Pesa in your shop, several things happen behind the scenes between your shop, PayHero, and Safaricom's M-Pesa system. This guide explains each step so you can understand what's happening when a payment succeeds — or when something goes wrong.

The full payment flow at a glance

1. Customer adds items to cart and goes to checkout.
2. Customer chooses M-Pesa and enters their Safaricom phone number.
3. Your shop sends a payment request to PayHero with the order amount and phone number.
4. PayHero asks Safaricom to send an STK Push prompt to the customer's phone.
5. Customer enters their M-Pesa PIN on the prompt.
6. Safaricom processes the payment and notifies PayHero.
7. PayHero sends a confirmation callback to your shop.
8. Your shop marks the order as paid and shows the customer a confirmation page.

The whole process usually takes 10–30 seconds.

Step 1 — Customer enters their phone number

At checkout, your customer picks M-Pesa and types in their phone number. Your shop accepts numbers in any common format (e.g. 0712345678, +254712345678, 254712345678) and converts them to the format PayHero expects.

Step 2 — Your shop creates the payment request

When the customer taps Pay, your shop calls PayHero's API with:

• The order amount (rounded up to whole shillings)
• The customer's phone number
• Your channel ID (so PayHero knows whose channel to credit)
• An external reference (your order number — used to match the callback later)
• A callback URL (where PayHero should send the confirmation)

Your customer doesn't have to configure anything on the PayHero side — your shop sends the callback URL with every payment request automatically.

Step 3 — STK Push lands on the customer's phone

Within a few seconds, the customer's phone displays an M-Pesa prompt showing the merchant name, amount, and a field to enter their M-Pesa PIN. They have about 60 seconds to enter their PIN before the prompt expires.

While this is happening, your shop shows a "Waiting for payment confirmation" screen. The customer should not close or refresh this page until they're redirected.

Step 4 — The confirmation callback

Once the customer enters their PIN (or the prompt times out), Safaricom processes the result and PayHero sends a webhook to your shop's callback URL. The callback contains:

• Status — "Success" or "Failed"
• Result code — 0 means success; any other value means failure
• M-Pesa receipt number — the Safaricom transaction ID (e.g. SBC7E4T8YH)
• Amount paid and phone number
• External reference — your original order number, so we can match it

Your shop verifies these details, marks the order as paid, records the M-Pesa receipt against the order, and sends the customer to the order confirmation page.

Step 5 — Order confirmation

The customer sees a confirmation page with their order number and M-Pesa receipt. You receive an email notification, and the order appears in Dashboard → Orders with a status of Paid.

What happens if the customer cancels or times out

If the customer dismisses the STK prompt or doesn't enter their PIN in time, PayHero still sends a callback — but with a failure status. Your shop marks the payment attempt as failed and shows the customer a "Payment was not completed" message with the option to try again. No order is created until payment succeeds, so failed attempts don't clutter your orders list.

What happens if the callback never arrives

Very rarely, network issues mean PayHero's callback doesn't reach your shop. To handle this, your shop also polls PayHero every few seconds while the customer is waiting. If the polling confirms a successful payment but the callback hasn't arrived, the order is still marked as paid. This dual-channel approach means almost no successful payment is ever lost.

Why M-Pesa receipts matter

The M-Pesa receipt number on each order is your proof of payment from Safaricom. If a customer ever disputes a charge, you can show them this receipt — it matches exactly what they'll see in their M-Pesa SMS confirmation. Receipts appear on both the customer's order page and your seller order details.

Common questions

"Do I need to set up the callback URL on PayHero?"
No. Your shop sends the callback URL with every payment request, so PayHero always knows where to send the confirmation. There's nothing to configure on the PayHero side.

"Can customers pay from a non-Safaricom number?"
No. M-Pesa STK Push only works for Safaricom subscribers. Customers on Airtel or Telkom would need to use a different payment method.

"What happens to the money?"
Successful payments land in your PayHero account. From there, you can withdraw to your M-Pesa, bank, or paybill on a schedule you choose in your PayHero dashboard. Your shop has nothing to do with payouts — that's entirely between you and PayHero.

"Why is the amount rounded up?"
M-Pesa STK Push only accepts whole shilling amounts. If your cart total is KES 99.50, the customer is charged KES 100. This matches how M-Pesa itself handles fractional amounts.