Skip to main content

​
Overview

Payees are the recipients of your payouts. This guide covers best practices for managing them at scale — creating different types, attaching multiple payment instruments, and handling common scenarios.

​
Individual vs. business payees

Choose the right type based on who you are paying:
TypeUse whenRequired fields
individualPaying a person (freelancer, contractor, employee, refund customer)first_name, last_name, country
businessPaying a company (supplier, vendor, partner)company_name, country

​
Create a payee

curl https://api.antonpayments.dev/v1/payees \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex@example.com",
    "country": "US"
  }'
Response
{
  "data": {
    "id": "pye_cng3q8s6ek9kc5qg1h1g",
    "type": "individual",
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex@example.com",
    "country": "US",
    "status": "active",
    "created_at": "2026-02-14T10:00:00Z"
  }
}

​
Adding payment instruments

A payee can have multiple instruments — different ways to receive payment. For example, a contractor might have both a US bank account and a UK bank account. 
# US bank account
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"
    }
  }'

# UK bank account for the same 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": "GBP",
    "details": {
      "account_number": "12345678",
      "sort_code": "601234"
    }
  }'
When creating a payout, specify which instrument to use via the instrument_id field.

​
Listing payees

Retrieve payees with cursor-based pagination: 
# First page
curl "https://api.antonpayments.dev/v1/payees?limit=50" \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": [
    {
      "id": "pye_cng3q8s6ek9kc5qg1h1g",
      "type": "individual",
      "first_name": "Alex",
      "last_name": "Chen",
      "status": "active"
    }
  ],
  "has_more": true,
  "next_cursor": "pye_cng3q8s6ek9kc5qg1h1g"
}

# Next page
curl "https://api.antonpayments.dev/v1/payees?limit=50&cursor=pye_cng3q8s6ek9kc5qg1h1g" \
  -H "Authorization: Bearer ak_test_..."
Continue paginating while has_more is true, passing next_cursor as the cursor parameter.

​
Listing instruments for a payee

curl https://api.antonpayments.dev/v1/payees/pye_cng3q8s6ek9kc5qg1h1g/instruments \
  -H "Authorization: Bearer ak_test_..."
Response
{
  "data": [
    {
      "id": "ins_abc123",
      "type": "bank_account",
      "currency": "USD",
      "status": "active"
    },
    {
      "id": "ins_def456",
      "type": "bank_account",
      "currency": "GBP",
      "status": "active"
    }
  ],
  "has_more": false
}

​
Updating a payee

curl https://api.antonpayments.dev/v1/payees/pye_cng3q8s6ek9kc5qg1h1g \
  -X PATCH \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alex.chen@newdomain.com"
  }'

​
Deletion considerations

Payee deletion is permanent and cannot be undone. Before deleting, ensure there are no active or pending payouts to this payee.
When you delete a payee:
  • In-progress payouts to that payee will still complete
  • New payouts to that payee will fail
  • Historical data (completed payouts) is preserved for audit

​
Best practices

Create payees and verify their instrument details well before you need to send a payout. This catches errors (wrong account number, invalid routing number) before time-sensitive payments.
Include the payee’s email when creating them. This allows Anton to send delivery confirmations where applicable.
Do not create duplicate payees for the same person. Use instruments to add multiple payment methods to a single payee.
Keep a mapping between your internal user/vendor IDs and Anton payee IDs. This makes it easy to create payouts from your business logic.
Attach metadata to payees with your internal identifiers. This simplifies reconciliation and lookup across systems.