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".
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.
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
Creates the instrument and returns it as active. Pass beneficiary_id in the body: there is no per-payee create path.
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.
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:
- Create the new instrument with
default: true. The old one loses the default flag. - Send new payouts to the new
ins_ID. - 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:
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
GET /v1/instruments/methods?country=XX.pattern the catalog gives for that field.details lists every failing field.beneficiary_id names no payee of yours.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.