M-PESA integration for a Kenyan website: what the work involves

A payment prompt is the visible part

Most customers see an M-PESA prompt on their phone, enter a PIN and return to the website. Behind that short interaction, the website has to start the request, keep a pending order, receive Safaricom’s callback and match the result to the correct customer.

That is why M-PESA integration costs more than adding a Lipa na M-PESA logo. A production flow needs server-side code and a database record. It also needs a plan for delays, cancellations, wrong phone numbers and callbacks that arrive after the browser has closed.

Choose the payment flow first

STK Push suits checkouts because the site initiates a request for a stated amount. C2B registration and confirmation flows suit businesses that expect customers to pay a PayBill or Till and then need the system to recognise the transaction. B2C covers payouts, which is a different job with different controls.

Do not pick an API because its name appears in a tutorial. Write down what starts the payment, who chooses the amount, how the business identifies the customer and what should happen after a successful result. That description tells the developer which Daraja APIs and account setup are needed.

• Customer phone number and expected amount

• PayBill, Till or other approved business account

• Order or invoice reference

• Action after success, failure or timeout

• Refund and support process

Credentials and account ownership

The business should own the Safaricom business account and the Daraja application used in production. Keep consumer keys, secrets, passkeys and security credentials on the server. They do not belong in browser code, public repositories or screenshots sent through chat groups.

Sandbox credentials are for development. Production access requires the correct business details and approval steps in Safaricom’s process. Build time and account approval time are separate. A developer cannot solve missing documents by changing code.

Callbacks decide the real payment status

The browser is not the source of truth. Customers close tabs, lose data or press Back while the phone prompt is still open. The website should treat the server callback as the payment result, store the M-PESA receipt where supplied and prevent one callback from fulfilling an order twice.

Never mark an order as paid because a customer uploaded a screenshot. Screenshots can be altered and they do not prove that funds reached the business account. Staff need a transaction record they can compare with the M-PESA statement or portal.

• Store the request and checkout identifiers

• Record callback time and result code

• Keep successful receipt details

• Make repeated callbacks safe

• Allow staff to find a payment by order reference or phone number

Customer messages matter during delays

Some payments take longer than the neat demo shown during development. The checkout should say that a request was sent, let the customer retry when appropriate and avoid claiming failure before the final result is known. A pending screen is better than a false error.

Write support instructions for real cases. What should a customer do if money left the phone but the order still says pending? Which transaction details should they send? Who checks the business statement? Good copy prevents duplicate payments and panicked calls.

Test more than the successful payment

Test an accepted payment, a cancelled prompt, an incorrect PIN, a timeout, a duplicate callback and a callback received after the customer leaves. Check the amount and account reference on every path. Then confirm that order emails, stock changes and receipts happen once.

Run production tests with small agreed amounts after approval. Keep logs that omit secrets and full personal details. Payment support gets much easier when a developer can trace a request ID without exposing credentials or a customer’s PIN.

Related guides

Read next: E-commerce web design in Kenya

Read next: Custom web applications

Read next: Discuss an M-PESA integration

Read next: Safaricom Daraja developer portal