Anton.Docs
Dashboard (opens in a new tab)

Register an instrument

The account number goes in and never comes back out. What you get is a masked display and an ID to name on a payout.

An instrument is where a payee gets paid: a bank account, a wallet or a card. Its ID starts with ins_. Each instrument belongs to one payee. A payee can hold many, and a payout uses exactly one.

The credentials you send are tokenized on receipt. The API never returns them. You get back masked display fields such as masked_account: "IBAN ****3000".

Before you begin

Choose the method

method names the credential format you store, not the rail that delivers the money. One credential can route over several rails, and Anton picks the rail when you send the payout. The methods that exist depend on the payee's country.

Other values exist, including card, interac, pix, upi and mobile_money. Do not hard-code the fields. Ask the catalog.

List the methods for a country
curl "https://api.antonpayments.dev/v1/instruments/methods?country=DE" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

Each entry gives you method, category, default_currency and a fields list. Every field has a key, a label, a required flag and, where it applies, a pattern and an example. Build your form from that list. For a country picker, use GET /v1/instruments/countries. Germany, for example, returns iban, card and crypto.

Register the instrument

POST/v1/instrumentsRegister the instrument

Creates the instrument and returns it as active. Pass beneficiary_id in the body: there is no per-payee create path.

Reference
Not yet tested in sandbox
curl -X POST \
  https://api.antonpayments.dev/v1/instruments \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Idempotency-Key: ins-contractor-1042-eur-primary" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
    "method": "iban",
    "currency": "EUR",
    "label": "Primary account",
    "default": true,
    "credentials": {
      "account_holder_name": "Jane Smith",
      "iban": "DE89370400440532013000"
    }
  }'

currency is optional. Without it, the instrument takes the method's default_currency. label is yours, up to 255 characters. default: true makes this the payee's default instrument and clears the flag on the previous one.

The response carries the masked fields: display_last4, display_bank, display_network and masked_account. Show those in your UI. Do not ask for the account number again.

What happens next

An instrument is active or disabled. You move it between them.

activeCan be named on a payout
you set status
disabledNot usable on payouts

Set status with PATCH /v1/instruments/{id}. A deleted instrument leaves your listings and cannot be used on new payouts.

A payout accepts only an active instrument that belongs to the payee named on it.

Listen for instrument.created, instrument.updated and instrument.deleted. See Track payouts with webhooks.

Change an instrument

PATCH /v1/instruments/{id} changes label, default, status and metadata. A field you leave out stays as it is. metadata replaces the whole map. null clears label and metadata, and sets default to false.

You cannot change credentials. To rotate them, create a new instrument and delete the old one:

  1. Create the new instrument with default: true. The old one loses the default flag.
  2. Send new payouts to the new ins_ ID.
  3. Delete the old instrument. Delete removes its credentials from the vault. Past payouts that used it stay readable and unchanged.

Create before you delete, so the payee is never without a payable instrument.

Dedupe

An instrument you already hold for the payee returns 409 duplicate_instrument. Treat it as "already registered". List the payee's instruments and reuse the existing ID:

List one payee's instruments
curl "https://api.antonpayments.dev/v1/instruments?beneficiary_id=ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1&status=active" \
  -H "Authorization: DPoP $ANTON_ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

When it goes wrong

422method_not_supported
The method is not available in the payee's country. Check GET /v1/instruments/methods?country=XX.
422invalid_credentials
The credentials failed the method's format rules. Compare each value to the pattern the catalog gives for that field.
422validation_error
A field failed validation. details lists every failing field.
409duplicate_instrument
The payee already has this instrument. Reuse its ID.
409beneficiary_not_active
The payee is archived or blocked. Restore it first, or contact support if it is blocked.
404resource_missing
beneficiary_id names no payee of yours.
422idempotency_key_reused
The same key came with a different body. Use a new key.

Idempotency

POST /v1/instruments requires an Idempotency-Key. Derive it from your own data, such as the payee reference and a label, so a retry returns the original instrument. See Idempotency.

Anton also keeps a content fingerprint, used to spot duplicates. It never holds the account number, wallet address or card number. Keep your own record of what you sent if you need it back.

Next

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

Next in the core pathFund your balance