Validate Bank Accounts

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.

Version 3 (Recommended)

V3 provides comprehensive decisioning insights including transaction history, name matching, and duplicate detection.

For complete request and response schema, refer to:

• Validate Account & Routing V3

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

Field	Type	Description
confidence_score	decimal	Overall confidence score (0.0 - 1.0)
confidence_level	string	Human-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

Field	Type	Description
validity	string	Validation 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 when choosing v3 as the Account Intelligence version in the actions object of your request payload:

Low Risk ( valid account with name match )

{
    "account_number": "1234567890",
    "routing_number": "000000001"
}

Version 2 Testing

When using v2 as the Account Intelligence version in the actions object of your request payload, the same routing numbers can be used to simulate different validation outcomes. Version 2 responses include a confidence score and confidence level, but do not include the detailed insights provided in Version 3.

• 000000001 — High confidence score (e.g., 0.81) with a confidence level of very_high
• 000000002 — Medium confidence score (e.g., 0.65) with a confidence level of medium
• 000000003 — Low confidence score (e.g., 0.30) with a confidence level of low

Version 1 Testing

When using v1 as the Account Intelligence version in the actions object of your request payload, the same routing numbers can be used to simulate different validation outcomes. Version 1 responses only indicate whether the account is valid, invalid, or not_validated — no confidence score or level is provided.

• 000000001 — Returns valid
• 000000002 — Returns invalid
• 000000003 — Returns not_validated

---

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:

• Validate Account & Routing V3

---