Use Cases
E-commerce checkout playbook
Take payments in an online store: the endpoints in order, the edge cases (double webhooks, closed tabs, timeouts) and a launch checklist.
The playbook in one page
A customer fills a cart, pays with mobile money, and you ship. The risky moments are the ones between "pay" and "paid": the OTP step, a slow approval, a duplicate webhook, and a customer who closes the tab. This playbook shows the endpoints in order and what to do at each edge.
| Order | Endpoint | Purpose |
|---|---|---|
| 1 | Your database | Create the order and a unique externalref |
| 2 | Mobile Money Collection (or Generate Payment Link) | Ask the customer to pay |
| 3 | Webhook payment.succeeded / payment.failed | Learn the result |
| 4 | Payment Status | Safety net for orders still pending |
| 5 | List Transactions | Daily reconciliation |
Step by step
- The customer presses Pay. Create the order (status pending) with a fresh externalref, for example the order number plus an attempt counter: ORDER-1001-1.
- Choose the flow. For a payment prompt on the customer's phone call Mobile Money Collection. For a hosted page call Generate Payment Link and redirect.
- Prompt flow: send the collection; on TP14 show an OTP field, send the code, then send the prompt again (with an Idempotency-Key). Show "Approve the payment on your phone" with a timer and a "I have paid" button that checks status.
- Result: your webhook handler marks the order paid on payment.succeeded (verifying the signature and deduping on event_id) or failed on payment.failed. The "I have paid" button and a poll of Payment Status do the same if the webhook is late.
- Fulfil exactly once: change status from pending to paid in one conditional UPDATE and only ship when that UPDATE changed a row.
- On failure show data.reason in plain words ("Wrong PIN", "Insufficient funds") and let the customer try again with a new attempt: new externalref.
- Every night run the reconciliation: statement against orders.
curl https://api.moolre.com/open/transact/payment \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -H "X-API-PUBKEY: $MOOLRE_PUBKEY" \ -H "Idempotency-Key: ORDER-1001-1" \ -d '{ "type": 1, "channel": "MTN", "currency": "GHS", "payer": "0240000001", "amount": "120.00", "externalref": "ORDER-1001-1", "accountnumber": "1000000000001" }'Edge cases
| Situation | What to do |
|---|---|
| The customer closes the tab after approving | The webhook still arrives. Mark the order paid from it. Send an email or SMS receipt |
| The webhook arrives twice | Dedupe on event_id; the conditional UPDATE also makes it harmless |
| The webhook never arrives | A job checks orders pending for more than a few minutes with Payment Status |
| TP18 or a timeout on the request | Do not create a new payment. Keep the order pending and check Payment Status |
| The customer pays twice | Two payments with two externalrefs exist. Your records show the second as unmatched: handle it as a refund you make yourself with a payout, after confirming with the customer |
| The amount received differs from the order | Do not ship; hold the order and investigate |
| The customer abandons the OTP | The order stays pending; cancel it by your own timeout |
| Wrong number entered | A prompt goes to someone else, who will decline. The payment fails with a reason; ask the customer to retry with the right number |
Checklist
- One unique externalref per attempt, stored before the request.
- Fulfilment is a conditional UPDATE from pending to paid, run once.
- The webhook is verified, deduped and fast; a status poll backs it up.
- The amount is checked against the order before shipping.
- The checkout shows clear states: waiting for approval, paid, failed with a reason.
- A daily reconciliation compares the statement with your orders.