Anton.Docs
Dashboard (opens in a new tab)

Register a payee

A payee holds identity and nothing else. The details you send go to a vault, and Anton keeps a name and a token.

A payee is the person or business you pay. The API calls it a beneficiary, and its ID starts with ben_. A payee holds identity only. It cannot receive money until you attach an instrument to it.

Every payee belongs to one merchant. If two merchants pay the same person, each creates its own record. Personal details you send are tokenized. The payee record keeps a display name, a country and a token reference, never the raw details.

Before you begin

Choose the type

type decides which detail block you send. The block is named after it: individual or business. Send exactly one, matching type. country is required in both cases.

address takes street_line_1, city, postal_code and country. Add street_line_2 and state where the country needs them.

Register the payee

POST/v1/beneficiariesRegister the payee

Creates the payee and returns it with status active. Keep the id: you need it for the instrument and the payout.

Reference
Not yet tested in sandbox
curl -X POST \
  https://api.antonpayments.dev/v1/beneficiaries \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: ben-contractor-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "country": "GB",
    "external_ref": "contractor-1042",
    "metadata": {
      "department": "engineering"
    },
    "individual": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+442079460000",
      "birth_date": "1988-05-12",
      "nationality": "GB",
      "address": {
        "street_line_1": "10 Example Street",
        "city": "London",
        "postal_code": "SW1A 1AA",
        "country": "GB"
      }
    }
  }'

Two fields exist for your own use. external_ref is your ID for this payee, up to 255 characters. metadata is a string map for tags such as a department. Put no personal data in either.

Add end_user_ip when a person in your product triggered the call. It is optional and feeds risk signals.

Many payees at once is a different job. Import payees from a file creates them from a CSV.

What happens next

The payee starts active. Its risk_score and risk_tier are null and risk_signals is empty until the first score, shortly after creation. Scores run from 0 to 1000 and higher is worse. Show risk_signals[].label as it comes and branch on code.

archivedPaused by you
you archive · you restore
activeReady to pay
Anton blocks
blockedCannot be paid

You archive and restore. Anton blocks. A blocked payee cannot be used for payouts and cannot be restored through the API.

You can ask for a fresh check of an active payee with POST /v1/beneficiaries/{id}/rescreen. It returns 202 and the payee stays active until the check finishes. If the check blocks the payee, you get a beneficiary.blocked event.

Listen for these events instead of polling: beneficiary.created, beneficiary.updated, beneficiary.blocked and beneficiary.deleted. See Track payouts with webhooks.

Find a payee you already hold

Anton refuses an identity you already hold. A second create with the same details returns 409 duplicate_beneficiary. Treat that as "already registered", not as a failure.

To find the existing record, search on your own reference:

Find an existing payee
curl "https://api.antonpayments.dev/v1/beneficiaries?search=contractor-1042" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

search is a substring match on the display name and external_ref, so check the result for an exact external_ref before you reuse the ID. Store the ben_ ID next to your own record so you only search once.

Update a payee

The two update paths do different things.

PATCH /v1/beneficiaries/{id} changes display_name, country, external_ref and metadata. A field you leave out stays as it is. Send null to clear external_ref or metadata. It does not touch personal details.

PATCH /v1/beneficiaries/{id}/pii replaces the stored personal details. Vault tokens are immutable, so the block you send replaces the old one as a whole. A field you leave out is cleared, not kept. Send the complete block, even if one field changed. The display_name is re-derived from it.

Machine credentials can write personal details but cannot read them back. GET /v1/beneficiaries/{id}/pii answers 403 to an API credential. It works only for signed-in admin users of the merchant dashboard, and each read is audited. Keep your own copy of what you submit.

To stop paying someone, archive the payee. Archive keeps the record and the history, and you can restore it. Delete is for a payee you will never use again.

When it goes wrong

409duplicate_beneficiary
You already hold this identity. Search by external_ref and use that ID.
409idempotency_in_flight
Another request with the same key is still running. Wait a moment and send the same request again.
422validation_error
The block is missing, does not match type, or a field is invalid. details lists every failing field, so fix them in one pass.
422idempotency_key_reused
You sent the same key with a different body. Use a new key for a new payee.
404resource_missing
The ID does not exist, or it belongs to another merchant. Check the ben_ ID.
409beneficiary_not_active
A blocked payee cannot be archived or restored, and only an active payee can be re-screened.

Idempotency

POST /v1/beneficiaries requires an Idempotency-Key. Build it from your own data, such as ben-contractor-1042, so a retry after a network failure returns the original payee. A replay carries Idempotent-Replayed: true. Keys last 24 hours, and only a 2xx answer is stored, so a refused request runs again on retry. See Idempotency.

Next

Something wrong or missing here? Open an issue (opens GitHub in a new tab) ↗

Next in the core pathRegister an instrument