Skip to main content
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 — three cases:
  • payment_methods is exactly ["pix"]: do not send it. A PIX-only destination carries pix_key alone; sending account_number, iban, routing_number or swift_code returns 422.
  • payment_methods mixes PIX with another rail (e.g. ["pix", "wire"]): required, alongside pix_key — the non-PIX rail still needs full bank details.
  • Any other rail: required.
For country = MX this must be an 18-digit CLABE.
​
string | null
Max 35 characters — the limit partner banks impose on this field, so a longer name is rejected here rather than at payment time. 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 whenever payment_methods includes pix. For a PIX-only destination it is the only identifier you send, and currency must be BRL and country must be BR — both are enforced with a 422.
​
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. Note the field is plural — unknown fields (including the singular payment_method) are rejected with 422 rather than ignored.

​
Response

Returns 200 with the new destination’s id. 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.