Moolre Documentation

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.

OrderEndpointPurpose
1Account StatusConfirm the wallet can cover the run
2Validate NameCheck new or changed payee numbers
3Create bulk payout (atomic)Submit the whole run
4Webhook bulk_payout.completed, Bulk payout statusFollow the run
5List TransactionsReconcile 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 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

SituationWhat to do
More than 500 employeesSplit 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 outSend 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 pendingDo 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 strangerMoolre has no reversal API. This is why you validate names; handle recovery through your own process
The wallet runs dry mid-runItems fail with OM14. Fund the wallet and pay those employees in a new batch
Partial payCreate 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.