Skip to main content

​
Overview

Beneficiaries 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 beneficiaries

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

​
Adding payment instruments

A beneficiary 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.

​
Create the beneficiary first

curl https://api.antonpayments.com/v1/beneficiaries \
  -X POST \
  -H "Authorization: Bearer ak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "[email protected]",
    "country": "US",
    "currency": "USD"
  }'

​
Then add instruments

# US bank account
curl https://api.antonpayments.com/v1/beneficiaries/ben_abc123/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"
    }
  }'

​
Listing and filtering

Retrieve beneficiaries with pagination: 
# All beneficiaries
curl "https://api.antonpayments.com/v1/beneficiaries?limit=50" \
  -H "Authorization: Bearer ak_test_..."

​
Deletion considerations

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

​
Best practices

Create beneficiaries and verify their details well before you need to send a payout. This catches errors (wrong account number, invalid routing number) before time-sensitive payments.
Include the beneficiary’s email when creating them. This allows Anton to send delivery confirmations where applicable.
Don’t create duplicate beneficiaries for the same person. Use instruments to add multiple payment methods to a single beneficiary.
Keep a mapping between your internal user/vendor IDs and Anton beneficiary IDs. This makes it easy to create payouts from your business logic.