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.

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.

These are versions of the Account Intelligence service, chosen per request with actions.account_intelligence.version. They are unrelated to the Payments API version, which is v3 for every endpoint on this site.

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

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.

{
  "status": true,
  "message": "Validation processed successfully",
  "data": {
    "account_intelligence": {
      "confidence_score": 0.81,
      "confidence_level": "very high",
      "version": "v2"
    }
  },
  "errors": null,
  "request_id": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2"
}

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 returns a simple validity status.

{
  "status": true,
  "message": "Validation processed successfully",
  "data": {
    "account_intelligence": {
      "validity": "valid",
      "version": "v1"
    }
  },
  "errors": null,
  "request_id": "2d6a4c39-8fcf-4d80-9189-b4764eac31f2"
}

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. The sandbox reserves a set of routing numbers that each return a fixed validation outcome, letting you build against every result.

When using V3 as the Account Intelligence version, the sandbox test routing numbers and the exact values each one returns are documented in full on the Account Intelligence page. Refer there for the complete V3 testing reference.

A quick summary of the primary routing numbers:

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

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

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

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

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

Maintained by EkLine