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

# External bank addresses

> Two paths for creating external off-chain bank addresses: Plaid-linked bank account and Direct bank entry.

Brale supports two paths for creating an external off-chain bank address, each unlocking different transfer types.

When you create an external bank address, the path you choose determines which `transfer_types` are available for that address. Choose the right path based on the transfer rails you need.

## Comparison

| Capability | Plaid-linked bank account | Direct bank entry |
| - | - | - |
| `ach_debit` | Supported | Not supported |
| `ach_credit` | Supported | Supported |
| `rtp_credit` | Supported | Supported |
| `fednow_credit` | Supported | Supported |
| `wire` | Not supported | Supported |
| Balance lookup | Supported (`USD` only) | Not supported |

> [!WARNING]
>
> **ACH debit** is only available through the **Plaid-linked bank account**
> flow. You cannot enable `ach_debit` via Direct bank entry.

> [!WARNING]
>
> **Wire** is only available through the **Direct bank entry** flow. You cannot
> enable `wire` via the Plaid-linked bank account flow.

## Which path should you use?

* **Plaid-linked bank account** — Use this when you need `ach_debit` or want to provide a Plaid bank-linking experience for your users. This flow uses Plaid Link to securely connect a bank account and supports `ach_debit`, `ach_credit`, `rtp_credit`, and `fednow_credit` (on accounts with FedNow enabled).
* **Direct bank entry** — Use this when you already have bank account details (account number, routing number) or need `wire` transfers. This flow supports `wire`, `ach_credit`, `same_day_ach_credit`, `rtp_credit`, and `fednow_credit` (on accounts with FedNow enabled).

To pay out over FedNow, include `fednow_credit` when you register the recipient with either path, or add it to an existing address. The recipient's routing number must participate in FedNow. See [Send FedNow payouts](https://docs.brale.xyz/guides/fednow-outbound.md).

## Direct bank entry field requirements

For Direct bank entry, required fields depend on the transfer types you request.

| Transfer type | Required bank details |
| - | - |
| `ach_credit` | `owner`, `account_number`, `routing_number`, `account_type`, `transfer_types` |
| `same_day_ach_credit` | `owner`, `account_number`, `routing_number`, `account_type`, `transfer_types` |
| `rtp_credit` | `owner`, `account_number`, `routing_number`, `account_type`, `transfer_types` |
| `fednow_credit` | `owner`, `account_number`, `routing_number`, `account_type`, `transfer_types` |
| `wire` | All of the above, plus `bank_address` and `beneficiary_address` |

If `transfer_types` includes `wire`, wire requirements apply, even if the same address also includes ACH, RTP, or FedNow rails. For addresses without `wire`, omit `bank_address` and `beneficiary_address` unless you have accurate values—do not enter placeholder or generic bank addresses.

## Account holder type

Both paths accept an optional `account_holder_type` (`"individual"` or `"business"`). Brale uses it to choose the ACH SEC code for payouts to the address: `individual` → PPD, `business` → CCD. If you omit it, Brale uses the entity type of the account that owns the address. For Plaid-linked accounts, the holder category reported by Plaid takes precedence when available. You can set it later with the [PATCH address endpoint](https://docs.brale.xyz/api-reference/brale/update-address.md) if it was not set at creation; once set, it cannot be changed.

## Plaid-linked bank account flow

This flow uses the Plaid Link SDK to securely connect a bank account in two steps:

1. [Create a Plaid link token](https://docs.brale.xyz/api-reference/brale/create-plaid-link-token.md) — Generate a `link_token` to launch Plaid Link in your front-end.
2. [Register the account via Plaid](https://docs.brale.xyz/api-reference/brale/register-financial-institution-account-via-plaid-and-return-address-id.md) — Exchange the `public_token` from Plaid to create an `address_id`.

For a full walkthrough, see [Key Concepts → Addresses → Create addresses through Plaid](https://docs.brale.xyz/key-concepts/addresses.md#create-addresses-through-plaid).

After registration, you can check the linked account's USD balance with `GET /accounts/{account_id}/addresses/{address_id}/balance?transfer_type=ach_debit&value_type=USD`. See [Get A Balance](https://docs.brale.xyz/guides/how-to/get-a-balance.md#plaid-linked-bank-balance).

## Direct bank entry flow

Submit bank account details directly using the Addresses API:

* [Create a new external address](https://docs.brale.xyz/api-reference/brale/create-address.md) — Addresses without `wire` require `owner`, `account_number`, `routing_number`, `account_type`, and `transfer_types`. Wire-capable addresses also require `bank_address` and `beneficiary_address`. This path supports `wire`, `ach_credit`, `same_day_ach_credit`, `rtp_credit`, and `fednow_credit`.

For examples, see [Key Concepts → Addresses → Create via Direct bank entry](https://docs.brale.xyz/key-concepts/addresses.md#create-via-direct-bank-entry).

### Validation

When you create a Direct bank entry address, Brale validates the format of the bank details. For example, Brale checks that the routing number is valid. Brale does not verify that the account exists, that it is open, or who owns it.

* **Bad account details surface after submission.** If the account number does not exist or cannot receive the payment, the receiving bank returns the ACH entry. For example, `R03` means no account was found or the account could not be located.
* **Returns arrive as `transfer.failed`.** Brale updates the transfer to `failed` and sends a [`transfer.failed`](https://docs.brale.xyz/webhooks/webhook-events#transfer-failed) webhook. Read the return code and reason from `failure.ach_return`. See [the transfer `failure` field](https://docs.brale.xyz/api-reference/brale/get-transfer#failure) for the full schema.
* **Returns can arrive late.** An ACH return can arrive after the transfer was already processed. Keep handling `transfer.failed` events for transfers you have already recorded. See [Transfer status lifecycle](https://docs.brale.xyz/documentation/platform/transfer-timing.md#transfer-status-lifecycle).

If you need the account confirmed before you send funds, use the [Plaid-linked bank account flow](#plaid-linked-bank-account-flow) instead. That flow connects the account through Plaid Link rather than accepting manually entered details.

## Archive and unarchive

If you need to stop using a previously linked external bank address without deleting the record, use the [PATCH address endpoint](https://docs.brale.xyz/api-reference/brale/update-address.md) to archive it. If the customer later wants to restore the same external address, unarchive it.

* Archive: `PATCH /accounts/{account_id}/addresses/{address_id}` with `{ "status": "archived" }`
* Unarchive: `PATCH /accounts/{account_id}/addresses/{address_id}` with `{ "status": "active" }`

Archive and unarchive apply only to external addresses. See [Address lifecycle](https://docs.brale.xyz/key-concepts/addresses.md#address-lifecycle) for details.