Skip to main content
GET
/
v1
/
instruments
/
{id}
Retrieve an instrument
curl --request GET \
  --url https://api.antonpayments.com/v1/instruments/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'DPoP: <api-key>'
{
  "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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.antonpayments.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

OAuth 2.0 client_credentials grant (RFC 6749 §4.4) bound to a DPoP keypair (RFC 9449).

Flow (every authenticated /v1 call requires both an access token AND a fresh per-request DPoP proof):

  1. Register a credential via the merchant portal. Anton issues a client_id (ant_oc_<env>_<32hex>) and a client_secret (ant_ocs_<env>_<48hex>, shown ONCE). The portal generates an ES256 or Ed25519 DPoP keypair in your browser; you store the private half.
  2. Mint an access token: POST /oauth/token with Authorization: Basic <client_id:client_secret> and Content-Type: application/x-www-form-urlencoded. Body: grant_type=client_credentials. A DPoP header carrying a proof signed for the token endpoint is required (no ath claim on this proof).
  3. Use the token: send Authorization: DPoP <access_token> plus a fresh DPoP: <proof> header on every /v1 request. The proof JWT MUST carry htm (request method), htu (request URL, no query/fragment), iat (within ±60s), jti (unique within 5 min), and ath (SHA-256 of the access token, base64url).

Tokens expire in 1 hour in production / staging and 8 hours in sandbox. There are no refresh tokens — call /oauth/token again with your secret. Anton's public signing key is published at /.well-known/jwks.json.

OpenAPI 3.0 has no native DPoP scheme; this declaration plus dpopHeader together convey both the access-token Authorization and the per-request proof header.

​
DPoP
string
header
required

Per-request DPoP proof JWT (RFC 9449). MUST accompany the Authorization: DPoP <access_token> header on every protected operation. The proof is signed by the merchant's private DPoP key and carries htm, htu, iat, jti, and ath claims.

Path Parameters

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

Response

Instrument.

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"