Payroll with bulk payouts
Environment: Live
Run payroll as an atomic bulk payout: freeze, fund, validate, submit, follow, fix failures and keep the audit record.
# 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
1. 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.
2. Check the wallet with Account Status. The balance must cover the total plus fees. If it does not, top up first.
3. 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.
4. 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.
5. 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.
6. 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).
7. Follow the run with the completion webhook. When it arrives, read counts and failed_amount.
8. 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.
9. Keep the batch summary and the item list as your audit record, and reconcile with the statement.
```curl
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"
}
]
}'
```
- [Bulk payouts](https://docs.moolre.com/guides/bulk-payouts)
- [Create bulk payout](https://docs.moolre.com/api/payouts/bulk)
## 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.