Bank Account validation is a crucial aspect of a company’s risk assessment. Understanding their customers’ banking status will allow our Clients to significantly mitigate fraud and payment acceptance risk.

With credit cards, companies can authorize or decline a transaction based on the credit limit at the time of payment and can set aside funds to cover the payments. However, for ACH or electronic checks, we currently do not have an authorization process as with credit cards. And with ACH returns costing money to Companies, there is an urgent need for a solution that does bank and identity verification. This will also help ensure that the payments we push through will not be returned.

Bank Account Validation is available within EBPP as part of your bill pay setup. This function should not be used by EBPP Clients unless you need to validate bank accounts outside of your EBPP setup, and a separate license must be purchased to make use of this standalone service.

Overview

Here are the Authorization methods that are supported.

The HTTP Authorization request header is used to provide authentication information. This header looks like the following.

Authorization : OPAY1-HMAC-SHA256 Credential=...,Signature=...

The constituents of the authorization header are explained in the table below.

Signature Calculation

Signature is calculated as follows.

Base64(HMAC-SHA256(secret,input))

The calculation is explained in detail below.

The string input is computed as follows.

input = method():path():queryString():headers():payload()

Each of the substrings is explained below.

The HTTP Authorization request header is used to provide authentication information. This header looks like the following.

Authorization : OPAY2-HMAC-SHA256 Credential=...,Signature=...

The constituents of the authorization header are explained in the table below.

Signature Calculation

Signature is calculated as follows.

Base64(HMAC-SHA256(secret,input))

The calculation is explained in detail below.

The string input is computed as follows.

input = client_key:api_key:secret_key:timestamp

The HTTP Authorization request header is used to provide authentication information. This header looks like the following.

Authorization : OPAY3-HMAC-SHA256 Credential=...

The constituents of the authorization header are explained in the table below.

Account Validation uses standard HTTP response codes to return the status of an API call. Additional information, such as errors, may be useful to a caller. An HTTP response code of 2xx indicates success. In this case, additional information pertaining to the request is sent back in the header parameters. An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Account Validation also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable.)

Http Response Codes

An HTTP response code of 4xx indicates a client error and 5xx indicates a processing error. In these cases, Account Validation also returns a list of errors in the response body in JSON. Each error has a code, message, and specifics on which field the error pertains to (if applicable). The Account Validation API specific error codes are described here.

The set of rules that define the risk level and the recommended decision corresponding to each of the underlying reason codes returned by the provider. There are 3 standard rulesets available to the client. In addition to these, clients can define their own rulesets. The following list captures the default ruleset definition.

The code for the underlying reason that the account validation provider returns. This is available in the additional data section of the Account Validation API response. The following is the complete list of provider reason codes and the corresponding descriptions.

There are cases where Account Validation wants to indicate to the account holder that they could contact the underlying provider to enquire about the account validation response. This happens when Account Validation declines the account on the basis of certain reason codes that provider returns. The idea is to allow the consumer to contact the provider in order to give clarifications and possibly correct the account validation status for subsequent requests, if they disagree with the provider's response.

This can be used for storing additional or contextual information. Account Validation supports upto 5 metadata fields, namely, context_attr_1, context_attr_2, context_attr_3, context_attr_4 and context_attr_5.

We support idempotency for the HTTP methods POST, PUT, DELETE and PATCH using the header parameter, namely, idempotent_request_key.

In other words, any POST, PUT, DELETE and PATCH request will be considered as a duplicate request or retry and not reprocessed by Account Validation if all the request parameters, including the path and query parameters, the request headers (excluding the timestamp header) and the request body, match with an earlier request. In case of duplicate requests or retries, the API response will be that of the original request.The only exceptions to this are the Retrieve API even though they may use HTTP POST.

The idempotent_request_key is valid only for a duration of one hour from the time of the original request. Any duplicate request or retries after a gap of one hour from the original request will be considered as a fresh request and reprocessed by Account Validation.

Account Validation does not support retry of GET requests and these are processed every time, irrespective of the idempotent_request_key.