Connecting an M-Pesa payment flow to the records around it
This case study describes a completed Statum project without naming the client. Connecting an M-Pesa payment flow to the records around it was the core design problem. It focuses on the system behaviour and delivery decisions that can be verified from the implementation scope.
01
Payment request
02
Provider callback
03
Reconciled record
Integration boundary
One transaction, a visible trail.
Application record
Customer, order, amount, and internal reference.
Provider response
Callback, provider reference, and event timing.
Operational status
Pending, success, failure, or human review.
The provider callback is part of the workflow, not the only source of truth.
Delivery anatomy
The useful work sits around the API call.
A payment request is only one part of the workflow. The product also needs to know who or what the payment belongs to, what happened when the provider responded, and what a person should do when a callback is delayed or duplicated.
Context
A digital product needed mobile-money payments connected to its own customer, order, or account records.
Integration
M-Pesa payment initiation, callback handling, status tracking, and reconciliation were treated as one connected system.
Evidence
The page records the delivered scope and integration responsibilities without inventing performance claims.
Delivered scope
What Statum delivered
- 01Payment initiation through an M-Pesa integration.
- 02Callback handling for asynchronous provider responses.
- 03Transaction states that separate pending, successful, failed, and review cases.
- 04Records and views that support reconciliation and follow-up.
- 05Application and integration boundaries that can be tested separately.
Operational reasoning
Why the workflow matters
A callback can arrive late, more than once, or after a user has already left the screen. Treating the provider response as the only source of truth makes it difficult to investigate exceptions. Recording the request, the provider response, and the internal transaction state gives the team a clearer operational trail.
Delivery decisions
How the delivery was structured
The work was treated as a connected workflow rather than a single payment button. The application needed a clear boundary between its own order or customer records and the provider-facing integration. That boundary made it possible to test application behaviour without depending on a live provider response for every scenario.
Payment requests were given an internal identity before the external call was made. Provider references and responses could then be attached to that identity, while the application kept its own status for pending, successful, failed, or review cases. This distinction is useful when an external response arrives late or does not contain enough context for an operator.
The operational handover also mattered. A team maintaining the integration needs to know which credentials belong to which environment, where callback events are recorded, how retries are handled, and who owns reconciliation when the provider record and the internal record do not agree. Those decisions are part of dependable payment integration work.
A useful starting point
What a similar project should clarify
A new M-Pesa integration should begin with the transaction journey, not only the API documentation. The team should map who starts the payment, what the customer sees, which records change, and which exceptions need human attention. From there, the technical design can cover authentication, idempotency, timeouts, retries, reversals, reporting, and access to sensitive transaction information.
Related capability
Build integrations people can operate.
Explore the API integration service behind payment, statutory, messaging, and business-system connections.