​
Overview

Before initiating a transaction or linking a manually entered bank account, it’s important to ensure the account and routing number combination is valid. GrailPay offers a dedicated endpoint that validates these details in real-time to reduce the risk of failed transactions and ACH returns. This validation is especially useful during onboarding or when updating a user’s financial information, as it helps ensure the account is active and properly formatted for ACH.
This endpoint only supports manually entered bank accounts. For accounts linked through Bank Link or Plaid, validation is handled as part of the linking process.

​
Use Cases

You might use this endpoint when:
  • Collecting account details via a custom onboarding form
  • Adding a bank account outside the registration flow
  • Verifying bank details before submitting a transaction
  • Implementing safeguards to reduce return-related fraud

​
Validation Results

The API will return one of the following values in the valid_account field:
ValueDescription
validThe account and routing number are valid.
invalidThe combination is invalid. Do not proceed with linking or transacting.
not_validatedValidation could not be completed. Proceed with caution.
If the validation fails (invalid), the API returns an HTTP 406 Not Acceptable response. This ensures downstream systems and user interfaces can handle failures programmatically.

​
Required Fields

To validate an account, include the following fields in your request payload:
  • account_number – The full 12-digit account number
  • routing_number – A 9-digit ABA routing number
  • account_type – Must be checking or savings

​
Next Steps

After successful validation (valid), you can proceed to Add the Bank Account to the user profile, or use the validated details to initiate a transaction. For complete request and response schema, refer to