Skip to main content

​
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 user, the Add Bank Account API allows you to do so. This endpoint requires the user_uuid of an onboarded person, business, or merchant, which you will include as a path parameter in your request.

​
What You’ll Need

To add a bank account, you’ll need: For Manual Account Entry:
  • The user_uuid of an existing person, business, or merchant
  • The bank account details:
  • account_number
  • routing_number
  • account_type (checking or savings)
  • account_name
When Using Plaid:
  • The user_uuid of an existing person, business, or merchant
  • A valid access_token obtained from the Plaid Link flow
  • The account_id corresponding to the selected bank account
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 user_uuid from onboarding or retrieving it from your backend after onboarding to use the SDK to add a bank account to an existing user.

​
Step 1: Determine the Target User

Before you can add a bank account, you must have successfully onboarded a user and obtained their unique user_uuid. This can be from a Person, Business, or Merchant record. For more details on onboarding:

​
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

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.
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: 
{
    "actions": {
        "account_intelligence": {
            "version": "v3",
            "name_match": true
        }
    }
}
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

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_user_uuid in your request.

​
Billing Attribution

Field: billing_merchant_user_uuid Description: UUID of a merchant-associated user for billing tracking. 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, replacing {uuid} with the target person’s UUID: 
POST /api/v3/people/{uuid}/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 [email protected].