Skip to main content

​
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
  • Performing name matching verification against account holder information

​
Account Intelligence Versions

The response payload varies depending on which version of account intelligence you select. We recommend using V3 for the most comprehensive validation insights.
V1 Deprecation Notice: Version 1 account intelligence is deprecated and will be removed in a future release. Please migrate to V3 for enhanced decisioning insights.
V3 provides comprehensive decisioning insights including transaction history, name matching, and duplicate detection. For complete request and response schema, refer to:
To enable name matching, set name_match: true in the actions.account_intelligence object of your request payload. When name matching is enabled, the person object with first_name and last_name is required. If you are not using name matching, the person object is optional.

​
V3 Response Fields

To learn more about our V3 Response fields, refer to the Account Intelligence V3 Documentation.

​
Version 2

V2 returns a confidence score with a human-readable confidence level. 
{
  "account_intelligence": {
    "confidence_score": 0.81,
    "confidence_level": "very high",
    "version": "v2"
  }
}

​
V2 Response Fields

FieldTypeDescription
confidence_scoredecimalOverall confidence score (0.0 - 1.0)
confidence_levelstringHuman-readable confidence level (e.g., very high, high, medium, low)

​
Version 1 (Deprecated)

V1 is deprecated. Please migrate to V3.
V1 returns a simple validity status. 
{
  "account_intelligence": {
    "validity": "valid",
    "version": "v1"
  }
}

​
V1 Response Fields

FieldTypeDescription
validitystringValidation result: valid, invalid, or not_validated

​
Testing

You can test the validation endpoint in our Sandbox Environment. Use the following test routing numbers to simulate different validation outcomes: 
{
    "account_number": "1234567890",
    "routing_number": "100000001"
}

​
Next Steps

After successful validation, 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: