M-Pesa is how most Kenyan customers prefer to pay. Getting it to work reliably inside your website, app or POS, so that every payment automatically matches the right order, takes more care than it first appears. This guide explains the options and the pitfalls.
The building blocks: Safaricom Daraja
Safaricom exposes M-Pesa to developers through the Daraja API. The main products most businesses use are:
- STK Push (Lipa Na M-Pesa Online). Your system sends a payment request, and a prompt appears on the customer's phone asking them to enter their M-Pesa PIN. It is the smoothest checkout experience for websites and apps.
- C2B (Customer to Business). Customers pay to your paybill or till number, and Daraja notifies your system so it can match the payment to an account or order.
- B2C (Business to Customer). Your system sends money out: refunds, salaries, supplier or rider payouts, farmer payments.
- Transaction status and reversals. Tools for checking what happened to a payment and handling errors.
What you need before you start
- A paybill or till number registered to your business.
- A Daraja developer account and an app with the right products enabled.
- Credentials: consumer key and secret, your shortcode, and, for STK Push, a passkey; for B2C, an initiator name and security credential.
- A public HTTPS callback URL where Safaricom can send payment results.
- A go-live process. You test in the sandbox, then request production access.
How STK Push works in practice
- The customer chooses M-Pesa at checkout and enters their phone number.
- Your server requests an access token, then sends an STK Push request with the amount, phone number, shortcode and a reference to your order.
- Safaricom returns a CheckoutRequestID immediately. This does not mean the customer has paid.
- The customer approves the prompt on their phone.
- Safaricom sends the result to your callback URL, success or failure, with a receipt number.
- Your system marks the order paid, and the customer sees confirmation.
The key idea: the request and the result are separate. Your design has to handle the gap between them.
Mistakes that cost businesses money
Trusting the first response
The immediate response only tells you the request was accepted. Never mark an order as paid until the callback or a status query confirms success.
Ignoring failure and delay
Customers cancel prompts, enter wrong PINs, have insufficient funds, or the callback arrives late. A robust system:
- Shows clear states: waiting for payment, paid, failed, cancelled.
- Queries the transaction status if no callback arrives.
- Lets the customer retry without creating duplicate orders.
Duplicate callbacks
Callbacks can be delivered more than once. Make your handler idempotent so the same receipt number can never credit an order twice.
Weak matching of payments to orders
With C2B, customers mistype account numbers. Decide up front how you'll handle unmatched payments, with an exceptions queue instead of guesswork.
No reconciliation
Even with a good integration, you need a daily check that compares M-Pesa statements with your own records, so discrepancies are caught in days, not months.
Leaking credentials
Keep keys and security credentials in secure server-side configuration, never in front-end code or public repositories.
Beyond M-Pesa
Many businesses also want Airtel Money and card payments for international customers or larger tickets. Gateways such as Pesapal, Flutterwave, Paystack and Stripe can sit alongside M-Pesa in one checkout. The best mix depends on your customers, fees and settlement needs.
A simple checklist
- Paybill or till registered and Daraja app approved.
- Sandbox tests including failed, cancelled and delayed payments.
- Idempotent callback handling and clear order states.
- Alerts on failures, and a daily reconciliation report.
- Secure storage for credentials.
- A support process for "I paid but my order isn't confirmed."
How Vuvo Labs can help
We integrate M-Pesa, Airtel Money and card gateways into websites, apps, POS and billing systems, with the reconciliation layer that keeps your books accurate. If you'd like a review of your current flow, talk to us about payments.