Anton.Docs
Dashboard (opens in a new tab)

Send payouts in bulk

Nothing is paid until you confirm, and confirming can't be undone. Upload one file of payouts, review what validation found, then read the result of every row.

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.

Before you begin

Decide: batch or a loop

Batch uploadPOST /v1/batches

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.

file (CSV or XLSX)metadata
Loop over the payout APIPOST /v1/payouts

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.

one JSON call per payout

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.

Download the template
curl "https://api.antonpayments.dev/v1/batches/template?format=csv" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -o batch-template.csv

format 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.

Upload a batch
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.

POST/v1/batches/{id}/confirmConfirm the batch

source_currency is the funding currency for rows that name none. The body is optional.

Reference
Not yet tested in sandbox
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

uploadedFile stored
async
validatingChecking rows
validatedReady to review
you confirm
confirmedYou approved
processingPayouts being created
completedEvery valid row paid

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}/results returns each row's status (success, failed, skipped or pending), its payout_id, and a message for any row that did not succeed.
  • GET /v1/batches/{id}/payouts lists the payouts the batch created. Reconcile against your source file by row number. Retry failed rows in a new batch.

What goes wrong

400invalid_file_format
Only .csv and .xlsx are accepted.
413file_too_large
The file is over 32 MB. Split it.
409duplicate_file
A batch with this exact file is still being processed. Wait for it to finish.
422batch_upload_failed
The upload could not be stored. Retry with a new key.
409batch_not_validated
The batch is still validating or failed validation. Wait, or fix the file.
409batch_confirmation_expired
You confirmed too late. Upload the file again.
422insufficient_balance
Your balance cannot cover the batch in one or more funding currencies. Fund it and confirm again.
422batch_confirm_failed
Confirmation did not complete. Retry with the same key.
409batch_not_cancellable
The batch is finished or already processing. Cancel its payouts one at a time.

Before you go live

  • Idempotency. Upload, confirm and cancel all require an Idempotency-Key. Use a key that names the run, such as payroll-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_hold or failed.
  • Rate limits. A 429 carries Retry-After in seconds. Wait that long before retrying. See Rate limits.
  • Credentials per environment. Sandbox credentials work against https://api.antonpayments.dev and production credentials against https://api.antonpayments.com. See Environments.
  • Test first. Fund a sandbox balance and run a small file end to end. See Test data.

Next steps

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗