Use Cases
Marketplace and platform payouts
Collect from buyers, keep your own ledger, and pay sellers or agents safely with name validation, bulk payouts and reconciliation.
The playbook in one page
A marketplace or platform collects money from buyers and pays sellers, drivers, creators or agents. Moolre has no split or escrow feature: you collect into your own wallet, keep the ledger of who is owed what yourself, and pay out when you decide. This playbook shows how to do that safely with the existing endpoints.
| Order | Endpoint | Purpose |
|---|---|---|
| 1 | Mobile Money Collection or Payment Link | Buyer pays into the platform wallet |
| 2 | Your ledger | Record what each seller is owed (sale minus your commission) |
| 3 | Validate Name | Check a seller's payout number once, when they register it |
| 4 | Initiate Transfer or Bulk payout | Pay sellers on your schedule |
| 5 | Transfer Status, payout webhooks | Confirm each payout |
| 6 | List Transactions | Reconcile the wallet with the ledger |
Step by step
- Onboard the seller: collect their payout phone number and network (or bank and account number). Call Validate Name, show the holder name and have the seller confirm it is theirs. Store the number, channel and the confirmed name.
- Collect from the buyer as in the checkout playbook. On payment.succeeded write ledger entries in one database transaction: the sale, your commission, and the amount owed to the seller.
- Decide when to pay: after delivery is confirmed, after a holding period, or when the balance owed passes a minimum. This is your rule, not an API feature.
- Build the payout list from the ledger: each seller with a balance owed above the minimum. Give each payout a unique externalref made from the seller and the payout run, for example PO-2026-11-15-seller42.
- Pay one seller with Initiate Transfer, or many with Create bulk payout (batchref equal to the run id). Mark ledger entries as "paying" before you send, so a crash cannot pay twice.
- On payout.succeeded mark entries paid. On payout.failed return the entries to "owed" and tell the seller (wrong number, network down), then pay again in a later run with a new externalref.
- Reconcile: owed plus paid plus your commission must equal what was collected, and the wallet balance must match.
curl https://api.moolre.com/open/transact/bulk \ -H "Content-Type: application/json" \ -H "X-API-USER: $MOOLRE_USER" \ -H "X-API-KEY: $MOOLRE_KEY" \ -H "Idempotency-Key: PO-2026-11-15" \ -d '{ "type": 1, "accountnumber": "1000000000001", "currency": "GHS", "batchref": "PO-2026-11-15", "atomic": false, "items": [ { "externalref": "PO-2026-11-15-seller42", "receiver": "0240000001", "channel": "MTN", "amount": "85.00", "sendername": "Acme Market", "reference": "Sales 8 to 14 Nov" }, { "externalref": "PO-2026-11-15-seller43", "receiver": "0240000002", "channel": "TELECEL", "amount": "40.50", "sendername": "Acme Market" } ] }'Edge cases
| Situation | What to do |
|---|---|
| A buyer disputes a sale after the seller was paid | Moolre has no refund or reversal API. Handle it in your ledger: recover from the seller's next payout, or pay the buyer from your wallet with a payout you decide on |
| A seller changes their number | Validate Name again and have them confirm before the next payout |
| A payout item fails | Return the amount to "owed" and pay it in the next run with a new externalref |
| A payout is pending for a long time | Never resend. Check Transfer Status by externalref; the batch reports unresolved after 72 hours |
| The wallet is short | Pay in priority order, or fund first. A low balance returns OM14 or APY21 and the item fails |
| A seller is paid twice by mistake | Unique externalref per seller per run makes this impossible within a run; across runs your ledger status guards it |
Checklist
- Sellers confirm the validated name before their first payout.
- The ledger is the source of truth; payouts follow it, never the other way round.
- Ledger entries are marked "paying" before the request and finalised from the webhook.
- Payout externalrefs are derived from the run and the seller; batchref from the run.
- Disputes and refunds are handled in your own rules, not assumed to be an API feature.
- Collections plus payouts plus commission reconcile with the wallet every day.