# Add Bank Account

## Overview

Bank accounts are a core part of ACH transactions in the GrailPay ecosystem. Each transaction involves a **payer**
and **payee**, both of whom must have active, valid bank accounts connected to the application.

If a bank account was not added during initial onboarding (via the registration API), or if you need to attach a new
bank account to an existing entity, the **Add Bank Account** API allows you to do so. This endpoint requires the
`uuid` of an onboarded **person** or **business**, which you send as `entity_uuid` in the body of
your request.

---

## What You'll Need

To add a bank account, you’ll need:

For Manual Account Entry:

- The `uuid` of an existing **person** or **business**, sent as `entity_uuid`
- The bank account details:
- `account_number`
- `routing_number`
- `account_type` (`checking` or `savings`)
- `account_name`

When Using Plaid:

- The `uuid` of an existing **person** or **business**, sent as `entity_uuid`
- A valid `access_token` obtained from the Plaid Link flow
- The `account_id` corresponding to the selected bank account

:::note
You also can use the [Bank Link SDK](/docs/technical/bank-link-sdk/overview) to streamline the process of adding
bank accounts.  You will need to make sure you are either storing the entity's `uuid` from onboarding or retrieving it
from your backend after onboarding to use the SDK to add a bank account to an existing entity.
:::

---

## Step 1: Determine the Target Entity

Before you can add a bank account, you must have successfully onboarded the entity and obtained its `uuid`.
This can be a **Person** or **Business** record, and the value goes in the request as `entity_uuid`.

For more details on onboarding:

- [Onboard a Person](/docs/technical/users/onboard-a-person)
- [Onboard a Business](/docs/technical/users/onboard-a-business)

---

## Step 2: Prepare Bank Account Details

You’ll need to collect the following information from the user:

- **Account Number** – A 12-digit bank account number.
- **Routing Number** – A valid 9-digit ABA routing number.
- **Account Type** – Either `checking` or `savings`.
- **Account Name** – A user-facing name or label for this account (e.g., "Main Checking").

---

## Step 3: Enable Account & Routing Validation

:::note
Enabling account and routing validation at the time of adding a bank account is optional, but strongly recommended
to help fight fraud and general payment failures.
:::

#### Real-Time Validation (Recommended)

To reduce fraud risk and ensure funds can be successfully routed, we recommend enabling real-time bank account validation
during onboarding. This feature is powered by our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence) product,
which provides intelligent validation of routing and account numbers at the time of submission.

To enable this, include an actions object in your onboarding request:

```json title="Success (200)"
{
    "actions": {
        "account_intelligence": {
            "version": "v3",
            "name_match": true
        }
    }
}
```

:::note
Please note that the Name Match functionality is only available when using V3 of Account Intelligence
:::

This validation step confirms that the provided routing and account numbers are both valid and correctly formatted. If
name_match is enabled, it also checks that the account holder’s name aligns with the expected identity. In addition to
these checks, the response includes a **Risk Score** and a set of decisioning insights that explain how the account was
evaluated.

To understand the full structure of the response and how to interpret the results, refer to
our [Account Intelligence](/docs/risk/bank-accounts/account-intelligence#response-attributes) documentation.

Although optional, enabling this validation is strongly recommended for all production integrations to reduce failure
rates and improve payout reliability.


---

## Step 4: Attribute Billing to a Merchant

:::note
Associating a call to add a bank account with a merchant for billing is not required, but it is strongly recommended if your
integration supports it, as this allows your team to better track usage for monitoring and billing purposes.
:::

If your integration supports **merchant-level billing attribution**, you can associate the bank account creation with a
merchant by passing the `billing_merchant_uuid` in your request.

### Billing Attribution

**Field:** `billing_merchant_uuid`
**Description:** UUID of the merchant that should receive billing attribution.

This enables detailed cost attribution across your ecosystem and simplifies billing audits.

---

## Step 5: Make the API Call

To add a bank account, make a `POST` request to the following endpoint, with `entity_uuid` identifying the entity and the
account details under `bank_account`:

```
POST /api/v3/bank-accounts
```

For full schema details, refer to
the [Add Bank Account Endpoint](/api/payments/#tag/bank-accounts/POST/api/v3/bank-accounts)
in our OpenAPI docs.

---

## Testing

For guidance on testing in Sandbox, see our [Technical Overview](/docs/technical/overview#testing) guide.

---

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com). 

---