Update a beneficiary

patch

https://api.checker.finance/v1/payments/beneficiaries/{beneficiary_id}

Partially update an existing beneficiary. Returns 400 CURRENCY_NOT_ENABLED when a payment_details patch sets a currency no enabled provider for the client can pay out.

The update is also synced to the provider(s) the beneficiary is registered with. When the beneficiary is registered with a single provider, that provider must currently be active and must accept the update: if the provider is not active the request returns 400 BENEFICIARY_NOT_ACTIVE, and if the provider rejects the change it returns 422 INVALID_BENEFICIARY / 422 PROVIDER_ERROR. In these failure cases the change is not persisted locally. When the beneficiary is registered with multiple providers, at least one must accept the update for the change to be persisted; providers that reject the update are deactivated for this beneficiary.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

beneficiary_id

string

required

Body Params

All fields optional (PATCH semantics)

first_party

boolean

business_name

string

first_name

string

middle_name

string

last_name

string

address

object

payment_details

object

Beneficiary payment details.

Bank (fiat) beneficiary — requires bank_name, account_name, currency, and
bank_country_code, plus exactly one routing identifier:

ABA / domestic US wire: routing_number + account_number
SWIFT: swift_code + account_number
IBAN / SEPA: iban (account_number not required; use for SEPA / SEPA_INSTANT EUR payouts)
UK domestic (GBP): account_number + bank_routing_codes (sort code) for FASTER_PAYMENTS / CHAPS

Crypto (on-chain) beneficiary — when wallet_address is present the
beneficiary is an on-chain recipient for the CRYPTO rail. Bank fields
(bank_name, bank_country_code, routing identifiers) are NOT required;
account_name, currency (any held on-chain asset ticker — stables and
BTC/ETH/SOL; conversion pairs gate quotes only), wallet_address,
and network are used.

USD bank beneficiary (customer-scoped provider) — currency USD with
routing_number (ABA) + account_number and a customer_id link. The
top-level first_party flag selects the destination model: true
registers the customer's own bank account, false registers a
third-party payee. Paid out on the ACH / FEDWIRE rails.

Headers

Idempotency-Key

string

required

Idempotency key required on all write requests. Replaying the same key with the same body returns the original response.

X-Api-Key

string

required

Your API key

X-Timestamp

string

required

Request timestamp (ISO 8601 UTC), included in the signature payload

X-Nonce

string

required

Unique request nonce (e.g. UUID)

X-Signature

string

required

HMAC-SHA256 hex digest of {METHOD}\n{path}\n{query}\n{X-Timestamp}\n{body}, signed with your API secret. Path excludes the query string; use an empty string for query/body when absent.

Responses

200OK

400Bad request

401Unauthorized

404Not found

409Conflict