> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudpay.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk payments

> Up to 1,000 collections or payouts in one request.

| Endpoint | Scope |
| - | - |
| `POST /v1/merchants/{id}/bulk/collections` | `collect` |
| `POST /v1/merchants/{id}/bulk/disbursements` | `disburse`; live keys only |

```bash theme={null}
curl -X POST https://api.cloudpay.africa/cloudpay/v1/merchants/$MERCHANT_ID/bulk/disbursements \
  -H "Authorization: Bearer $CLOUDPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "payroll-2026-11",
    "items": [
      { "msisdn": "0712345678", "amount": 2500000, "idempotency_key": "emp-017", "narrative": "Nov salary" },
      { "msisdn": "0722000111", "amount": 1800000, "idempotency_key": "emp-018", "narrative": "Nov salary" }
    ]
  }'
```

How a batch is processed:

1. **The whole batch is checked first.** If any item is invalid, nothing is sent, and you get `400 invalid_batch_item` with the item number in `message`. For example: `item 3: amount must be a positive whole number of cents`.
2. **The balance must cover all of it.** For a payout batch from your Cloudpay balance, if the main balance can't cover every amount plus every fee, you get `422 insufficient_funds`, and nothing is sent.
3. **You get `202` with the batch `id`.** The items then start in the background.
4. **Track the batch.** `GET …/bulk/{id}` gives item counts by status. To see the items, use `GET …/disbursements?batch_id={id}` or `…/collections?batch_id={id}`.

Each item has its own `idempotency_key`, up to 60 characters and unique within the batch. Items fail and succeed independently. To retry the failed items, send them in a new batch with new keys.

Collection batches aren't limited to 3 prompts per phone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.