4 min read · Planning guide
Planning & implementation decisions
Is your organization ready for an M-Pesa integration?
Prepare the account and API access, business references, allocation policy and exception responsibilities before requesting implementation. Use the worksheet to test observable payment outcomes; it does not certify provider approval or a deployed integration.
| Test input | Expected application result | Evidence to keep |
|---|---|---|
| Same confirmed event delivered twice concurrently | One payment allocation | Transaction identity, count and allocation record |
| No confirmation before timeout | Pending status; no false paid state | Request identity and supported follow-up outcome |
| Unknown invoice reference | Unallocated payment queued for review | Exception record and assigned owner |
| ERP unavailable after confirmation | Confirmation retained; transfer recoverable | Delivery attempts and replay result |
- Step 1 →
Prepare
Confirm API/account access and reference rules.
- Step 2 →
Test
Run normal and exception cases in an agreed environment.
- Step 3 →
Reconcile
Compare provider records, payments and allocations.
- Step 4
Sign off
Record remaining differences and operational ownership.
Exception & recovery path
Unexplained differences remain open with an owner and evidence. Never mark them reconciled merely because the overall totals match.
Which payment cases belong in acceptance testing?
Cover confirmed payment, delayed confirmation, simultaneous duplicate delivery, incorrect reference, conflicting amount and destination outage. For each, record the provider evidence, customer-visible status, ledger outcome and review owner. Reversal handling needs its own approved correction policy.
How do you reconcile at the end of a period?
For a defined merchant account and period, compare provider records to the internal payment register, then compare payments to allocations. Separate provider fees, reversals and timing differences according to the agreed accounting policy. Assign every unresolved difference to an owner.
How do you distinguish engineering tests from provider certification?
Sandbox tests validate your application’s behaviour for the cases supplied. They do not prove production approval, settlement behaviour or every provider failure mode. Record the API/version, environment, sample size and limitations with actual results.
Take this into your project discussion
- Merchant account / enabled API / environment: ____________________
- Invoice reference / transaction identity / allocation policy: ____________________
- Test case / expected result / actual result / evidence: ____________________
- Provider total / payment register / allocations / differences: ____________________
- Exception owner / action / resolution evidence: ____________________
- Production prerequisite / approval owner / review date: ____________________
Planning content reviewed . Confirm current provider requirements and project-specific assumptions before implementation.
1. Define the Payment Journey
Start with what is being paid: order, invoice, service fee, rent or installment. Decide which system creates the reference and amount, who initiates the payment and what the customer should see after completing or abandoning the action. A clear transaction identifier is essential to later matching.
2. Choose Supported Provider Services
Review current Safaricom documentation and the business account products relevant to your use case. Options may include STK Push, Paybill/C2B and related status or callback functions. API availability, production approval and merchant fees depend on the provider and the account—not on the design of the checkout screen.
3. Separate Request from Confirmation
A displayed prompt, initiated request or customer screenshot is not proof of settled payment. The backend should process supported provider confirmations and status checks, record transaction identifiers and time, and update business state only under the correct conditions.
4. Reconcile Against Business Records
Finance staff need to find successful transactions, partial payments, unmatched references, delayed messages, reversals and adjustments. Decide who reviews exceptions, how supporting evidence is stored and how errors are corrected without erasing the transaction history.
5. Handle Failures and Duplicate Messages
Design for timeouts, delayed callbacks, repeated notifications, unavailable services and customer retries. Suitable idempotency controls and clear status messages reduce duplicate allocations and support troubleshooting. Provider credentials must remain in secure server-side environments.
6. Connect Payments to the Right Workflow
Once payment is confirmed, the correct account, order or service record can update, and relevant staff or customer communication can follow. Map the source of truth, API permissions and error-handling rules before integration.
7. Test the Unhappy Paths
Run cases involving success, timeout, duplicate callback, incorrect reference, cancellation, unmatched amount and provider downtime. The business should know what a customer sees, what a staff member can inspect and when human intervention is required.
Provider Documentation
Use Safaricom’s Daraja 3.0 API catalogue to check current M-Pesa services and their documentation. Confirm the API version, account eligibility and production requirements for your chosen service before implementation.
Frequently asked questions
Can M-Pesa payments automatically update customer balances?
Where supported APIs and reliable account references exist, an integration can apply confirmed payments to appropriate records.
Is STK Push required for every Kenyan business?
No. Choose the appropriate provider service based on payment flow, business account and relevant documentation.