Update a Beneficiary
Update mutable fields on a beneficiary: display_name, country, external_ref,
and metadata. PII cannot be updated via this endpoint — use
PUT /v1/beneficiaries/{id}/pii instead, since PII is tokenized.
Fields not present in the request body are left unchanged.
Authorizations
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
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.
255Path Parameters
Beneficiary ID (prefixed ben_).
^ben_[a-zA-Z0-9]+$"ben_01HX8Z9K0M2N3P4Q5R6S7T8UA1"
Body
Mutable fields on a beneficiary. Fields not included are left unchanged.
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.