Skip to main content

​
Overview

Batch payouts let you process many payouts in a single operation. Upload a CSV file with payout details, review the parsed results, confirm to execute, and track progress as individual payouts are processed. This is ideal for:
  • Payroll runs
  • Marketplace seller payouts
  • Monthly commission payments
  • Recurring supplier payments

​
Batch lifecycle

1

Upload

Upload a CSV file with payout details. Anton validates every row and reports errors.
2

Validate

Anton parses the file, validates payee IDs, instruments, amounts, and currencies. Errors are reported per row.
3

Confirm

Review the validation results and confirm the batch to begin processing.
4

Process

Individual payouts are created and submitted through the standard payout lifecycle (screening, approval, rail submission).
5

Complete

The batch reaches a terminal state once all individual payouts have resolved (completed, failed, or returned).

​
1. Get the CSV template

curl https://api.antonpayments.dev/v1/batches/template \
  -H "Authorization: Bearer ak_test_..." \
  -o batch-template.csv

​
CSV column headers

The template uses the following columns:
ColumnRequiredDescription
payee_idYesThe payee receiving the payout (e.g., pye_abc123)
instrument_idYesThe payment instrument to use (e.g., ins_abc123)
amountYesPayout amount as a decimal string (e.g., 500.00)
currencyYesThree-letter ISO currency code (e.g., USD, GBP, EUR)
descriptionNoHuman-readable description of the payout
referenceNoYour internal reference for reconciliation

​
Example CSV

payee_id,instrument_id,amount,currency,description,reference
pye_abc123,ins_001,500.00,USD,January salary,PAY-001
pye_def456,ins_002,1200.00,GBP,Consulting fee,PAY-002
pye_ghi789,ins_003,350.00,EUR,Commission,PAY-003

​
2. Upload the batch

curl https://api.antonpayments.dev/v1/batches \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -F "file=@payouts.csv"
Response
{
  "data": {
    "id": "batch_cng3q8s6ek9kc5qg1h5g",
    "status": "pending_review",
    "total_rows": 150,
    "valid_rows": 148,
    "error_rows": 2,
    "total_amount": "125000.00",
    "currency": "USD",
    "created_at": "2026-02-14T10:00:00Z"
  }
}

​
3. Check for errors

If there are validation errors, retrieve the details: 
curl https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g/errors \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": [
    {
      "row": 45,
      "field": "amount",
      "message": "Amount must be greater than 0"
    },
    {
      "row": 102,
      "field": "payee_id",
      "message": "Payee not found: pye_invalid"
    }
  ]
}
You have two options:
  • Fix the errors in your CSV and re-upload as a new batch
  • Confirm the batch with only the valid rows (error rows are skipped)

​
4. Confirm the batch

curl https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g/confirm \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Idempotency-Key: batch-confirm-2026-02-14"
This creates individual payouts for all valid rows. Each payout goes through normal screening and processing.

​
5. Track progress

# Batch status
curl https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": {
    "id": "batch_cng3q8s6ek9kc5qg1h5g",
    "status": "processing",
    "total_rows": 150,
    "valid_rows": 148,
    "error_rows": 2,
    "completed_count": 95,
    "failed_count": 3,
    "pending_count": 50,
    "total_amount": "125000.00",
    "currency": "USD"
  }
}

# Individual payouts in the batch (cursor-based pagination)
curl "https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g/payouts?limit=50" \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": [
    {
      "id": "pay_abc123",
      "payee_id": "pye_abc123",
      "amount": "500.00",
      "currency": "USD",
      "status": "completed"
    },
    {
      "id": "pay_def456",
      "payee_id": "pye_def456",
      "amount": "1200.00",
      "currency": "GBP",
      "status": "processing"
    }
  ],
  "has_more": true,
  "next_cursor": "pay_def456"
}

​
Handling partial failures

Batches can partially succeed. Some payouts may complete while others fail due to compliance screening, invalid instrument details, or rail errors. When a batch completes with failures:
  • The batch status becomes completed (not failed) as long as some payouts succeeded
  • Use the batch payouts endpoint to filter by status and identify failures
  • Failed payouts include error details explaining the reason
  • You can create new individual payouts to retry specific failures
# List only failed payouts in the batch
curl "https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g/payouts?status=failed&limit=50" \
  -H "Authorization: Bearer ak_test_..."

​
Cancelling a batch

Before confirmation, you can cancel the entire batch: 
curl https://api.antonpayments.dev/v1/batches/batch_cng3q8s6ek9kc5qg1h5g/cancel \
  -X POST \
  -H "Authorization: Bearer ak_test_..."
After confirmation, individual payouts can be cancelled (if they have not started processing) but the batch itself cannot be undone.

​
Limits and tips

Maximum 10,000 rows per batch. For larger volumes, split into multiple batches.
Your available balance must cover the total batch amount at confirmation time. If insufficient, the confirmation will fail. Check your balance before confirming.
Include a unique reference per row so you can match Anton payouts back to your source records. This is critical for reconciliation.
Subscribe to batch.completed and batch.failed events. Each individual payout within the batch also generates its own payout.* webhook events.
Always include an Idempotency-Key when confirming a batch. This prevents accidental double-confirmation if your request is retried.