Beneficiaries Overview

Understand beneficiaries, beneficiary accounts, supported destination types, and why bank accounts should be resolved before use.

Prerequisites

Choose the payout country and rail before you create or attach a beneficiary account.

Overview

A beneficiary is a reusable recipient profile. A beneficiary account is the specific destination attached to that profile, such as a bank account, mobile money wallet, or crypto address.

Beneficiary
└── Beneficiary Account

Create the beneficiary once, then attach one or more destination accounts that can be reused in future payout flows.

Supported destination types

Type	Use it for	Common fields
Bank	Bank transfers and ACH-style rails	`accountNumber`, `accountName`, `networkId`, `country`
Mobile money	Mobile wallet payouts	`phoneNumber`, `provider`, `country`, `networkId`
Crypto	Wallet-address payouts	`chain`, `address`

Resolve before you create

For bank-based payouts, resolve the bank account before you attach it to a beneficiary. Resolution confirms the account holder name and reduces the risk of misdirected payouts.

Get networks → Resolve bank account → Create beneficiary → Add beneficiary account

What success looks like

you know the difference between a beneficiary and a beneficiary account
you know which destination fields apply to each payout type
you resolve bank accounts before attaching them to a beneficiary

Troubleshooting

The network ID is invalid

Fetch provider networks for the destination country and use the returned networkId instead of hardcoding bank or provider identifiers.

The resolved name does not match the recipient

Do not continue. Ask the customer or operations team to confirm the account details before creating the beneficiary account.

What's next

Next step	Why
Get Provider Networks	Select the correct payout network for the country.
Resolve a Bank Account	Validate bank account details before attaching them.
Create a Beneficiary	Create the recipient and attach a payout destination.