# Create bulk payout API

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.

## Endpoint
- **Method**: POST
- **URL**: https://api.moolre.com/open/transact/bulk

## Headers
| Header | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| X-API-USER | string | Yes | Your Moolre username. |
| X-API-KEY | string | Yes | Your wallet private API key. A public key is refused. |
| Idempotency-Key | string | No | 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. |

## Request Body
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| type | integer | Yes | Must be 1. |
| accountnumber | string | Yes | Your Moolre wallet account number. |
| currency | string | Yes | GHS or NGN. Must equal the wallet currency. |
| batchref | string | Yes | 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 | No | HTTPS URL (at most 512 characters) that receives bulk_payout.completed instead of the wallet callback URL. |
| atomic | boolean | No | 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 | Yes | 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). |

## Response (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).

```json
{
  "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": []
  }
}
```

## Response (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.

```json
{
  "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": []
  }
}
```

## Response (200 (HTTP 409 in strict mode) Batch reference reused)
batchref was already used with different items. Use a new batchref.

```json
{
  "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": []
  }
}
```

## How processing works

1. You submit the batch. Every row is validated at once; rows that fail are returned in data.rejected and never queued.
2. Accepted rows are queued (status queued). A background worker runs every minute and sends each item as an ordinary payout, using the item's externalref as the payout reference.
3. Each item moves queued, submitted, then succeeded, failed or pending. Each payout also sends its own payout.succeeded or payout.failed callback, exactly like a single payout.
4. When every item is final the batch is completed and Moolre sends bulk_payout.completed once.

If the wallet balance is below total_amount (fees are extra), the batch is still queued and the response carries balance_warning and balance. Each payout is checked against the real balance when it is sent, so top up before the worker reaches the item.

A payout that failed cannot be retried with the same externalref. Send failed items again in a new batch with new externalref values.

## Limits

| Limit | Value |
| --- | --- |
| Items per batch | 500 |
| Active batches per wallet | 20 queued or processing |
| Amount per item (GHS) | 200000.00 |
| batchref | 1 to 128 characters, unique per wallet |
| externalref | 1 to 128 characters, unique on the wallet across all payouts and batches |

## Fields every response can carry

These fields are additive: existing fields keep their names, order and types.

| Field | Meaning |
| :--- | :--- |
| error | On a failure: { code, message, fields: [{ field, code, message }] } listing every failing field. |
| meta | Always present, last in the object. meta.replayed is true only when the response is the stored answer to a repeated Idempotency-Key (absent otherwise). meta.requestid is the unique id of the request (also the X-Request-Id response header): quote it when you contact support. meta.notices is always an array, empty when there is nothing to report; each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See [Deprecations](https://docs.moolre.com/guides/deprecations). |

There is no outcome field. Decide the result from status, code and, on payment and transfer endpoints, data.txstatus (0 pending, 1 succeeded, 2 failed). These codes mean the result is unknown and may still succeed, so treat them as pending and check the status: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, SYS500. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.

Send X-Moolre-Http-Status: strict to receive real HTTP status codes (400, 401, 403, 404, 409, 422, 429, 5xx) instead of HTTP 200. See [Responses and request IDs](https://docs.moolre.com/guides/responses).
