API Reference / Bulk payouts
Create bulk payout
POSThttps://api.moolre.com/open/transact/bulk
Submit up to 500 payouts in one batch. Every item is validated when you submit; accepted items are sent in the background, one ordinary payout each (same fees, limits and per-payout callbacks as Initiate Transfer). Moolre sends a bulk_payout.completed webhook when every item has a final state.
Headers
- X-API-USER string required
Your Moolre username.
- X-API-KEY string required
Your wallet private API key. A public key is refused.
- Idempotency-Key string optional
Optional. 1 to 128 printable characters. Repeating a request with the same key and the same body returns the stored response with meta.replayed true for 24 hours; the same key with a different body returns IDEM01.
Body parameters
- type integer required
Must be 1.
- accountnumber string required
Your Moolre wallet account number.
- currency string required
GHS or NGN. Must equal the wallet currency.
- batchref string required
Your reference for the batch: 1 to 128 characters, unique per wallet. Sending the same batchref with the same items returns the original batch (BLK02); with different items it is refused (BLK09).
- callback string optional
HTTPS URL (at most 512 characters) that receives bulk_payout.completed instead of the wallet callback URL.
- atomic boolean optional
When true and any item fails validation, nothing is queued (BLK07). Default false: valid items are queued and the rest are listed in data.rejected.
- items array required
1 to 500 payout items. Each item: externalref (required, 1 to 128 characters, unique on the wallet across all payouts and batches, case-insensitive; extid is accepted as an alias), receiver (required: phone number of 9 to 15 digits for MTN, TELECEL and AT, account number of 6 to 24 digits for BANK, code for GHQR), channel (required: MTN, TELECEL, AT, BANK or GHQR; NGN wallets: BANK only), amount (required decimal string, at most 2 decimals; GHS at most 200000.00 per item), sublistid (BANK only: the bank code from Get banks), sendername (optional, 1 to 40 characters: letters, digits, space and . ' -) and reference (optional narration, at most 64 printable characters).
Responses
200 Success
The batch was validated and queued. data.rejected lists items that failed validation (index is the position in the submitted items array). A replay of the same batch returns BLK02 with data.replayed true (meta.replayed is also true when the Idempotency-Key matched).
{ "status": 1, "code": "BLK01", "message": "Batch queued.", "data": { "batchid": "bat_3f9c2a1d7e5b4c60", "batchref": "PAYROLL-2026-11", "accepted": 2, "rejected": [ { "index": 2, "code": "BLKR04", "message": "externalref has already been used on this wallet.", "externalref": "PAY-3" } ], "total_amount": "150.00", "status": "queued", "currency": "GHS", "balance_warning": true, "balance": "90.00" }, "go": null, "meta": { "requestid": "req_c68f4c66115c26725c796242", "notices": [] }}200 (HTTP 422 in strict mode) No valid items
Every item failed validation, or atomic was set and some failed. Nothing was queued. Read data.rejected.
{ "status": 0, "code": "BLK08", "message": "No valid items in this batch.", "data": { "accepted": 0, "rejected": [ { "index": 0, "code": "BLKR07", "message": "amount must have at most 2 decimal places. Send it as a string.", "externalref": "PAY-1" } ] }, "go": null, "meta": { "requestid": "req_c68f4c66115c26725c796242", "notices": [] }}200 (HTTP 409 in strict mode) Batch reference reused
batchref was already used with different items. Use a new batchref.
{ "status": 0, "code": "BLK09", "message": "batchref was already used with different items. Use a new batchref.", "data": "batchref", "go": null, "meta": { "requestid": "req_c68f4c66115c26725c796242", "notices": [] }}