# 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



1. 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.
2. 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.
3. 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.
4. 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.
5. Fulfil exactly once: change status from pending to paid in one conditional UPDATE and only ship when that UPDATE changed a row.
6. On failure show data.reason in plain words ("Wrong PIN", "Insufficient funds") and let the customer try again with a new attempt: new externalref.
7. Every night run the reconciliation: statement against orders.

```curl
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"
  }'
```

```json
{
  "status": 1,
  "code": "TR099",
  "message": null,
  "data": "f25fc80e-791b-495b-8799-dcf87660457d",
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Collect payments, step by step](https://docs.moolre.com/guides/collect-payments)
- [Payment links and checkout](https://docs.moolre.com/guides/payment-links)

## 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.
