Use Cases
Payroll with bulk payouts
Run payroll as an atomic bulk payout: freeze, fund, validate, submit, follow, fix failures and keep the audit record.
The playbook in one page
Payroll is a batch of payouts that must be right: the right people, the right amounts, once. Moolre has no scheduled payouts, so you run payroll yourself (from your own scheduler or by hand) and use a bulk payout to send it. The bulk endpoint validates every row up front, queues the good ones, reports each result and tells you when the run is done.
| Order | Endpoint | Purpose |
|---|---|---|
| 1 | Account Status | Confirm the wallet can cover the run |
| 2 | Validate Name | Check new or changed payee numbers |
| 3 | Create bulk payout (atomic) | Submit the whole run |
| 4 | Webhook bulk_payout.completed, Bulk payout status | Follow the run |
| 5 | List Transactions | Reconcile and keep the audit record |
Step by step
- Freeze the payroll: a list of employees with the net pay in cedis as a string with two decimals, the payout number and network. Compute total_amount yourself.
- Check the wallet with Account Status. The balance must cover the total plus fees. If it does not, top up first.
- Validate new or changed numbers with Validate Name and have the payroll officer confirm the names. Do not validate the whole list every month: validate on change.
- Choose the batchref (PAYROLL-2026-11) and give each employee an externalref such as PAYROLL-2026-11-EMP0042. These are permanent identifiers: they can never be reused on the wallet.
- Submit with Create bulk payout: atomic true (one bad row stops the whole run), an Idempotency-Key equal to the batchref, and a callback if you want completion events on a separate URL.
- If you get BLK07, read data.rejected, fix the rows (BLKR codes tell you how) and submit again with the same batchref: the rows that were refused were never queued, so the corrected batch is a new request. If you change items you must use a new batchref (BLK09).
- Follow the run with the completion webhook. When it arrives, read counts and failed_amount.
- For each failed item read code and message: OM14 means fund the wallet and pay again; AVD02 or a wrong number means fix the number. Pay failed employees in a new batch with new externalrefs, and note it in the payroll record.
- Keep the batch summary and the item list as your audit record, and reconcile with the statement.
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: PAYROLL-2026-11" \ -d '{ "type": 1, "accountnumber": "1000000000001", "currency": "GHS", "batchref": "PAYROLL-2026-11", "atomic": true, "items": [ { "externalref": "PAYROLL-2026-11-EMP0001", "receiver": "0240000001", "channel": "MTN", "amount": "2450.00", "sendername": "Acme Ltd", "reference": "Salary Nov 2026" }, { "externalref": "PAYROLL-2026-11-EMP0002", "receiver": "0240000002", "channel": "TELECEL", "amount": "1980.00", "sendername": "Acme Ltd", "reference": "Salary Nov 2026" } ] }'Edge cases
| Situation | What to do |
|---|---|
| More than 500 employees | Split into batches of up to 500, each with its own batchref, for example PAYROLL-2026-11-A and -B. At most 20 batches may be active on a wallet |
| The submit times out | Send it again unchanged with the same Idempotency-Key. You get BLK02 (data.replayed true, and meta.replayed true for the same Idempotency-Key), not a second payroll |
| An item stays pending | Do not pay the employee again. Check by externalref, wait; the batch is unresolved after 72 hours if it is still pending |
| A number is wrong and the payout succeeded to a stranger | Moolre has no reversal API. This is why you validate names; handle recovery through your own process |
| The wallet runs dry mid-run | Items fail with OM14. Fund the wallet and pay those employees in a new batch |
| Partial pay | Create a new batch with new externalrefs for the difference; never edit a submitted batch |
Checklist
- The run is frozen and totalled before submission, and the wallet is funded.
- batchref and every externalref are permanent and derived from the run and the employee.
- atomic is on for payroll; you read data.rejected when it fires.
- Pending items are never resent.
- Failed items are paid in a new batch after the cause is fixed.
- The batch summary is archived and reconciled with the statement.