Quick Answer
A reliable M-Pesa workflow creates an order before payment, records payer and recipient separately, waits for confirmed provider status, matches one payment to one order, prevents duplicate processing, and exposes unmatched transactions for manual review. An STK prompt or customer screenshot is not proof of completed payment.
Create the order first
Generate an internal order ID with package, price, payer, recipient, and channel before requesting payment. This creates the context needed to process callbacks safely.
Use explicit payment states
State
Created
Meaning
Order exists; no payment request completed
Allowed action
Request or show payment
State
Pending
Meaning
Request sent; result not final
Allowed action
Wait and show status
State
Completed
Meaning
Provider confirmed success
Allowed action
Begin supported fulfilment once
State
Failed or cancelled
Meaning
Payment did not complete
Allowed action
Allow safe retry
State
Unmatched
Meaning
Money or callback lacks a clear order
Allowed action
Manual review
State
Reversed or refunded
Meaning
Money returned
Allowed action
Close and record reference
Separate payer from recipient
The number approving M-Pesa can differ from the line receiving the package. Store both and make the recipient visible before payment. Never infer the recipient from the M-Pesa message when the customer explicitly selected another number.
Make callbacks idempotent
Provider callbacks can be retried. Use a unique transaction reference or event key so the same successful payment cannot trigger fulfilment twice.
Verify server-side
Keep API credentials, signatures, callback secrets, and access tokens on the server. Do not trust amount or status sent by the browser. Log enough information to investigate without writing secrets into the log.
Reconcile unmatched money
Every incoming payment should map to an order or enter a review queue. Use account reference, amount, payer, time, and provider reference. Never silently discard a payment because the account reference is unfamiliar.
BingwaOne customer experience
BingwaOne can combine the mini-site, WhatsApp order, payment state, recipient, and fulfilment result. Customers receive clear pending, completed, or failed messages instead of guessing from the STK prompt.
Official References
Use Safaricom's official pages for current service terms and account-specific support.
- Safaricom Care guidance to access Bingwa Sokoni through *180*5#
- Safaricom guidance on who can join Bingwa Sokoni
- Safaricom M-PESA Business Till information
- Safaricom M-PESA Business Till guide
- Safaricom M-PESA Business channels and portals
- BingwaOne official website and agent tools
- BingwaOne Bingwa agent guide library
Frequently Asked Questions
Is an STK prompt proof of payment?
No. It only shows that a request was presented.
Can a screenshot confirm payment?
No. Use the provider-confirmed transaction.
Why is idempotency important?
It prevents duplicate callbacks from causing duplicate fulfilment.
What happens to unmatched payments?
They should enter a manual review queue, not disappear.
Does BingwaOne register or activate new Bingwa Sokoni agents?
BingwaOne provides tools such as mini-sites, posters, WhatsApp automation, SMS, video ads, and analytics. For new agents looking to join, our self-serve onboarding guide at the /join page takes you through the step-by-step process of getting a till number and setting up your business, though Safaricom remains the official service provider.
BingwaOne
Turn the guide into a simpler daily workflow.
Use agent posters, a mobile storefront, WhatsApp automation, SMS, and business records from one workspace.
Create a free agent account