Moolre Documentation

Step-by-step guides

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.

StageWhat happensWhat you do
SubmitEvery row is validated at once; bad rows are listed in data.rejected, good rows are queuedFix and resubmit the rejected rows in a new batch
ProcessA worker runs every minute and sends each queued item as an ordinary payoutWait; poll Bulk payout status if you like
Per itemqueued, submitted, then succeeded, failed or pending. Each payout also sends payout.succeeded or payout.failedUpdate your own records per item
CompleteWhen every item is final the batch is completed and bulk_payout.completed is sent onceReconcile 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 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"      }    ]  }'

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 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  }'

Item states and what to do

Item statusMeaningWhat to do
queuedWaiting to be sent. May return here for an automatic retry when the network was unavailable and nothing was chargedWait
submittedBeing sentWait
pendingThe provider has not confirmed yet (code BLK30)Do not resend. Check by externalref or wait for the webhook
succeededPaid; transactionid, thirdpartyref and receivername filledRecord it
failedNot paid; code and message explain whyA 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.

CodeMeaningFix
BLKR01externalref missingGive every item an externalref
BLKR02externalref longer than 128 characters or has control charactersShorten it
BLKR03externalref repeated inside the batch (case-insensitive)Make each item unique
BLKR04externalref already used on this wallet (a payout or another batch)Use a new externalref, or check the earlier payout
BLKR05receiver missing or malformed for the channelMTN, TELECEL, AT: 9 to 15 digits. BANK: 6 to 24 digits
BLKR06Unknown channelUse MTN, TELECEL, AT, BANK or GHQR
BLKR07amount missing, not a decimal, more than 2 decimals or below 0.01Send a string such as 25.00
BLKR08amount above the per-payout maximum (GHS 200000.00)Split the amount
BLKR09sublistid missing for BANKSend the bank code from Get banks
BLKR10sendername invalid1 to 40 characters: letters, digits, space, full stop, apostrophe, hyphen
BLKR11reference invalidAt most 64 printable characters
BLKR12Item is not an objectSend each item as a JSON object
BLKR13Channel not available for NGNNGN 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.

{  "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

CodeMeaningFix
BLK03type is not 1Send type 1
BLK04accountnumber or batchref missing or invalidSend both; batchref 1 to 128 characters
BLK05, BLK06items missing, empty, not a list, or more than 500Send 1 to 500 items; split larger runs into several batches
BLK07atomic was set and some rows were rejected; nothing queuedFix the rows in data.rejected and resubmit
BLK08No valid itemsFix the rows and resubmit
BLK09batchref reused with different itemsUse a new batchref
BLK10, BLK13Currency invalid, or different from the wallet currencySend the wallet currency
BLK11, BLK12Account not found, or wallet inactiveCheck accountnumber and that the wallet is active
BLK14callback is not an HTTPS URLUse https and at most 512 characters
BLK1520 batches already activeWait for some to complete
BLK18A public key was usedUse the private key
TK01IP not whitelistedAdd 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.