How to Add M-Pesa STK Push to Your Kenyan Web App Step by Step

M-Pesa STK Push is one of the cleanest payment flows you can offer Kenyan customers. Instead of redirecting them to enter a PIN on a separate page, the prompt pops up directly on their phone. They approve the payment and you're done. Setting this up on your web app requires API access, proper authentication, and handling callbacks correctly—but it's straightforward once you know the sequence.

Getting Your M-Pesa API Credentials

Before you write any code, you need access to Safaricom's Daraja API portal. Go to the Safaricom Developer Portal at developer.safaricom.co.ke and register for a free account. You'll need a valid business or personal email and a phone number.

Once logged in, create a new app. Safaricom will give you a Consumer Key and Consumer Secret—treat these like passwords. Store them in your environment variables, never in your code repository. You'll also need your till number (also called till code or Merchant Code), which Safaricom assigns to your business.

Here's the critical part: test the connection using the OAuth endpoint first. Your app must exchange the Consumer Key and Secret for an access token before making any payment requests. This token expires in an hour, so your backend should handle token refresh automatically.

The STK Push API Flow

When a customer clicks "Pay with M-Pesa" on your app, your backend makes a request to Safaricom's STK Push endpoint. You send:

• The customer's phone number (formatted as 254XXXXXXXXX)
• The transaction amount in Kenyan Shillings
• A unique transaction reference
• Your callback URL where Safaricom will send the payment result
• A description of the transaction

Safaricom responds immediately with a RequestID and a ResponseCode. A ResponseCode of 0 means the STK prompt was sent successfully to the customer's phone. Then you wait.

The customer sees the M-Pesa prompt, enters their PIN, and either approves or declines. Safaricom then posts the result to your callback URL. This is where most implementations fail—developers forget to validate the callback or don't handle network timeouts properly.

Handling the Callback Correctly

Your callback endpoint will receive a POST request with the payment result. The payload includes the ResultCode (0 for success, other numbers for failures) and metadata about the transaction. Always validate that the request came from Safaricom using the security credentials they provide.

Your callback should respond quickly with a 200 status code. If Safaricom doesn't get a 200, it retries the callback multiple times, which can create duplicate entries in your database. Use a transaction ID to prevent this.

After validating the callback, update your database, send a confirmation email to the customer, and trigger whatever your app does next—unlocking a service, processing an order, or crediting an account.

If you're building a production app and want to avoid these pitfalls, consider working with M-Pesa integration developers who've already debugged common issues. If you're a sole founder handling this solo, test exhaustively in the Safaricom sandbox before going live.

Testing Before Going Live

Safaricom provides a sandbox environment where you can test with fake phone numbers and transaction amounts. Use it. Create a basic test flow: submit a payment, wait for the callback, verify it arrives and is processed correctly.

Common issues to watch for: callbacks timing out, transaction references that aren't truly unique, phone numbers formatted incorrectly, or trying to use real M-Pesa till numbers before going live. The sandbox uses different credentials than production, so you'll need to swap them when you're ready to launch.

Once customers start using STK Push, monitor your callback success rate. If it drops below 98%, investigate whether timeouts or validation errors are the culprit. Your logs are your best friend here.

Frequently Asked Questions

What's the difference between STK Push and redirect to M-Pesa?

STK Push shows the prompt directly on the customer's phone without leaving your app. Redirect methods send them to a Safaricom page. STK Push is faster and feels more native, which improves conversion rates.

How long does a payment callback take to arrive?

Usually 3 to 10 seconds after the customer enters their PIN. Sometimes longer if the network is congested. Always have a timeout handler on your frontend so customers don't wait forever wondering if it worked.

Can I use STK Push for international phone numbers?

No. M-Pesa only works for customers with Safaricom numbers in Kenya. If you need to accept payments from Tanzanian or Ugandan customers, you'll need a different payment provider.

What fees does Safaricom charge for STK Push?

Safaricom charges a transaction fee that varies by amount. Check the current rates on the Safaricom Developer Portal or contact their business support team directly—rates change periodically and depend on your merchant category.