Moolre Documentation

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.

OrderEndpointPurpose
1Your databaseCreate the order and a unique externalref
2Mobile Money Collection (or Generate Payment Link)Ask the customer to pay
3Webhook payment.succeeded / payment.failedLearn the result
4Payment StatusSafety net for orders still pending
5List TransactionsDaily 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 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

SituationWhat to do
The customer closes the tab after approvingThe webhook still arrives. Mark the order paid from it. Send an email or SMS receipt
The webhook arrives twiceDedupe on event_id; the conditional UPDATE also makes it harmless
The webhook never arrivesA job checks orders pending for more than a few minutes with Payment Status
TP18 or a timeout on the requestDo not create a new payment. Keep the order pending and check Payment Status
The customer pays twiceTwo 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 orderDo not ship; hold the order and investigate
The customer abandons the OTPThe order stays pending; cancel it by your own timeout
Wrong number enteredA 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.