Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.antonpayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Editability note: this guide was drafted from the OpenAPI spec. If the product/engineering team has an updated batch flow (file schema, row limits, validation rules), edit inline — each H2 is self-contained.
Batch payouts let you send thousands of payments in one upload. The flow is three phases: upload → validate → confirm → process. You can’t skip steps; Anton requires you to explicitly confirm after seeing the validation summary.

​
When to use batches

  • Payroll — one upload per pay cycle
  • Marketplace disbursements — nightly seller settlements
  • Contractor payments — monthly or bi-weekly payouts to many contractors
For single-digit payouts per call, stick with POST /v1/payouts.

​
The file format

Download the template to start: 
curl "https://api.antonpayments.dev/v1/batches/template" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -o batch-template.csv
The template contains the canonical column order and example rows. Column order matters — Anton parses by position as well as name. Supported formats: CSV and XLSX. Each row is one payout instruction. Key columns include:
  • external_ref — your beneficiary reference (used to match existing beneficiaries or create new ones)
  • Beneficiary identity fields — populated only when creating a new beneficiary from the row
  • source_amount or dest_amount — decimal string
  • dest_currency, dest_country
  • method, reference, purpose
  • Method-specific credential columns (e.g., iban, sort_code, wallet_address)
Consult the downloaded template for the exact schema; do not reorder columns.

​
Upload a batch

curl "https://api.antonpayments.dev/v1/batches" \
  -X POST \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -F "file=@payroll-2026-04-30.csv"
  • Max file size: 32 MB
  • Max rows: contact support for current limits
The response returns the batch in uploaded status. Anton queues an async validation job — polling the batch endpoint will show the status moving through uploaded → validating → validated (or validation_failed). Duplicate uploads of the exact same file within 24 hours return 409 duplicate_file — use Idempotency-Key on the upload if you want deterministic retries (the file hash already acts as one, but explicit keys give clearer error handling).

​
Watch for validation

Validation is asynchronous. Poll or subscribe to webhooks: 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN"
When status moves to validated, the response includes a summary block:
  • new_beneficiaries / matched_beneficiaries / existing_beneficiaries
  • Method mix (count of rows per payment method)
  • Estimated debits per funding currency
  • FX markup in basis points
  • Balance-sufficiency check per currency
Review these before confirming. The batch has an expires_at — confirm before it expires, or the validated batch is marked expired and you have to re-upload.

​
Inspect errors before confirming

Row-level validation errors and warnings: 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID/errors" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN"
Errors block specific rows; warnings don’t. Typical errors:
  • Missing required columns
  • Invalid currency / country codes
  • Amount formatting (non-decimal, too many digits)
  • Beneficiary mismatch (PII conflicts with existing record at same external_ref)
  • Unsupported method for the destination country
Fix errors in your source file and re-upload — batches are immutable once uploaded.

​
Confirm a validated batch

Confirmation is irrevocable — once confirmed, Anton creates payouts from valid rows and starts processing. 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID/confirm" \
  -X POST \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "Idempotency-Key: confirm-$BATCH_ID" \
  -H "Content-Type: application/json" \
  -d '{"source_currency": "USD"}'
The source_currency in the body is the default funding currency for rows that didn’t specify one. Omit to let Anton use your account default.
Once a batch is confirmed you cannot cancel the batch as a whole via POST /v1/batches/{id}/cancel — that only works from pre-processing states. Individual payouts within the batch can still be cancelled via POST /v1/payouts/{id}/cancel up until they reach processing.

​
Watch processing

Status progression after confirmation: 
confirmed → processing → completed | partial | failed
  • completed — every valid row became a successful payout
  • partial — some rows succeeded, some failed during processing
  • failed — all rows failed
Subscribe to batch.completed and batch.failed webhook events rather than polling.

​
Inspect per-row results

Once processing finishes, pull the per-row outcomes: 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID/results" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN"
Each result has the original row number, outcome (success / failed / skipped / pending), and the created payout_id (if any). Use this to reconcile your source file with what actually shipped. For the created payouts themselves: 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID/payouts" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN"
These are normal Payout records — the full state machine applies, and each fires its own payout.* webhook events as it moves through processing and settlement.

​
Cancelling

Before processing starts (states: uploaded, validating, validated, validation_failed, confirmed before worker picks it up), cancel the whole batch: 
curl "https://api.antonpayments.dev/v1/batches/$BATCH_ID/cancel" \
  -X POST \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN"
Once processing starts, cancel individual payouts instead.

​
Resumability

Anton tracks a per-batch current_row_index checkpoint — if the batch worker restarts mid-process, it resumes from the last successfully processed row rather than re-processing everything. You don’t have to do anything for this to work; it’s platform behavior.

​
Next steps

Send a single payout

For low-volume, per-event payout flows.

Handle webhooks

Subscribe to batch.* and payout.* events for real-time status.