Batch payouts

Pay up to 1,000 people in one request, checked line by line before any money moves.

A batch carries a payroll file or a marketplace disbursement run as one request. Each line is a POST /payouts body, so anything you can send alone you can send in a batch.

How it works

1. Submit the run with your own externalReferenceId, the id of the payroll file or cycle. The answer is 202: received, not paid.
2. Validate. Every line is checked first, without pricing or debiting anything.
3. Confirm or cancel. A clean run with autoCommit: true goes straight to creation. A run with any invalid line, or with autoCommit: false, waits in awaiting_confirmation for you.
4. Create. The valid lines become ordinary payouts, with the same statuses, webhooks and bank returns as a payout sent alone.
5. Reconcile each created line through GET .../batches/{batchId}/items and the event feed.

Coverage

A batch line can pay any corridor a single payout can. See Countries and currencies for the list, and read GET /recipients/{orgId}/corridors for what your organization is routed to.

Enablement and limits

Batches are on by default, bounded by the same caps, holds and approvals as a single payout. If your organization has them turned off, submit and confirm answer 403 MASS_PAYOUTS_DISABLED; cancel and reads keep working. Test mode inherits the live setting.

Route	Limit
POST .../payouts/batches	30 per minute
GET .../batches, GET .../batches/{batchId}, GET .../batches/{batchId}/items	600 per minute each
Lines per batch	1 to 1,000

Split a bigger payroll into several batches, each with its own Idempotency-Key and externalReferenceId. Rate limits are covered on Environments & sandbox.

Key features

A run id that stops double runs

externalReferenceId is unique per organization, permanently. A job that loses its Idempotency-Key and re-runs the file under a fresh one gets 409 PAYOUT_BATCH_DUPLICATE_REFERENCE, and nothing is submitted.

One approval for the whole run

When your organization requires approval on API payouts, autoCommit is forced off and the first confirm opens one approval covering every line. Once approvers reach quorum, the run is released within a minute.

Lines you can export

GET .../batches/{batchId}/items?format=csv returns the whole run with each line’s status, payoutId and first error. Error codes match a single POST /payouts.

Integration guides

• Send a batch: submit, review, confirm and reconcile a run.
• Track status & failures: batch and payout statuses.
• Reconcile your ledger: the event feed every created line reports to.