Payment Destinations
Create Payment Destination
Add a bank account to a beneficiary
POST
Payment destinations are the bank accounts a beneficiary can receive funds into. Sensitive account fields are always masked in responses — the client API never returns full account numbers, IBANs, CLABEs, or PIX keys. Destinations are created under a beneficiary and then addressed directly by their own id (
dest_…).
Adds a bank account to a beneficiary. A
bank_account destination with payment_methods = ["pix"] (BRL) requires only a pix_key identifier instead of full bank account details.
Path Parameters
string
required
Id of the parent account (e.g.
acct_...).string
required
Beneficiary id (e.g.
bene_…).Request Body
string
required
ISO 3166-1 alpha-2 payment country code.
enum
required
Destination type. Always
bank_account.enum
required
Currency this destination receives.
string | null
Free-text label for display purposes.
string | null
Max 255 characters. Conditional: required for
bank_account (except PIX destinations). For country = MX this must be an 18-digit CLABE.string | null
Max 255 characters. Conditional: required for
bank_account.string | null
Max 50 characters (e.g.
checking, savings). Conditional: required for bank_account.string | null
PIX key identifier (CPF/CNPJ, email, phone, or random key). Conditional: required — and the only identifier needed — for a
bank_account destination with payment_methods = ["pix"].string | null
Max 100 characters.
string | null
Max 34 characters.
string | null
Max 11 characters.
boolean
default:"false"
Marks this as the beneficiary’s default destination. Defaults to
false.string | null
Max 255 characters.
Address | null
Bank address object.
string | null
Max 255 characters.
Address | null
Correspondent bank address (same shape as
bank_address).string | null
Max 11 characters.
string | null
Max 255 characters.
array | null
Payment methods this destination supports:
wire, ach, fedwire, spei, pix, manual.Response
Returns 200 with the new destination’sid. Use Get Payment Destination to retrieve the full (masked) object.
string
Id of the newly created payment destination (e.g.
dest_…).For PIX (Brazil, BRL), create a
bank_account destination with country = BR, payment_methods = ["pix"], and supply only a pix_key — no account number, routing details, or IBAN are needed. The key is returned masked as pix_key_masked.