​
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 the risk of failed transfers or ACH returns, you can request real-time validation of the bank account and routing number by including the validate_account_routing flag in your payload.

​
Validation Results

ResultDescription
validAccount was successfully validated and added.
invalidValidation failed. Account was not added. (HTTP 406)
not_validatedValidation service was unavailable. Account was added without confirmation.

​
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 {user_uuid} with the target user’s UUID: 
POST /3p/api/v1/bank-account/{user_uuid}
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, contact your GrailPay integration support contact or open a support request via the portal.