# Bulk payouts

Pay up to 500 recipients in one request: submit and validate, follow the batch, handle rejected rows and pending items, and the completion webhook.

## What a bulk payout is

A bulk payout is a batch of up to 500 ordinary payouts submitted in one request. Each item goes through the same payout path as Initiate Transfer, so fees, limits, provider routing and the per-payout webhooks are the same. The difference is that Moolre validates the whole batch, sends the items in the background, tracks each item, and tells you when the batch is finished.

Use it for payroll, commissions, supplier and marketplace payouts, and any run where you would otherwise loop over Initiate Transfer.

| Stage | What happens | What you do |
| --- | --- | --- |
| Submit | Every row is validated at once; bad rows are listed in data.rejected, good rows are queued | Fix and resubmit the rejected rows in a new batch |
| Process | A worker runs every minute and sends each queued item as an ordinary payout | Wait; poll Bulk payout status if you like |
| Per item | queued, submitted, then succeeded, failed or pending. Each payout also sends payout.succeeded or payout.failed | Update your own records per item |
| Complete | When every item is final the batch is completed and bulk_payout.completed is sent once | Reconcile and report |

## Before you start



- [ ] The private key, and your server IP on the disbursement whitelist.
- [ ] A wallet balance that covers the total plus fees (a low balance does not block the submit, but each payout is checked when it is sent).
- [ ] A unique externalref per item, unique on the wallet across all payouts and batches (case-insensitive).
- [ ] A unique batchref per batch (1 to 128 characters).
- [ ] A webhook endpoint for bulk_payout.completed and the per-item payout events.

## Step by step: submit a batch



1. Build the list of items. Each item needs externalref, receiver, channel (MTN, TELECEL, AT, BANK or GHQR) and amount (a string with at most two decimals). BANK items also need sublistid. sendername and reference are optional.
2. Choose the batchref, for example PAYROLL-2026-11. It identifies the batch for ever: store it with your payroll run.
3. Decide on atomic. With atomic true, one bad row refuses the whole batch (BLK07) and nothing is queued, which is the safe choice for payroll. Without it, good rows are queued and bad rows are reported.
4. Send Create bulk payout with an Idempotency-Key equal to the batchref.
5. Read the reply. BLK01 means queued: data.accepted counts the queued rows, data.rejected lists each bad row with its index, a BLKR code, a message and the externalref, and data.total_amount is the sum of the accepted rows. balance_warning and balance appear when the wallet balance is below total_amount.
6. Store data.batchid next to your batchref. Fix the rejected rows and send them in a new batch with a new batchref and new externalref values for the rows that need it.

```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": "PAY-1",
        "receiver": "0240000001",
        "channel": "MTN",
        "amount": "100.00"
      },
      {
        "externalref": "PAY-2",
        "receiver": "0240000002",
        "channel": "TELECEL",
        "amount": "50.00",
        "sendername": "Acme"
      },
      {
        "externalref": "PAY-3",
        "receiver": "0000012345",
        "channel": "BANK",
        "amount": "300.00",
        "sublistid": "030100"
      }
    ]
  }'
```

```json
{
  "status": 1,
  "code": "BLK01",
  "message": "Batch queued.",
  "data": {
    "batchid": "bat_3f9c2a1d7e5b4c60",
    "batchref": "PAYROLL-2026-11",
    "accepted": 3,
    "rejected": [],
    "total_amount": "450.00",
    "status": "queued",
    "currency": "GHS"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Create bulk payout (API reference)](https://docs.moolre.com/api/payouts/bulk)

## Step by step: follow the batch



1. Wait for the bulk_payout.completed webhook. It carries the batch summary: counts, succeeded_amount, failed_amount and unresolved.
2. Meanwhile (or if you prefer polling) call Bulk payout status with the batchid or batchref. status is queued, processing or completed.
3. Read the items. Page through them with after (send next_after from the previous page) and limit, and filter with status to see only failed or pending items.
4. For each succeeded item store transactionid, thirdpartyref and receivername. For each failed item read code and message.
5. When the batch status is completed, check unresolved. If it is true, some items were still pending after 72 hours: look each one up by externalref with Transfer Status. Do not assume they failed.

```curl
curl https://api.moolre.com/open/transact/bulk_status \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -d '{
    "accountnumber": "1000000000001",
    "batchref": "PAYROLL-2026-11",
    "status": "failed",
    "limit": 100
  }'
```

```json
{
  "status": 1,
  "code": "BLK21",
  "message": "Batch found.",
  "data": {
    "batchid": "bat_3f9c2a1d7e5b4c60",
    "batchref": "PAYROLL-2026-11",
    "status": "completed",
    "unresolved": false,
    "total_amount": "450.00",
    "counts": {
      "total": 3,
      "queued": 0,
      "submitted": 0,
      "pending": 0,
      "succeeded": 2,
      "failed": 1
    },
    "succeeded_amount": "150.00",
    "failed_amount": "300.00",
    "items": [
      {
        "index": 2,
        "externalref": "PAY-3",
        "receiver": "0000012345",
        "channel": "BANK",
        "amount": "300.00",
        "status": "failed",
        "code": "OM14",
        "message": "It looks like you have insufficient balance to make this payment. (OM14).",
        "attempts": 1
      }
    ],
    "next_after": null
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Item states and what to do



| Item status | Meaning | What to do |
| --- | --- | --- |
| queued | Waiting to be sent. May return here for an automatic retry when the network was unavailable and nothing was charged | Wait |
| submitted | Being sent | Wait |
| pending | The provider has not confirmed yet (code BLK30) | Do not resend. Check by externalref or wait for the webhook |
| succeeded | Paid; transactionid, thirdpartyref and receivername filled | Record it |
| failed | Not paid; code and message explain why | A failed externalref cannot be reused. Send the item again in a new batch with a new externalref |

## Rejected rows (BLKR codes)

Each rejected row has an index (its position in the items you sent, starting at 0), a code, a message and the externalref.

| Code | Meaning | Fix |
| --- | --- | --- |
| BLKR01 | externalref missing | Give every item an externalref |
| BLKR02 | externalref longer than 128 characters or has control characters | Shorten it |
| BLKR03 | externalref repeated inside the batch (case-insensitive) | Make each item unique |
| BLKR04 | externalref already used on this wallet (a payout or another batch) | Use a new externalref, or check the earlier payout |
| BLKR05 | receiver missing or malformed for the channel | MTN, TELECEL, AT: 9 to 15 digits. BANK: 6 to 24 digits |
| BLKR06 | Unknown channel | Use MTN, TELECEL, AT, BANK or GHQR |
| BLKR07 | amount missing, not a decimal, more than 2 decimals or below 0.01 | Send a string such as 25.00 |
| BLKR08 | amount above the per-payout maximum (GHS 200000.00) | Split the amount |
| BLKR09 | sublistid missing for BANK | Send the bank code from Get banks |
| BLKR10 | sendername invalid | 1 to 40 characters: letters, digits, space, full stop, apostrophe, hyphen |
| BLKR11 | reference invalid | At most 64 printable characters |
| BLKR12 | Item is not an object | Send each item as a JSON object |
| BLKR13 | Channel not available for NGN | NGN wallets use BANK only |

## Retrying a submit safely



1. If the submit times out, send it again unchanged, with the same batchref, the same items and the same Idempotency-Key.
2. Moolre returns the original batch with code BLK02 and data.replayed true (meta.replayed is true too when the Idempotency-Key matched). Nothing is queued twice.
3. If you send the same batchref with different items, you get BLK09. Use a new batchref for a new batch.
4. If you get BLK15 (20 batches are still active on the wallet), wait for some to complete.

> **The externalref is the real guard:** Every item is a payout with its own externalref, and the wallet-wide unique rule stays in force. Even a mistake in your own code cannot pay the same externalref twice.

## The completion webhook

Sent once, to the batch callback if you gave one (an HTTPS URL of up to 512 characters) or else to the wallet callback URL. Verify the signature and dedupe on event_id like every Moolre webhook.

```json
{
  "event": "bulk_payout.completed",
  "event_id": "evt_0123456789abcdef01234567",
  "created": "2026-11-15T09:20:00Z",
  "data": {
    "batchid": "bat_3f9c2a1d7e5b4c60",
    "batchref": "PAYROLL-2026-11",
    "accountnumber": "1000000000001",
    "currency": "GHS",
    "status": "completed",
    "unresolved": false,
    "total_amount": "450.00",
    "counts": {
      "total": 3,
      "queued": 0,
      "submitted": 0,
      "pending": 0,
      "succeeded": 2,
      "failed": 1
    },
    "succeeded_amount": "150.00",
    "failed_amount": "300.00",
    "completed": "2026-11-15T09:20:00Z"
  }
}
```

## Batch-level errors and fixes



| Code | Meaning | Fix |
| --- | --- | --- |
| BLK03 | type is not 1 | Send type 1 |
| BLK04 | accountnumber or batchref missing or invalid | Send both; batchref 1 to 128 characters |
| BLK05, BLK06 | items missing, empty, not a list, or more than 500 | Send 1 to 500 items; split larger runs into several batches |
| BLK07 | atomic was set and some rows were rejected; nothing queued | Fix the rows in data.rejected and resubmit |
| BLK08 | No valid items | Fix the rows and resubmit |
| BLK09 | batchref reused with different items | Use a new batchref |
| BLK10, BLK13 | Currency invalid, or different from the wallet currency | Send the wallet currency |
| BLK11, BLK12 | Account not found, or wallet inactive | Check accountnumber and that the wallet is active |
| BLK14 | callback is not an HTTPS URL | Use https and at most 512 characters |
| BLK15 | 20 batches already active | Wait for some to complete |
| BLK18 | A public key was used | Use the private key |
| TK01 | IP not whitelisted | Add the server IP in the app |

## Checklist



- [ ] Batch and item references are unique, stored before the submit, and derived from your own payroll or payout run.
- [ ] You use atomic for runs that must be all-or-nothing, and an Idempotency-Key equal to the batchref.
- [ ] You handle data.rejected and keep a record of every rejected row.
- [ ] You update your records per item from webhooks or Bulk payout status, not from the submit reply.
- [ ] You treat pending items as unknown and never resend them.
- [ ] You fund the wallet before the batch starts and watch balance_warning.
- [ ] You reconcile the batch total with succeeded_amount and the account statement.

- [Payroll with bulk payouts (playbook)](https://docs.moolre.com/use-cases/payroll)
- [Webhooks and callbacks](https://docs.moolre.com/guides/webhooks-and-callbacks)
