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

# Bulk payouts

> Send up to 100 payouts in one request, with a result for each.

`POST /v1/payouts/bulk` takes a list of payouts and creates them one by one. Each item succeeds or fails on its own, so a batch can partly succeed.

## Send a batch

**Idempotency-Key** `string` *required*

One key for the whole batch.

**items** `array` *required*

Between 1 and 100 payouts. Each item takes the same fields as [a single payout](/guides/payouts.md#send-a-payout).

**extra item field**

**idempotencyKey** `string`

Optional. Your own key for this one item, up to 255 characters. If you leave it out, Payve derives a key from the batch key and the item's position.

```bash cURL
curl -X POST "$PAYVE_API_URL/v1/payouts/bulk" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Idempotency-Key: payroll-2026-11-batch-01" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "sourceCurrency": "NGN",
        "destinationCurrency": "NGN",
        "amount": 15000000,
        "method": "bank_transfer",
        "merchantReference": "payroll-2026-11-emp-001",
        "beneficiary": {
          "type": "bank_account",
          "accountNumber": "0123456789",
          "bankCode": "058",
          "holderName": "Ngozi Adeyemi",
          "country": "NG"
        }
      },
      {
        "sourceCurrency": "NGN",
        "destinationCurrency": "NGN",
        "amount": 22000000,
        "method": "bank_transfer",
        "merchantReference": "payroll-2026-11-emp-002",
        "beneficiary": {
          "type": "bank_account",
          "accountNumber": "0234567891",
          "bankCode": "058",
          "holderName": "Tunde Bello",
          "country": "NG"
        }
      }
    ]
  }'
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payouts/bulk`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.PAYVE_API_KEY,
    'Idempotency-Key': `payroll-${run.id}`, // one key per payroll run
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ items: run.items }),
});
const { data: results } = await res.json();

for (const result of results) {
  if (result.success) {
    await saveAccepted(run.items[result.index], result.data);
  } else {
    await saveRejected(run.items[result.index], result.error);
  }
}
```

```python Python
import os, requests

res = requests.post(
    f"{os.environ['PAYVE_API_URL']}/v1/payouts/bulk",
    headers={
        "x-api-key": os.environ["PAYVE_API_KEY"],
        "Idempotency-Key": f"payroll-{run.id}",  # one key per payroll run
    },
    json={"items": run.items},
    timeout=120,
)
res.raise_for_status()

for result in res.json()["data"]:
    item = run.items[result["index"]]
    if result["success"]:
        save_accepted(item, result["data"])
    else:
        save_rejected(item, result["error"])
```

```json Response · 200
{
  "data": [
    {
      "index": 0,
      "success": true,
      "data": {
        "id": 1870,
        "publicId": "pyt_1a7c3e9b5d0f2846",
        "status": "pending",
        "sourceAmount": "15000000",
        "merchantReference": "payroll-2026-11-emp-001"
      }
    },
    {
      "index": 1,
      "success": false,
      "error": "Wallet balance is insufficient for this transaction."
    }
  ]
}
```

**index** `integer`

The item's position in your `items` array, starting at 0.

**success** `boolean`

Whether Payve accepted this item.

**data** `object`

The payout, when `success` is `true`. The same shape as a single payout.

**error** `string`

Why the item was refused, when `success` is `false`. A message, not an error code.

> [!WARNING]
>
> **A `200` does not mean every payout was accepted.** The status covers the request, not the items.
> Read `success` on every result. A refused item is not retried for you.

> [!WARNING]
>
> **Accepted is not paid.** `success: true` means the payout was created. Each payout still finishes
> on its own and sends its own `payout.successful` or `payout.failed` event.

## How a batch is processed

* Items are created in order, one after another.
* One item failing does not stop the rest.
* The request returns when every item has been tried. Allow a long client timeout for a large batch.
* The whole body is validated first. One malformed item fails the whole request with `422`, and nothing is created.

## Idempotency for a batch

The `Idempotency-Key` header covers the whole batch.

* **Replay the same batch with the same key** and you get the first response back. No new payouts are created.
* **Each item also gets its own key**, derived from the batch key and its position. Sending the same items in the same order under the same key maps each row onto the payout it already created.
* **Your own `idempotencyKey` on an item wins** over the derived one.

> [!WARNING]
>
> Do not reorder, add or remove items and resend under the same batch key. The body is different, so
> the request is refused with `422 idempotency_key_reused`. Fix the failed items and send them as a
> **new** batch with a **new** key.

## Handling partial success

**1. Save every result**

Store `publicId` and `id` for each accepted item, and the error for each refused one.

**2. Fix the refused items**

Work out why each was refused: low balance, a limit, a bad account number.

**3. Send only those, as a new batch**

Use a new batch key. Never resend items that were accepted.

**4. Wait for the webhooks**

Track each accepted payout to `successful` or `failed`.

## Before you send

* **Check your balance.** `GET /v1/wallets/{currency}` shows what is available. Make sure it covers the whole batch plus fees. A batch larger than your balance can be partly accepted, with some payouts failing afterwards.
* **Check the recipients.** Run a [name check](/guides/name-check.md) on new accounts.
* **Give each item a `merchantReference`.** It is how you match results and webhooks to your own records.

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `400 validation_idempotency_key_required` | No `Idempotency-Key` header. | Send one. |
| `403` | The key lacks `payouts:write`. | Use a key with the scope. |
| `422 validation_missing_field` | `items` is empty, has more than 100 entries, or an item is malformed. | Fix the body. Nothing was created. |
| `422 idempotency_key_reused` | The batch key was used with a different body. | Use a new key for a new batch. |
| `200` with `success: false` items | Those items were refused. | Read each `error`. |
