Create an Instrument for a Beneficiary

Attach a payment instrument to a beneficiary. The credentials you submit (bank account numbers, wallet addresses, card PANs) are tokenized in Basis Theory on receipt — Anton’s core database stores only a token reference, a display-only masked value, and a content fingerprint used for cross-merchant deduplication.

The request body shape depends on the method — each method has a distinct credential schema. See the Instruments methods endpoint for the full per-country method catalog.

Requires an Idempotency-Key header.

POST

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 'DPoP: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "currency": "USD",
  "country": "US",
  "label": "<string>",
  "credentials": {},
  "is_default": false,
  "end_user_ip": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    DPoP: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'USD',
    country: 'US',
    label: '<string>',
    credentials: {},
    is_default: false,
    end_user_ip: '<string>'
  })
};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}/instruments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.antonpayments.com/v1/beneficiaries/{id}/instruments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'USD',
    'country' => 'US',
    'label' => '<string>',
    'credentials' => [
        
    ],
    'is_default' => false,
    'end_user_ip' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-key>",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.antonpayments.com/v1/beneficiaries/{id}/instruments"

	payload := strings.NewReader("{\n  \"currency\": \"USD\",\n  \"country\": \"US\",\n  \"label\": \"<string>\",\n  \"credentials\": {},\n  \"is_default\": false,\n  \"end_user_ip\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("DPoP", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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

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):

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.
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).
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.

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

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.

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

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"

List a Beneficiary's InstrumentsReturn all payment instruments attached to this beneficiary.

⌘I

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 'DPoP: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "currency": "USD",
  "country": "US",
  "label": "<string>",
  "credentials": {},
  "is_default": false,
  "end_user_ip": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    DPoP: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    currency: 'USD',
    country: 'US',
    label: '<string>',
    credentials: {},
    is_default: false,
    end_user_ip: '<string>'
  })
};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}/instruments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.antonpayments.com/v1/beneficiaries/{id}/instruments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'USD',
    'country' => 'US',
    'label' => '<string>',
    'credentials' => [
        
    ],
    'is_default' => false,
    'end_user_ip' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-key>",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.antonpayments.com/v1/beneficiaries/{id}/instruments"

	payload := strings.NewReader("{\n  \"currency\": \"USD\",\n  \"country\": \"US\",\n  \"label\": \"<string>\",\n  \"credentials\": {},\n  \"is_default\": false,\n  \"end_user_ip\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("DPoP", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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"
}