M-Pesa integration checklist for a business application
Plan payment references, confirmations, retries and reconciliation before adding M-Pesa to your website or business app.
Start with the payment you need to settle
Before writing an integration, decide what the customer is paying for: an invoice, an order, a subscription or a specific service. Give that record an internal identifier and keep its expected amount and currency. A payment prompt should point to an existing obligation, not create an untraceable credit.
Separate a request from a confirmed payment
When the customer receives a prompt, the payment may still be pending. They may cancel, enter the wrong PIN or leave the request unanswered. Keep a pending state until the server receives and validates the confirmation. Do not grant paid access simply because a request was accepted for processing.
Plan the failure paths
- Keep the internal order or invoice reference separate from the payment provider reference.
- Handle duplicate callbacks without applying the payment twice.
- Check the confirmed amount against the expected payment.
- Let staff identify payments that need investigation without changing a record to paid by guesswork.
- Provide a clear customer message for pending, failed and confirmed payments.
Use a document workflow as an example
Invoiced connects payment with document access. That relationship illustrates an important design question: which specific action becomes available after payment? In your own system, write down the action and make the server responsible for allowing it. Read about the Invoiced project.
Test before production
Use the provider's test environment for the supported scenarios, then plan a controlled production check. Include a successful payment, a failed request, a delayed confirmation and a duplicate callback. Confirm that staff can trace the resulting records. Live merchant onboarding and API requirements should be checked against the current Safaricom Daraja documentation.
Prepare a useful integration brief
Describe your current application, the payment type, expected customer journey, merchant setup and reconciliation process. Do not put API secrets in the brief. Explore Agilecode's M-Pesa integration service or discuss your workflow.
Tell us what you need to build.
Describe your project and the features you need.
