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
Between 1 and 100 payouts. Each item takes the same fields as a single payout.
Response · 200
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
TheIdempotency-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
idempotencyKeyon an item wins over the derived one.
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.

