Update a Beneficiary - Anton Payments

PUT

beneficiaries

{id}

Update a beneficiary

curl --request PUT \
  --url https://api.antonpayments.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'DPoP: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "country": "US",
  "external_ref": "<string>",
  "metadata": {},
  "end_user_ip": "<string>"
}
'

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <token>',
    DPoP: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    display_name: '<string>',
    country: 'US',
    external_ref: '<string>',
    metadata: {},
    end_user_ip: '<string>'
  })
};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'country' => 'US',
    'external_ref' => '<string>',
    'metadata' => [
        
    ],
    'end_user_ip' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-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}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"country\": \"US\",\n  \"external_ref\": \"<string>\",\n  \"metadata\": {},\n  \"end_user_ip\": \"<string>\"\n}")

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

	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": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "type": "individual",
  "status": "active",
  "display_name": "Jane Smith",
  "country": "GB",
  "external_ref": "contractor-1042",
  "metadata": {
    "department": "engineering"
  },
  "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.

Path Parameters

string

required

Beneficiary ID (prefixed ben_).

Pattern: ^ben_[a-zA-Z0-9]+$

Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

Body

application/json

Mutable fields on a beneficiary. Fields not included are left unchanged.

display_name

string

Maximum string length: 255

country

string

ISO 3166-1 alpha-2 country code.

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

Example:

"US"

external_ref

string | null

Set to null to clear.

Maximum string length: 255

metadata

object

Replaces the existing metadata map in full.

Show child attributes

end_user_ip

string

Response

Beneficiary updated.

A person or business you pay. PII is tokenized in Basis Theory on creation — raw identifiers are never returned in this response. Use GET /v1/beneficiaries/{id}/pii to retrieve detokenized PII for a beneficiary you own.

string

required

Pattern: ^ben_[a-zA-Z0-9]+$

Example:

"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"

merchant_id

string

required

Pattern: ^mer_[a-zA-Z0-9]+$

type

enum<string>

required

Available options:

individual,

business

status

enum<string>

required

active — usable for payouts.
archived — soft-disabled by the merchant; not usable. Can be restored.
blocked — blocked by compliance. Not usable and cannot be restored via the API.

Available options:

active,

archived,

blocked

display_name

string

required

Derived from the tokenized PII on creation. For individuals, a concatenation of name fields; for businesses, the legal name.

Example:

"Jane Smith"

country

string

required

ISO 3166-1 alpha-2 country code.

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

Example:

"US"

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"

external_ref

string | null

Your own reference, if you supplied one at creation.

metadata

object

Show child attributes

Delete a BeneficiarySoft-deletes a beneficiary. The record is removed from active listings and can no longer be used to initiate new payouts. Historical payouts referencing this beneficiary remain unchanged and accessible. Archiving is typically preferred over deletion — see `POST /v1/beneficiaries/{id}/archive`. Archiving preserves the beneficiary in a disabled state that can be restored later.

⌘I

Update a beneficiary

curl --request PUT \
  --url https://api.antonpayments.com/v1/beneficiaries/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'DPoP: <api-key>' \
  --data '
{
  "display_name": "<string>",
  "country": "US",
  "external_ref": "<string>",
  "metadata": {},
  "end_user_ip": "<string>"
}
'

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer <token>',
    DPoP: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    display_name: '<string>',
    country: 'US',
    external_ref: '<string>',
    metadata: {},
    end_user_ip: '<string>'
  })
};

fetch('https://api.antonpayments.com/v1/beneficiaries/{id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'display_name' => '<string>',
    'country' => 'US',
    'external_ref' => '<string>',
    'metadata' => [
        
    ],
    'end_user_ip' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "DPoP: <api-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}"

	payload := strings.NewReader("{\n  \"display_name\": \"<string>\",\n  \"country\": \"US\",\n  \"external_ref\": \"<string>\",\n  \"metadata\": {},\n  \"end_user_ip\": \"<string>\"\n}")

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

	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": "ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1",
  "merchant_id": "mer_01HX8Z9K0M2N3P4Q5R6S7T8UZZ",
  "type": "individual",
  "status": "active",
  "display_name": "Jane Smith",
  "country": "GB",
  "external_ref": "contractor-1042",
  "metadata": {
    "department": "engineering"
  },
  "created_at": "2026-04-15T14:30:00Z",
  "updated_at": "2026-04-15T14:30:00Z"
}