M-Pesa STK Push Integration: The Complete Guide
Payments · Published Feb 15, 2024 · By Tech Deciphers
Step-by-step guide to integrating M-Pesa STK Push into your web or mobile application for Kenyan businesses.
M-Pesa STK Push (Sim Toolkit Push) is the payment method Kenyan customers expect. Instead of dialing a paybill number and typing an account reference by hand, STK Push sends a prompt directly to the customer's phone — they enter their PIN and the payment completes in seconds. For any business selling online in Kenya, it's the single highest-leverage integration you can build.
At a technical level, STK Push is part of Safaricom's Daraja API. The flow starts with your server requesting an OAuth access token, then calling the stkpush endpoint with the customer's phone number, amount, and a callback URL. Safaricom pushes the prompt to the phone, and — critically — your server does not get the result synchronously. You register a callback URL up front, and Safaricom posts the outcome (success, cancelled, or timed out) to that URL once the customer responds.
This asynchronous design is where most first-time integrations go wrong. Developers assume the initial API response tells them whether payment succeeded, but it only confirms the request was accepted — not that money changed hands. You need to persist a pending transaction record when you initiate the push, then update it when the callback arrives, and build a polling or webhook mechanism on your frontend so the customer sees a real-time result instead of a stuck spinner.
The other common failure mode is callback reliability. Safaricom's sandbox environment is forgiving, but production traffic means callbacks can arrive late, out of order, or occasionally not at all if your server was down. We always pair STK Push with a reconciliation job that queries the transaction status endpoint for anything still "pending" after a few minutes, so no payment silently falls through the cracks.
Get the idempotency, callback handling, and reconciliation right, and STK Push becomes a payment experience that feels instant and trustworthy — which, for a Kenyan audience, is the difference between a completed sale and an abandoned cart.