Skip to main content
POST
/
v1
/
batches
Upload a batch
curl --request POST \
  --url https://api.antonpayments.com/v1/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file'
{
  "id": "bat_01HX8Z9K0M2N3P4Q5R6S7T8UBT",
  "merchant_id": "<string>",
  "uploaded_by": "<string>",
  "status": "uploaded",
  "file_name": "payroll_2026_04_15.csv",
  "file_format": "csv",
  "file_size": 123,
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z",
  "total_rows": 123,
  "valid_rows": 123,
  "invalid_rows": 123,
  "warning_rows": 123,
  "skipped_rows": 123,
  "processed_rows": 123,
  "summary": {
    "new_beneficiaries": 123,
    "matched_beneficiaries": 123,
    "existing_beneficiaries": 123,
    "methods": {},
    "estimated_debits": [
      {
        "currency": "USD",
        "amount": "1234.56",
        "fx_rows": 123,
        "same_currency_rows": 123,
        "rate_timestamp": "2026-04-15T14:30:00Z"
      }
    ],
    "fx_markup_bps": 123,
    "balance_check": {}
  },
  "source_currency": "USD",
  "current_row_index": 123,
  "expires_at": "2026-04-15T14:30:00Z",
  "confirmed_at": "2026-04-15T14:30:00Z",
  "confirmed_by": "<string>",
  "cancelled_at": "2026-04-15T14:30:00Z",
  "cancelled_by": "<string>",
  "processing_started_at": "2026-04-15T14:30:00Z",
  "completed_at": "2026-04-15T14:30:00Z"
}

Authorizations

​
Authorization
string
header
required

API keys are opaque strings prefixed by environment:

  • ak_live_* — production keys, accepted only on api.antonpayments.com.
  • ak_test_* — sandbox keys, accepted only on api.antonpayments.dev.

Include your key in the Authorization header: Bearer ak_test_....

Body

multipart/form-data
​
file
file
required

CSV or XLSX file. Filename is preserved.

Response

Batch accepted and queued for validation.

A batch upload. Moves through uploaded -> validating -> validated -> confirmed -> processing -> completed | partial | failed. Can be cancelled from any pre-processing state.

​
id
string
required
Pattern: ^bat_[a-zA-Z0-9]+$
Example:

"bat_01HX8Z9K0M2N3P4Q5R6S7T8UBT"

​
merchant_id
string
required
Pattern: ^mer_[a-zA-Z0-9]+$
​
uploaded_by
string
required

User ID of the operator who uploaded this batch.

​
status
enum<string>
required
Available options:
uploaded,
validating,
validated,
validation_failed,
confirmed,
processing,
completed,
partial,
failed,
cancelled
​
file_name
string
required
Example:

"payroll_2026_04_15.csv"

​
file_format
enum<string>
required
Available options:
csv,
xlsx
​
file_size
integer
required

Bytes.

​
created_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
updated_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
total_rows
integer
​
valid_rows
integer
​
invalid_rows
integer
​
warning_rows
integer
​
skipped_rows
integer
​
processed_rows
integer
​
summary
object

Validation summary the merchant reviews before confirming.

​
source_currency
string

Default funding currency used for rows that don't specify their own. Set at confirmation.

Pattern: ^[A-Z]{3}$
Example:

"USD"

​
current_row_index
integer

Resumability checkpoint — highest row index successfully processed.

​
expires_at
string<date-time>

Deadline for confirming a validated batch.

Example:

"2026-04-15T14:30:00Z"

​
confirmed_at
string<date-time>

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
confirmed_by
string
​
cancelled_at
string<date-time>

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
cancelled_by
string
​
processing_started_at
string<date-time>

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
completed_at
string<date-time>

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"