> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payment Destination

> Add a bank account to a beneficiary

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_…`).

| Enum             | Values                                            |
| ---------------- | ------------------------------------------------- |
| `type`           | `bank_account`                                    |
| `status`         | `active`, `pending`, `disabled`                   |
| `payment_method` | `wire`, `ach`, `fedwire`, `spei`, `pix`, `manual` |

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

<ParamField path="account_id" type="string" required>
  Id of the parent account (e.g. `acct_...`).
</ParamField>

<ParamField path="beneficiary_id" type="string" required>
  Beneficiary id (e.g. `bene_…`).
</ParamField>

## Request Body

<ParamField body="country" type="string" required>
  ISO 3166-1 alpha-2 payment country code.
</ParamField>

<ParamField body="type" type="enum" required>
  Destination type. Always `bank_account`.
</ParamField>

<ParamField body="currency" type="enum" required>
  Currency this destination receives.
</ParamField>

<ParamField body="label" type="string | null">
  Free-text label for display purposes.
</ParamField>

<ParamField body="account_number" type="string | null">
  Max 255 characters. **Conditional**: required for `bank_account` (except PIX destinations). For `country` = `MX` this must be an 18-digit CLABE.
</ParamField>

<ParamField body="account_name" type="string | null">
  Max 255 characters. **Conditional**: required for `bank_account`.
</ParamField>

<ParamField body="account_type" type="string | null">
  Max 50 characters (e.g. `checking`, `savings`). **Conditional**: required for `bank_account`.
</ParamField>

<ParamField body="pix_key" type="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"]`.
</ParamField>

<ParamField body="routing_number" type="string | null">
  Max 100 characters.
</ParamField>

<ParamField body="iban" type="string | null">
  Max 34 characters.
</ParamField>

<ParamField body="swift_code" type="string | null">
  Max 11 characters.
</ParamField>

<ParamField body="is_default" type="boolean" default="false">
  Marks this as the beneficiary's default destination. Defaults to `false`.
</ParamField>

<ParamField body="bank_name" type="string | null">
  Max 255 characters.
</ParamField>

<ParamField body="bank_address" type="Address | null">
  Bank address object.

  <Expandable title="child attributes">
    <ParamField body="address_line" type="string" required>
      Street address.
    </ParamField>

    <ParamField body="city" type="string" required>
      Max 100 characters.
    </ParamField>

    <ParamField body="region" type="string" required>
      State / province / region. Max 100 characters.
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Max 20 characters.
    </ParamField>

    <ParamField body="country" type="string" required>
      Country code string. Send an ISO 3166-1 alpha-2 value; the shared Address schema does not enforce its length.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="correspondent_bank_name" type="string | null">
  Max 255 characters.
</ParamField>

<ParamField body="correspondent_bank_address" type="Address | null">
  Correspondent bank address (same shape as `bank_address`).
</ParamField>

<ParamField body="correspondent_bank_swift" type="string | null">
  Max 11 characters.
</ParamField>

<ParamField body="account_holder" type="string | null">
  Max 255 characters.
</ParamField>

<ParamField body="payment_methods" type="array | null">
  Payment methods this destination supports: `wire`, `ach`, `fedwire`, `spei`, `pix`, `manual`.
</ParamField>

## Response

Returns 200 with the new destination's `id`. Use Get Payment Destination to retrieve the full (masked) object.

<ResponseField name="id" type="string">
  Id of the newly created payment destination (e.g. `dest_…`).
</ResponseField>

<Note>
  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`.
</Note>

<RequestExample>
  ```json Request theme={null}
  {
    "country": "GB",
    "type": "bank_account",
    "currency": "GBP",
    "label": "Globex GBP",
    "account_name": "Globex Limited",
    "account_number": "31926819",
    "account_type": "checking",
    "iban": "GB29NWBK60161331926819",
    "swift_code": "NWBKGB2L",
    "is_default": true
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "dest_8kpw2x7a3b9c1e5f2d4g6h8j"
  }
  ```
</ResponseExample>