Skip to main content

​
Overview

This guide walks through the full payout lifecycle: checking your balance, creating a payee, adding a payment instrument, sending the payout, and tracking its status through to completion.

​
Prerequisites

  • An Anton Payments account with API keys
  • Funded balances in the source currency (sandbox has test balances pre-loaded)

​
1. Check your balance

Before sending a payout, verify you have sufficient funds: 
curl https://api.antonpayments.dev/v1/balances/USD \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": {
    "currency": "USD",
    "available": "50000.00",
    "held": "2000.00",
    "total": "52000.00"
  }
}
The available amount is what you can use for new payouts. Ensure it covers the payout amount plus any fees.

​
2. Create a payee

If you are paying someone for the first time, create a payee record: 
curl https://api.antonpayments.dev/v1/payees \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria@example.com",
    "country": "US"
  }'
Response
{
  "data": {
    "id": "pye_cng3q8s6ek9kc5qg1h1g",
    "type": "individual",
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria@example.com",
    "country": "US",
    "status": "active",
    "created_at": "2026-02-14T10:00:00Z"
  }
}
Save the id — you will need it to add an instrument and create the payout.

​
3. Add a payment instrument

Attach a bank account or other payment method to the payee: 
curl https://api.antonpayments.dev/v1/payees/pye_cng3q8s6ek9kc5qg1h1g/instruments \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_account",
    "currency": "USD",
    "details": {
      "account_number": "9876543210",
      "routing_number": "021000021"
    }
  }'
Response
{
  "data": {
    "id": "ins_cng3q8s6ek9kc5qg1h3g",
    "payee_id": "pye_cng3q8s6ek9kc5qg1h1g",
    "type": "bank_account",
    "currency": "USD",
    "status": "active",
    "created_at": "2026-02-14T10:01:00Z"
  }
}

​
4. Send the payout

curl https://api.antonpayments.dev/v1/payouts \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-1042-maria" \
  -d '{
    "payee_id": "pye_cng3q8s6ek9kc5qg1h1g",
    "instrument_id": "ins_cng3q8s6ek9kc5qg1h3g",
    "amount": "2500.00",
    "currency": "USD",
    "description": "Consulting fee - January 2026",
    "reference": "INV-1042"
  }'
Response
{
  "data": {
    "id": "pay_cng3q8s6ek9kc5qg1h2g",
    "payee_id": "pye_cng3q8s6ek9kc5qg1h1g",
    "instrument_id": "ins_cng3q8s6ek9kc5qg1h3g",
    "amount": "2500.00",
    "currency": "USD",
    "status": "pending_screening",
    "description": "Consulting fee - January 2026",
    "reference": "INV-1042",
    "created_at": "2026-02-14T10:02:00Z"
  }
}
Always include an Idempotency-Key for payout creation. This protects against duplicate payouts if your request is retried due to network issues. Use a deterministic value like your internal invoice or transaction ID.

​
5. Track the payout

​
Option A: Poll the status

curl https://api.antonpayments.dev/v1/payouts/pay_cng3q8s6ek9kc5qg1h2g \
  -H "Authorization: Bearer ak_test_..."
Set up a webhook subscription to get notified automatically as the payout moves through each stage: 
payout.created -> payout.screening -> payout.processing -> payout.sent -> payout.completed

​
Payout lifecycle

A payout progresses through these statuses:
StatusDescription
pending_screeningCreated, awaiting compliance screening
screeningCompliance checks in progress
pending_approvalFlagged for manual review
processingApproved, submitted to payment rail
sentPayment rail confirmed dispatch
completedFunds delivered to the payee
failedPayout could not be completed
returnedFunds returned after delivery attempt
cancelledCancelled before processing

​
Common issues

You will get a 400 error if available balance is too low. Fund your account or retry when pending payouts complete and release held funds.
Ensure the payee ID exists and belongs to your merchant account. Check you are using the right environment (sandbox vs production).
A payout requires both a payee_id and an instrument_id. Create an instrument on the payee before submitting the payout.
In production, compliance screening can take a few seconds to a few minutes. If a payout stays in pending_screening for more than 10 minutes, contact support.