Update a beneficiary

Partially updates an existing beneficiary. Returns the beneficiary in the same shape as POST /v1/beneficiaries.

The path id is the GlobalStack external identifier (ben_…).

Mutable fields

• name, label, metadata, merchant_reference
• Fiat: network, account_number, account_name, provider_id
• Crypto: network, address

Immutable fields

type, customer_id, currency, country_code. Including any of these in the request body fails validation with 400 bad_request. To re-attach a beneficiary to a different customer or change its currency/country/type, create a new beneficiary.

Semantics

• metadata is replaced whole-cloth when present. No deep merge — the new map fully replaces the stored map.
• merchant_reference is replace-only. Passing null to clear it is rejected as 400 bad_request.
• network change (fiat) requires provider_id to also be sent. The existing provider snapshot in details.provider is not guaranteed to be valid for the new network, so GlobalStack re-calls FX Engine getAccountProvider and refreshes the snapshot.
• provider_id change (fiat, on its own or alongside a network change) triggers an FX Engine call to refresh details.provider.
• All other validations from POST /v1/beneficiaries apply to the merged state: currency must be offramp-supported in details.country_code; the resulting network must be supported by the currency in that country; mobile-money beneficiaries require an account_name; crypto network must be supported by the currency.

Status preconditions

• pending → updated.
• active → updated.
• archived → 409 invalid_status.

Errors

• 400 bad_request — request body fails field-level validation, includes an immutable field, or sends merchant_reference: null.
• 400 invalid_input — a cross-field rule is broken (e.g. fiat network change without provider_id) or the merged state fails a currency/network check.
• 404 not_found — id does not exist or belongs to a different integration.
• 409 invalid_status — beneficiary is archived.
• 409 duplicate_resource — merchant_reference collides with another beneficiary in this integration.
• 500 external_service_unavailable — FX Engine call failed.

Example — change account number

PATCH /v1/beneficiaries/ben_01KPBAP7WTDKQKW5B3R31VPNX4
{
  "account_number": "0099887766"
}

Example — switch fiat network from bank to mobile_money

PATCH /v1/beneficiaries/ben_01KPBAP7WTDKQKW5B3R31VPNX4
{
  "network": "mobile_money",
  "provider_id": "prov_01KPBBNEWPR0V1DERZZZZZZZ4M",
  "account_number": "+2348012345678",
  "account_name": "Alice Johnson"
}