Moolre Documentation

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.

OrderEndpointPurpose
1Mobile Money Collection or Payment LinkBuyer pays into the platform wallet
2Your ledgerRecord what each seller is owed (sale minus your commission)
3Validate NameCheck a seller's payout number once, when they register it
4Initiate Transfer or Bulk payoutPay sellers on your schedule
5Transfer Status, payout webhooksConfirm each payout
6List TransactionsReconcile the wallet with the ledger

Step by step

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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

SituationWhat to do
A buyer disputes a sale after the seller was paidMoolre 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 numberValidate Name again and have them confirm before the next payout
A payout item failsReturn the amount to "owed" and pay it in the next run with a new externalref
A payout is pending for a long timeNever resend. Check Transfer Status by externalref; the batch reports unresolved after 72 hours
The wallet is shortPay in priority order, or fund first. A low balance returns OM14 or APY21 and the item fails
A seller is paid twice by mistakeUnique 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.