Add a payout destination to an existing beneficiary so you can use that recipient in quote and transaction flows.

⏱️
Time to integrate: Most teams can connect this endpoint in under 10 minutes after beneficiary creation is working and they know which payout destination details they need to collect.

What this endpoint does

Use this endpoint to attach a beneficiary account (a payout destination such as a bank account or wallet) to an existing beneficiary.

The beneficiary is the recipient profile. The beneficiary account is the specific destination where funds can be sent.

This separation lets you keep one beneficiary record while attaching one or more payout destinations over time.

When to call this endpoint

Call this endpoint when you need to:

add the first payout destination for a beneficiary
attach multiple payout destinations to the same beneficiary
prepare a recipient for quote generation and transaction execution
maintain payout destinations separately from beneficiary profile data

In most flows, you create the beneficiary first, then add the beneficiary account before generating a quote or executing a transaction.

Beneficiary vs beneficiary account

Use these objects for different purposes:

Object	Purpose
Beneficiary	Stores the recipient profile your organization pays
Beneficiary account	Stores the specific payout destination attached to that recipient

This model helps your team:

reuse the same recipient with different destination accounts
update payout destinations without recreating the whole beneficiary
separate recipient identity review from account-level validation

Authentication

Send your API key in the x-api-key header on every request.

Item	Value
Authentication method	API key
Required header	`x-api-key`
Rate limit scope	Per API key

Recommended workflow

Use this endpoint as part of the core payout setup sequence:

Fetch organization accounts.
Check verification status.
Create a beneficiary.
Add a beneficiary account.
Resolve bank details if your payout flow requires pre-validation.
Generate a quote.
Execute the transaction.

What data to prepare before adding a beneficiary account

Before sending the request, collect the destination data your payout flow requires.

At minimum, your team should confirm:

which payout method or destination type you are adding
the beneficiary this account belongs to
the account or wallet details needed for that destination type
any provider, country, network, or currency information required for routing
any compliance metadata your workflow requires before the destination can be used

⚠️
Needs confirmation: Exact request fields, supported account types, required routing fields, currency constraints, and validation rules should be confirmed in the API definition.

Validation guidance

Before calling this endpoint, validate destination details in your own system.

Recommended checks:

confirm the beneficiary ID exists and belongs to the intended recipient
normalize account numbers, wallet addresses, or identifiers before submission
verify country and provider values against the payout rail you intend to use
avoid saving duplicate destination accounts unless your operating model requires them
collect destination metadata needed later for support, reconciliation, or compliance review

If your payout flow supports bank transfers, consider resolving or validating bank details before allowing the destination to be used in live execution.

How to use the response

After the beneficiary account is created, store the returned beneficiary account ID in your backend.

You will typically use that ID to:

identify the correct destination during transaction preparation
retrieve or update the payout destination later
support operations, reconciliation, and customer support workflows
distinguish between multiple destinations attached to the same beneficiary

Common use cases

Add the first payout destination

Create the beneficiary, attach the destination account, then continue to quote generation and execution.

Add multiple destination accounts to one beneficiary

Use one beneficiary for the recipient and attach multiple bank or wallet destinations as needed.

Stage destinations for operations review

Add the destination account first, then let internal teams review or validate it before enabling transaction execution.

Production notes

Before using this endpoint in production:

Define who is allowed to attach payout destinations.
Decide whether destinations are enabled immediately or after internal review.
Log the internal actor or service that created each beneficiary account.
Validate destination details carefully to reduce failed payouts and support escalations.
Prevent accidental duplicate destination creation during repeated submissions or retries.

This endpoint has direct downstream impact on payout success, so destination quality matters as much as authentication.

Common failure cases

Authentication fails

Check these items first:

the x-api-key header is present
the API key belongs to the intended environment
the base URL is correct

The beneficiary does not exist or is not usable

If the request fails because the parent beneficiary is invalid:

confirm the beneficiary ID is correct
confirm the beneficiary was created in the same environment
confirm you are not mixing sandbox and production identifiers

Validation errors

If the API rejects the request:

verify all required destination fields are present
confirm the payload matches the intended payout method
check routing data, account identifiers, and provider values before retrying

Duplicate or conflicting payout destinations

If your team sees multiple similar destination records:

define whether the same destination can be stored more than once
add internal duplicate checks before calling the endpoint
ensure retries do not create repeated payout destinations unintentionally

The account is created but payouts still fail later

Saving a payout destination does not guarantee it is valid for execution.

Next check:

bank account resolution where applicable
quote generation inputs
transaction currency and network compatibility
transaction-specific validation rules

⚠️
Needs confirmation: Exact validation errors, duplicate handling behavior, supported payout destination types, and whether account verification happens at creation time should be confirmed from the API schema and backend behavior.

Enterprise implementation notes

Access control

Restrict beneficiary account creation to trusted backend services or approved internal operators.

Auditability

Record:

beneficiary account ID
beneficiary ID
destination type
internal customer, vendor, or counterparty reference
creating service or user
creation timestamp

Data handling

Treat payout destination data as sensitive operational data. Store only what your workflow needs, and align retention with your compliance and privacy requirements.

Troubleshooting checklist

Use this checklist if payout destination setup is blocking your flow:

Confirm authentication with x-api-key.
Confirm the beneficiary exists in the intended environment.
Confirm the payload matches the destination type you are adding.
Confirm all required routing and account fields are present and correctly formatted.
Store the returned beneficiary account ID for later steps.
Continue with bank account resolution or quote generation before testing execution.

Recommended next endpoints

After you add a beneficiary account, continue with:

Related pages

Create Beneficiary

Create the parent recipient record before attaching payout destinations.

Resolve Bank Account

Validate payout account details before generating a quote or executing a transaction.

Generate Quote

Price the transaction after the recipient and payout destination are ready.