Skip to main content
POST
/
v1
/
beneficiaries
/
{id}
/
instruments
Create an instrument for a beneficiary
curl --request POST \
  --url https://api.antonpayments.com/v1/beneficiaries/{id}/instruments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "method": "iban",
  "currency": "USD",
  "country": "US",
  "label": "<string>",
  "credentials": {},
  "is_default": false,
  "end_user_ip": "<string>"
}
'
{
  "id": "ins_01HX8Z9K0M2N3P4Q5R6S7T8UA2",
  "beneficiary_id": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "method": "iban",
  "currency": "EUR",
  "country": "DE",
  "label": "Primary EUR account",
  "display_last4": "5432",
  "display_bank": "Deutsche Bank",
  "masked_account": "DE89****5432",
  "status": "active",
  "is_default": true,
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z"
}

Authorizations

​
Authorization
string
header
required

API keys are opaque strings prefixed by environment:

  • ak_live_* — production keys, accepted only on api.antonpayments.com.
  • ak_test_* — sandbox keys, accepted only on api.antonpayments.dev.

Include your key in the Authorization header: Bearer ak_test_....

Headers

​
Idempotency-Key
string
required

Unique key identifying this operation. Sending the same key twice returns the original response instead of creating a duplicate. Keys are retained for 24 hours.

Maximum string length: 255

Path Parameters

​
id
string
required
Pattern: ^ben_[a-zA-Z0-9]+$

Body

application/json

Create an instrument attached to a beneficiary.

The credentials object shape varies by method. A few common shapes:

  • iban: { "iban": "GB82WEST12345698765432", "bic": "WESTGB22" } (BIC optional)
  • uk_bank: { "account_number": "12345678", "sort_code": "123456" }
  • us_bank: { "routing_number": "026073150", "account_number": "...", "account_type": "checking" }
  • crypto: { "wallet_address": "0x...", "network": "ethereum", "token_symbol": "USDC" }
  • card: { "pan": "...", "expiry_month": 12, "expiry_year": 2028 } (routed through PCI vault)

Call GET /v1/payment-methods?country=XX for the complete per-country catalog with the exact credential schema required.

​
method
enum<string>
required

Credential format of a payment instrument — named by what data is stored, not by the rail that delivers the funds. One credential type can route to multiple rails (e.g. an IBAN can go via SEPA, SEPA Instant, TARGET2, SWIFT, or CHAPS — the rail is selected at payout time).

Query GET /v1/payment-methods for the full country-specific catalog including per-method credential schemas.

Available options:
iban,
uk_bank,
us_bank,
ca_bank,
au_bank,
nz_bank,
jp_bank,
in_bank,
za_bank,
ng_bank,
ph_bank,
cl_bank,
co_bank,
swift,
clabe,
cbu,
cci,
pix,
upi,
interac,
paynow,
fps_hk,
promptpay,
card,
crypto,
mobile_money
​
currency
string

ISO 4217 three-letter currency code.

Pattern: ^[A-Z]{3}$
Example:

"USD"

​
country
string

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$
Example:

"US"

​
label
string

Merchant-visible label for this instrument (e.g. "Payroll - primary account").

Maximum string length: 255
​
credentials
object

Method-specific credential fields. Tokenized on receipt.

​
is_default
boolean
default:false

Make this the default instrument for the beneficiary. The previous default (if any) is unflagged.

​
end_user_ip
string

Response

Instrument created.

A payment destination attached to a beneficiary. Credentials (account numbers, wallet addresses, card PANs) are tokenized in Basis Theory and never returned by the API. Only masked display fields and method metadata are exposed.

​
id
string
required
Pattern: ^ins_[a-zA-Z0-9]+$
Example:

"ins_01HX8Z9K0M2N3P4Q5R6S7T8UA2"

​
beneficiary_id
string
required
Pattern: ^ben_[a-zA-Z0-9]+$
​
merchant_id
string
required
Pattern: ^mer_[a-zA-Z0-9]+$
​
method
enum<string>
required

Credential format of a payment instrument — named by what data is stored, not by the rail that delivers the funds. One credential type can route to multiple rails (e.g. an IBAN can go via SEPA, SEPA Instant, TARGET2, SWIFT, or CHAPS — the rail is selected at payout time).

Query GET /v1/payment-methods for the full country-specific catalog including per-method credential schemas.

Available options:
iban,
uk_bank,
us_bank,
ca_bank,
au_bank,
nz_bank,
jp_bank,
in_bank,
za_bank,
ng_bank,
ph_bank,
cl_bank,
co_bank,
swift,
clabe,
cbu,
cci,
pix,
upi,
interac,
paynow,
fps_hk,
promptpay,
card,
crypto,
mobile_money
​
status
enum<string>
required
Available options:
active,
disabled
​
is_default
boolean
required

Whether this is the beneficiary's default instrument for payouts.

​
created_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
updated_at
string<date-time>
required

RFC 3339 / ISO 8601 timestamp in UTC.

Example:

"2026-04-15T14:30:00Z"

​
currency
string

ISO 4217 three-letter currency code.

Pattern: ^[A-Z]{3}$
Example:

"USD"

​
country
string

ISO 3166-1 alpha-2 country code.

Pattern: ^[A-Z]{2}$
Example:

"US"

​
label
string

Merchant-visible label.

​
display_last4
string

Last 4 characters of the primary credential (account number / PAN / wallet address), for display.

​
display_bank
string

Bank name derived from routing details, for display.

​
display_network
string

Card network or chain, for display (e.g. visa, ethereum).

​
masked_account
string

Fully masked credential for list views.

Example:

"****5432"