Skip to main content

Preparing Your Batch File

CSV column headers, required fields, formatting rules, and maximum row limits.

Written by Ryan O
Updated today

Overview

Before uploading a batch, you need to prepare a properly formatted CSV file. This article covers the required format, column headers, and rules for creating a valid batch file.

Getting the Template

Download the official CSV template from the API to ensure you have the correct column headers:

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

You can also download the template from the merchant portal by navigating to Batch Payouts and clicking Download Template.

Column Headers

The CSV file uses the following columns:

  • payee_id (Required) -- The ID of the payee receiving the payout, e.g., pye_abc123. The payee must already exist in your account.

  • instrument_id (Required) -- The ID of the payment instrument to use, e.g., ins_abc123. Must belong to the specified payee.

  • amount (Required) -- The payout amount as a decimal string, e.g., 500.00. Must be greater than zero.

  • currency (Required) -- Three-letter ISO currency code, e.g., USD, GBP, EUR.

  • description (Optional) -- A human-readable description of the payout, such as "January salary" or "Consulting fee."

  • reference (Optional but recommended) -- Your internal reference for reconciliation, such as an invoice number or payroll ID.

Example File

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

Formatting Rules

  • File format: CSV (comma-separated values). XLSX is also supported.

  • Encoding: UTF-8.

  • Header row: The first row must contain column headers exactly as specified above.

  • Amounts: Use decimal format with two decimal places (e.g., 500.00 not 500). Do not include currency symbols or thousands separators.

  • Currency codes: Use uppercase three-letter ISO 4217 codes.

  • Empty rows: Blank rows are ignored during parsing.

  • Quoting: Fields containing commas must be enclosed in double quotes.

Limits

  • Maximum rows: 10,000 per batch. For larger volumes, split into multiple batches.

  • Balance requirement: Your available balance must cover the total batch amount at confirmation time.

Tips for Success

  • Include a unique reference for every row so you can match Anton payouts back to your source records during reconciliation.

  • Verify that all payee_id and instrument_id values exist before uploading. Missing IDs will cause row-level validation errors.

  • Test with a small batch in the sandbox environment before running large production batches.

Did this answer your question?