A practical checkout guide for Kenyan retailers that connects customer messages with payment requests, callbacks, settlement, refunds, reconciliation and a support path when the happy route breaks.
A payment prompt is not a completed order
The customer taps Pay. A phone prompt appears. They enter a PIN. The browser waits. Somewhere else, a payment provider sends a result to a server. The store creates or updates an order, finance later sees a settlement, and support may receive a screenshot if any part of that chain feels uncertain. Checkout trust is built by connecting those moments, not by painting the Pay button green.
The Safaricom Daraja developer portal exposes the APIs used for M-Pesa integrations. Card gateways use their own request and notification models. In both cases, the public interface should report only the state the store can verify, while the server treats provider callbacks or webhooks as untrusted messages that must be authenticated, recorded and handled safely.
Map the states before drawing the checkout
| State | What the customer should see | What the system and team must do |
|---|---|---|
| Ready | Total cost, delivery terms, chosen method and a clear Pay action | Create a priced order draft and validate stock, address and contact data |
| Request sent | A calm instruction to complete the prompt and avoid repeating the action | Store the provider request reference and prevent duplicate submissions |
| Customer action required | How to find or retry the prompt without losing the order | Keep the order pending and offer a controlled retry |
| Confirming | A truthful pending message, not an invented success screen | Wait for verified provider evidence or query status when supported |
| Paid | Receipt reference, order status and next fulfilment step | Mark the order once, trigger fulfilment once and record an audit event |
| Declined or cancelled | A plain reason where safe and another payment option | Keep the basket recoverable and avoid exposing provider internals |
| Unknown or delayed | The order reference and a support route | Queue reconciliation, avoid duplicate fulfilment and notify staff when needed |
| Refund requested | What was requested and the expected communication path | Check eligibility, approval and the original payment reference |
| Refunded | Amount, method, reference and support contact | Record the provider result and reconcile it with the order and settlement |
Callbacks must be safe to receive twice
Networks retry. Providers retry. Customers double-tap. A reliable payment handler assumes the same event may arrive more than once. It records a stable provider reference, verifies the notification, checks whether the transition already happened and makes the update idempotent. That means a repeated success callback does not create a second order, send a second fulfilment request or reduce stock twice.
Paystack's official webhook guidance recommends verifying event origins and returning a successful response promptly, then performing longer work outside the immediate response where appropriate. The exact verification method depends on the chosen provider, but the design principle is consistent: never trust a browser redirect alone as proof of payment.
Separate payment, order and settlement
These records are related but not identical. A payment can succeed while order creation fails. An order can be cancelled after a successful payment. A settlement can group many transactions and deduct fees. Finance needs a reconciliation view that can match store orders, provider transactions, refunds, fees and settlement deposits without relying on screenshots from customers.
- Give every order a reference before sending the customer to payment.
- Store provider request and transaction references separately from the order number.
- Keep an append-only record of payment state changes and who initiated manual actions.
- Flag paid orders without fulfilment and fulfilment attempts without verified payment.
- Provide a daily reconciliation path for exceptions, not only a monthly surprise.
Refunds need a product flow too
A refund button is the end of a decision, not the beginning. The operating rule should cover who may request, approve and execute a refund; whether partial refunds are allowed; what evidence is required; how the customer is updated; and how the order, inventory, provider record and accounting record change. Reversal and refund capabilities differ by provider and transaction state, so the interface must use the language of the implemented method rather than promising an instant outcome.
Test the awkward paths on purpose
- Customer closes the browser after authorising payment.
- The provider callback arrives late, twice or out of order.
- The checkout request times out but the customer was charged.
- Stock changes while the payment remains pending.
- A card requires additional authentication and the customer abandons it.
- A partial refund is approved after fulfilment has started.
- Support searches by order number, phone number and provider reference.
- Finance compares a provider settlement with the store's paid orders.
A credible E-commerce Experience connects the interface to these operating states. The customer gets clear language, staff get an exception queue, and finance gets records that can be reconciled. That is what payment confidence looks like when the banner image is removed.
Plan a Trustworthy Checkout