Create a beneficiary

post

https://api.checker.finance/v1/payments/beneficiaries

Register a payout beneficiary. It is validated at create time and
saved only if at least one enabled corridor for
payment_details.currency accepts it.

400 CURRENCY_NOT_ENABLED: no enabled corridor pays out in
payment_details.currency.
400 VALIDATION_ERROR: a required field is missing or malformed.
422 INVALID_BENEFICIARY: every eligible corridor rejected it;
message gives the reason.

China bank beneficiaries:

payment_details.bank_country_code and address.country must be CN.
swift_code: 8 characters, or 11 ending in [A-Z0-9]{3}, for a
supported bank.
bank_name must match that bank; common short forms (e.g.
"Citibank") are accepted.
account_number: uppercase letters and digits only.
address.postal_code: 3–16 characters.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

customer_id

string

Optional. When set, pre-registers with eligible providers for that customer

type

string

enum

required

Beneficiary legal entity type

Allowed:

business_name

string

Required when type is BUSINESS; forbidden for INDIVIDUAL

first_name

string

Required when type is INDIVIDUAL; forbidden for BUSINESS

middle_name

string

Optional; only allowed when type is INDIVIDUAL

last_name

string

Required when type is INDIVIDUAL; forbidden for BUSINESS

first_party

boolean

Optional; defaults to false

address

object

required

payment_details

object

required

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

201Created

400Bad request

401Unauthorized

409Conflict