A batch turns one CSV or XLSX file into many payouts, each an ordinary payout with its own lifecycle and webhooks. The batch is immutable: to fix a row you fix the file and upload it again.
Decide: batch or a loop
Use it when the payouts already live in a file: a payroll run, a settlement report, a month of contractor invoices. You get one review step, one confirmation and per-row results. A batch can create payees and instruments from the rows.
Use it when each payout is triggered by an event in your system and needs its own response. Every call carries its own Idempotency-Key, and you handle each result yourself.
To load payees from a file without paying anyone, see Import payees.
Get the template
The template has the exact header row and a few example rows. Column order and casing matter, so build your file from it and do not rename columns.
curl "https://api.antonpayments.dev/v1/batches/template?format=csv" \
-H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF" \
-o batch-template.csvformat is xlsx (the default) or csv. The template is the only definition of the columns, so download it rather than building one.
Upload the file
Uploads are multipart/form-data, which the console can't send. Use curl or your HTTP client.
curl "https://api.antonpayments.dev/v1/batches" \
-X POST \
-H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
-H "DPoP: $DPOP_PROOF" \
-H "Idempotency-Key: payroll-2026-11" \
-F "file=@payroll.csv" \
-F 'metadata={"payroll_run":"2026-11"}'The file can be up to 32 MB. metadata is a JSON object string of strings, with at most 50 keys, and it must never hold personal data. The optional file_hash field (sha256: prefix) makes Anton refuse the upload if the hash does not match.
The batch comes back as uploaded. Validation runs asynchronously and the result arrives by webhook. Track payouts with webhooks covers delivery.
Review, then confirm
When the batch is validated, fetch it with GET /v1/batches/{id}. The summary shows new and matched payees, the mix of methods, estimated debits per currency, and a balance check per currency. Read balance_checks before you confirm.
If invalid_rows is above zero, read GET /v1/batches/{id}/errors. Each issue has a severity (error stops the row, warning does not), the 1-based row, the field and a message. Warnings carry a type of duplicate_in_batch or beneficiary_name_change.
source_currency is the funding currency for rows that name none. The body is optional.
curl -X POST \ https://api.antonpayments.dev/v1/batches/bat_01HX8Z9K0M2N3P4Q5R6S7T8UBT/confirm \ -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \ -H "DPoP: $DPOP_PROOF" \ -H "Idempotency-Key: confirm-bat_01HX8Z9K0M2N3P4Q5R6S7T8UBT" \ -H "Content-Type: application/json" \ -d '{ "source_currency": "USD" }'
The batch becomes confirmed, then processing as payouts are created from the valid rows. Invalid rows are not paid.
A validated batch carries an expires_at, the deadline for confirming it. Miss it and you get batch_confirmation_expired; upload the file again.
Follow the lifecycle
Other outcomes: validation_failed after validating, partial (some rows failed) or failed (all rows failed) after processing, and cancelled. POST /v1/batches/{id}/cancel works from uploaded, validating, validated, validation_failed or confirmed. Once processing starts, cancel payouts one at a time with POST /v1/payouts/{id}/cancel. Treat a status you do not know as in progress.
Read the results
A partial batch is normal, not an error. Read the outcome row by row:
GET /v1/batches/{id}/resultsreturns each row'sstatus(success,failed,skippedorpending), itspayout_id, and amessagefor any row that did not succeed.GET /v1/batches/{id}/payoutslists the payouts the batch created. Reconcile against your source file by row number. Retry failed rows in a new batch.
What goes wrong
.csv and .xlsx are accepted.Before you go live
- Idempotency. Upload, confirm and cancel all require an
Idempotency-Key. Use a key that names the run, such aspayroll-2026-11, so a retried upload does not create a second batch. - Screening is per payout. Validation checks the file: format, amounts, methods, credentials and payee matching. Each payout the batch creates is checked separately before it is sent, so a confirmed row can still end in
on_holdorfailed. - Rate limits. A
429carriesRetry-Afterin seconds. Wait that long before retrying. See Rate limits. - Credentials per environment. Sandbox credentials work against
https://api.antonpayments.devand production credentials againsthttps://api.antonpayments.com. See Environments. - Test first. Fund a sandbox balance and run a small file end to end. See Test data.