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

}

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

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

Uppercase supported fiat currency or crypto asset code.

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

Examples:

"USD"

"BTC"

"USDC"

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.

data

object

required

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.

Show child attributes

Example:

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

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

}

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

Overview

Cross-Cutting

Reference Data

Beneficiaries

Instruments

Intelligence

Verifications

Payouts

Batches

Balances

Accounts

Webhooks

Pricing

FX

Corridors

Create an Instrument for a Beneficiary

Authorizations

Headers

Path Parameters

Body

Response