On This Page

Visa Bank Account Validation Merchant Guide

This section describes how to use this guide and where to find further information.
Audience and Purpose
This guide is written for merchants who want to implement the Visa Bank Account Validation product with the
REST API
.
This product is currently in the Pilot phase, and this guide is only for the Pilot launch of the product.
Prohibited Uses
Merchants are prohibited from using the Visa Bank Account Validation (1) alone or in connection with other data or information, to determine a consumer's eligibility for products, services, credit, insurance, housing or employment, and/or engage in any other actions that could give rise to adverse action requirements under the US Fair Credit Reporting Act, the Equal Credit Opportunity Act, and/or other similar federal, state, or local regulations; (2) alone or in connection with other data or information, in any way that would cause Visa or Cybersource to be a “consumer reporting agency”; or (3) alone or in connection with other data or information, to discriminate based on race, gender, or other protected characteristics.
Conventions
These statements appear in this document:
IMPORTANT
An
Important
 statement contains information essential to successfully completing a task or learning a concept.
WARNING
A
Warning
 contains information or instructions, which, if not heeded, can result in a security risk, irreversible loss of data, or significant cost in time or revenue or both.
Related Documentation
Visit the
Cybersource
 documentation hub to find additional technical documentation.
Customer Support
For support information about any service, visit the Support Center:

Pilot Release

This document provides information about the pilot release of Visa Bank Account Validation.

Recent Revisions to This Document

25.11.01

Enhanced Search Information
Added information on how to search for account validation transactions. For more information, see Transaction Search and Transaction Details.
Enhanced Reporting
Added information on how to include account validation transactions in the Transaction Request Report. For more information, see Reporting.
Editorial updates were made throughout the guide.

25.06.01

This revision contains only editorial changes and no technical updates.

25.05.01

This revision contains only editorial changes and no technical updates.

25.04.01

Initial release.

Introduction to Visa Bank Account Validation

Cybersource
 offers the Visa Bank Account Validation product, which helps you validate your customer's bank account for Automated Clearing House (ACH) transactions. This product also helps you comply with the National Automated Clearing House Association (Nacha) Web Debit Account Validation Rule for ACH web transactions.
This product helps reduce the number of administrative returns, enhances the security and reliability of ACH transactions, and protects your business from the costly repercussions of invalid ACH transactions.
The Visa Bank Account Validation product validates both the routing and bank account number. The responses on this validation will let you know whether the customer's account is validated, not validated, low risk, medium risk, or high risk for processing ACH transactions.

Requirements for Visa Bank Account Validation

In the US, Visa Bank Account Validation enables you to validate your customer's bank accounts for ACH transactions. Before you can start using it, you must meet these requirements:
  • Verify that you have the capability to use the REST API.
  • Contact the
    Cybersource
     sales team or your contracting partner to request onboarding for the Visa Bank Account Validation product.
  • Sign a Pilot/Beta agreement with
    Cybersource
     or your partner.
  • Generate a
    REST
     key P12 certificate for your merchant ID (MID) so that you can send requests. For more information, see Generating a P12 Certificate.
  • Enable Message-Level Encryption (MLE) so that you can send API requests to
    Cybersource
    . For more information, see Enabling Message-Level Encryption.

Generating a P12 Certificate

You can use this validation product only through a REST API integration.
You must create a
REST
 key for your merchant ID. If you already have a
REST
 key for other
Cybersource
REST
 services with the same merchant ID, you can use that key to access the Visa Bank Account Validation Service. Ensure that the key is a P12 certificate. For more details, see Create a P12 Certificate.

Enabling Message-Level Encryption

You must enable Message-Level Encryption (MLE) to send Visa Bank Account Validation API requests to
Cybersource
. For more information, see Enable Message-Level Encryption.

Visa Bank Account Validation

This section shows you how to process an account validation.

Validating a Bank Account Using
REST

Follow these steps to request a bank account validation:
  1. Create a request with the required and any optional REST API fields. Refer to the request and response examples, if needed.
  2. Send the completed request to one of these endpoints:
  3. Verify the response messages to make sure that the request succeeded. For more information, see the Transaction response codes.

Required Fields for Validating an Account

The value for this field must be set to
1
.
The value for this field must be the routing number for your customer’s bank. This field accepts only non-negative integers.
The value for this field must be the bank account number for your customer's bank account. This field accepts only non-negative integers.

Optional Fields for Validating an Account

The value for this field can include any reference code that you choose to associate with the validation request. This code is returned in the response exactly as provided.

REST Example: Validating an Account

Request
{
    "clientReferenceInformation": {
        "code": "TC50171_3"
    },
    "processingInformation": {
        "validationLevel": 1
            },
    "paymentInformation": {
        "bank": {
            "routingNumber": "041210163",
            "account": {
                "number": "1234567"
            }
        }
    }
}
Response to a Successful Request
{
    "clientReferenceInformation": {
       "code": "TC50171_3"
    },
    "requestId": "string",
    "submitTimeUtc": "string",
    "bankAccountValidation": {
        "rawValidationCode": 0,
        "resultCode": 0,
        "resultMessage": "string"
    }
}
Response to an Unsuccessful Request
{
    "submitTimeUtc": "string",
    "status": "string",
    "message": "string",
    "reason": "string",
    "details": [
        {
            "field": "string",
            "reason": "string"
        }
    ]
}

Response to a Successful Request

You receive these fields in a successful response. These fields track and reference your validation requests:
  • clientReferenceInformation.code
    : This field appears when you include it in the request. It holds any reference code you want to associate with the specific validation request. The code returns in the response exactly as you provide it.
  • requestID
    : This unique ID identifies the validation request and can be used for future reference. You can use this request ID to search for the validation request in the Transaction Search module.
  • submitTimeUtc
    : This field records the timestamp of the validation request.
  • bankAccountValidation
    : Refer to the API response codes table to understand the possible codes.

API Response Codes for a Successful Request

You can receive these response code values from
rawValidationCode
,
resultCode
, and
resultMessage
:
Values Returned for Successful Responses
Raw Validation Code
Result Code
Result Message
12
00
Validated
13
00
Low risk
14
00
Medium risk
15
04
High risk
16
04
Not validated
-1
98
Unable to perform validation; no information found.
-2
99
Service unavailable
Result Message Explanation
Result Code
Explanation
Validated
Account is in good standing.
Low risk
Some positive data is available for the account, and no negative information was found.
Medium risk
New account for which there is no negative information.
High risk
One or more information points indicate that there is an extremely low probability of payment from this account.
Not validated
Account closing or closed.
Result Code Explanation
Result Code
Explanation
00
Validated
04
Not validated
98
Unable to perform validation; no information found.
99
Service unavailable

Response to an Unsuccessful Request

It is important to understand the fields that are contained in a response to an unsuccessful request. These fields provide information to help you identify and resolve unsuccessful requests.
The response to an unsuccessful request contains these fields:
  • v-c-correlationid
    : The response header includes a unique identifier for this validation request.
  • submitTimeUtc
    : The timestamp of the validation request. The format is YYYY-MM-DDThhmmssZ.
  • message
    : The detailed message related to the status and reason for the response.
For more information about response codes, visit the Transaction response codes page.

HTTP Status Codes for an Unsuccessful Request

These are the possible values you can receive for a status, reason, and details block depending on the HTTP status code:
HTTP Status Codes
HTTP Status Code
(part of HTTP header)
Status
Reason
Details (an array with 0 to many blocks)
400
INVALID_REQUEST
INVALID_REQUEST
Field contains the name of the field that is missing or incorrect:
Reason – MISSING_FIELD, INVALID_DATA
403
UNAUTHORIZED
UNAUTHORIZED
—
404
NOT_FOUND
NOT_FOUND
—
422
VALIDATION_ERROR
PRODUCT_INACTIVE
INVALID_MERCHANT_CONFIGURATION
PRODUCT_NOT_CONFIGURED
—
502
SERVER_ERROR
SYSTEM_ERROR
SERVER_TIMEOUT
SERVICE_TIMEOUT
—

Reference Information

You can search for transaction validations in the
Business Center
 using the request ID or by using the REST API.

Viewing a Transaction in
Business Center

The details of a bank account validation transaction are available in the
Business Center
. From the Transaction Management module, you can view and examine in detail any of the transactions you process.

Transaction Search

You can use the Transactions page in the
Business Center
 to search for transactions processed by your account or the account of one or more of your merchants in your portfolio. The Transactions page displays details for each transaction matching your search criteria. Use the search toolbar to limit the results and apply filters to refine which transactions are returned. Your search can include up to 13 months of transactions.
Follow these steps to search your transactions:
  1. In the left navigation panel, choose the
    Transaction Management > Transactions
    .
  2. In the search toolbar, click the
    Date Range
     filter and choose an option.
  3. Click
    Add filter
    . A
    New Filter
     drop-down menu appears.
  4. Click the down arrow to view a list of filter options. Browse the list or start typing
    application
     in the filter field.
  5. Click
    Application
     to create an Application filter.
  6. In the
    Application
     filter field, start typing
    bank
     and click
    Bank Account Validation
     when it appears. (You can save this filter for future searches by clicking the arrow in the
    Actions
     field and choosing
    Save New
    .)
  7. Click
    Search
    . The result of the search appears in the Search Results section.

Figure:

Bank Account Validation filter

Transaction Details

On the Transaction Details page, you can view information about bank account validation, but the page must be configured to display the details. You must add a card to the page as a place for the bank account validation details to appear.
  1. In the left navigation panel, choose the
    Transaction Management > Transactions
    .
  2. In the search toolbar, use the filters to list the bank account validations. For information about creating a bank account validation filter, see Bank Account Validation filter.
  3. Click the request ID of one of the listed transactions to display the Transaction Details page for that transaction.
  4. Click the
    Actions
     drop-down menu at the top of the page and choose
    Edit Layout > Add Card > Bank Account Validation
    . A Bank Account Validation Service card appears on the Transaction Details page.

Figure:

Transaction Details Page Showing Bank Account Validation Card
Transaction Details page showing Bank Account Validation card
IMPORTANT
For transaction details, the Bank Account Validation card is created only once. After you create and save the card, the Transaction Management module saves your preference and provides it for future transactions.

Reporting

The Account Validation requests are available in the Transaction Request Report (TRR) standard report. For more information about the TRR, see the
Reporting User Guide
.
To help merchants view validation responses for transactions, four new fields are available in the TRR report:
  • RawValidationCode
  • ResultCode
  • ValidationLevel
  • ValidationMessage

Testing Data

You can use the data below to test each validation result in the sandbox environment.
Validation Mode Examples
Routing Number
Account Number
Raw Validation Code
Result Code
111000614
99970
12
00
111000614
99971
13
00
111000614
99973
14
00
111000614
99915
15
04
111000614
99941
16
04
111000614
99950
-1
98
111000614
99980
-2
99