Moolre Documentation

Use Cases

Savings group (susu) collections

Run contribution cycles for a savings group: Payment IDs or prompts, reminders, your own ledger, and paying the pot out safely.

The playbook in one page

A susu or savings group collects a fixed contribution from every member each cycle and pays the pot to one member (rotating savings), or keeps a shared fund. Moolre has no recurring collections or mandates: nothing debits a member automatically. Instead you run each cycle yourself: you ask each member to pay (or they pay to their own Payment ID), you track contributions in your own ledger, and you pay the pot out when the cycle is complete.

OrderEndpointPurpose
1Create Payment ID (or Mobile Money Collection)A way for each member to pay
2SMS or WhatsAppRemind members when a contribution is due
3Webhook payment.succeeded, Payment StatusRecord each contribution
4Your ledgerTrack who has paid this cycle
5Validate Name, Initiate TransferPay the pot to the member whose turn it is
6List TransactionsReconcile the group wallet

Step by step: set up a group

  1. Create a wallet for the group in the Moolre app, so the group money is separate from anyone's own money.
  2. Register each member in your ledger with name, phone and network, and their turn in the rotation.
  3. Give each member a way to pay: either Create Payment ID per member (they pay to it by USSD whenever they wish), or you send a collection prompt each cycle with Mobile Money Collection. Use an externalref that carries the group, the cycle and the member, for example SUSU-G1-C07-M012.
  4. Validate each member's payout number once with Validate Name and have the member confirm their name. Do this at registration, not on payout day.
curl https://api.moolre.com/open/account/create \  -H "Content-Type: application/json" \  -H "X-API-USER: $MOOLRE_USER" \  -H "X-API-PUBKEY: $MOOLRE_PUBKEY" \  -d '{    "type": 2,    "phone": "+233240000001",    "name": "Ama Mensah",    "currency": "GHS",    "amount": "100.00",    "externalref": "SUSU-G1-M012",    "accountnumber": "1000000000001"  }'

Step by step: run a cycle

  1. At the start of the cycle open it in your ledger: for every member a due contribution of the fixed amount, with a due date.
  2. Send each member a reminder with the amount, the date and how to pay (their Payment ID, or tell them a prompt is coming). Use Send SMS or WhatsApp.
  3. If you use prompts, send Mobile Money Collection per member with the cycle externalref, handling the OTP step the first time.
  4. On each payment.succeeded webhook (or Payment Status for the externalref) mark that member paid for the cycle, once. Ignore duplicates by event_id.
  5. Chase members who have not paid by the due date with a second reminder. Pending payments are not paid: do not count them.
  6. When the cycle is complete (or your rules say it is), compute the pot: contributions received minus any group fee. Check the wallet balance with Account Status.
  7. Pay the pot to the member whose turn it is with Initiate Transfer: a unique externalref such as SUSU-G1-C07-PAYOUT, an Idempotency-Key, and a sendername of the group. Wait for payout.succeeded before you close the cycle.
  8. Close the cycle in your ledger and publish the result to members (who paid, who received).
curl https://api.moolre.com/open/transact/transfer \  -H "Content-Type: application/json" \  -H "X-API-USER: $MOOLRE_USER" \  -H "X-API-KEY: $MOOLRE_KEY" \  -H "Idempotency-Key: SUSU-G1-C07-PAYOUT" \  -d '{    "type": 1,    "channel": "MTN",    "currency": "GHS",    "amount": "1180.00",    "receiver": "0240000001",    "externalref": "SUSU-G1-C07-PAYOUT",    "reference": "Susu cycle 7",    "sendername": "Unity Susu",    "accountnumber": "1000000000001"  }'

Edge cases

SituationWhat to do
A member pays lateRecord it against the cycle by externalref and date; your group rules decide any penalty
A member pays twiceTwo payments exist. Credit the next cycle in your ledger, or pay the extra back with a payout you decide on
A member never paysThe pot is smaller; your rules decide. Do not count pending prompts as contributions
The payout failsThe cycle stays open. Fix the cause (wrong number, balance), then pay with a NEW externalref (SUSU-G1-C07-PAYOUT-2)
The payout is pendingDo not pay again. Check Transfer Status by externalref and wait
A member leaves the groupSettle in your ledger; any payment back to them is an ordinary payout you initiate

Rehearse it in the sandbox

Use test numbers to rehearse a whole cycle: …111 members always pay, …999 pays with a wrong PIN, …555 stays pending for ever (your ledger must not count it). Reset between rehearsals.

curl https://sandbox.moolre.com/open/sandbox/reset \  -H "Content-Type: application/json" \  -H "X-API-USER: $MOOLRE_USER" \  -H "X-API-KEY: $MOOLRE_KEY" \  -d '{    "accountnumber": "1000000000001",    "scope": "all"  }'

Checklist

  • The group has its own wallet and its own ledger of cycles, members and contributions.
  • Every contribution has a unique externalref carrying group, cycle and member.
  • Only succeeded payments count; pending ones do not.
  • The pot is paid once, with a unique externalref and an Idempotency-Key, and confirmed before the cycle closes.
  • Members can see the result of every cycle.
  • Reminders and receipts are sent by you through SMS or WhatsApp.