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 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
• 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 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:

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 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 in our OpenAPI docs.

---

Testing

For guidance on testing in Sandbox, see our Technical Overview guide.

---

Questions?

If you’re encountering any issues, please reach out to support@grailpay.com.

---