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

string
required
One key for the whole batch.
array
required
Between 1 and 100 payouts. Each item takes the same fields as a single payout.
Response · 200
integer
The item’s position in your items array, starting at 0.
boolean
Whether Payve accepted this item.
object
The payout, when success is true. The same shape as a single payout.
string
Why the item was refused, when success is false. A message, not an error code.
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.
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.
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 on new accounts.
  • Give each item a merchantReference. It is how you match results and webhooks to your own records.

When it fails