Bank Account Verification API

Learn more about the Bank Account Verification API.

Guidelines

Below are the steps you must be aware of while calling Bank Account Verification APIs:

  • All API responses are in JSON format.

  • POST Requests should include ContentType: application/json

  • All API response has status, subCode, message, and data.

  • Subcode is the status subcode of the response-All requests to Cashfree that are processed by the server return HTTP 200. Use the status flag to determine if the request was successfully processed. Check the error subcodes here.

  • Certain APIs support pagination. If an API does support pagination, Cashfree does not return more than 10 items per request. Pass the lastReturnId if received as a part of the response to continue fetching. If lastReturnId is not present, no further item exists.

It is strongly recommended to scan error sub-code and not error messages.

Postman collection

Get started quickly with Cashfree payouts APIs by downloading the following collection and importing it in Postman.

Host URL

Use the following host URLs based on your specific environment.

Environment

Host URL

Test

​https://payout-gamma.cashfree.com​

Prod

​https://payout-api.cashfree.com​

Authentication

Calling the Authentication APIs allows you to get and verify bearer tokens returned by Cashfree. Cashfree require these token for all further communication.

Cashfree libraries automatically call the Authorize API and internally store the token.

Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP.

Token generated is valid for 300 seconds. Please ensure that you recall the authorize API once the token has expired.

Ensure your IP is whitelisted to find out how to whitelist your IP or if you have a dynamic IP, take a look here.

post
Authorize

/payout/v1/authorize
To authenticate with the Cashfree system and obtain the authorization bearer token, call the authorize API. All other API calls must have this token as Authorization header in the format 'Bearer <token>' (without quotes) for them to get processed.
Request
Response
Request
Headers
X-Cf-Signature
optional
string
Signature to be sent if IP is not whitelisted
X-Client-Secret
required
string
ClientSecret
X-Client-Id
required
string
ClientId
Response
200: OK
{"status":"SUCCESS",
"message":"Token generated",
"subCode":"200",
"data": {"token":"eyJ0eXA...fWStg",
"expiry":1564130052}}
401: Unauthorized
{"status":"ERROR",
"message":"Invalid clientId and clientSecret combination",
"subCode":"401"}
Curl
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/authorize' \
-H 'X-Client-Id: {{client id}}' \
-H 'X-Client-Secret: {{client secret}}' \

Cashfree libraries store the token internally and have their internal verification logic. This API does not apply to them.

post
Verify token

/payout/v1/verifyToken
Verify the bearer token generated. If the token does not exist, is invalid, or has expired, the response "Token is not valid" is returned. Regenerate token incase of token expiry for making API calls ( use /payout/v1/authorize for this)
Request
Response
Request
Headers
Authorization
required
string
Bearer token to be verified
Response
200: OK
{"status":"SUCCESS",
"message":"Token is valid",
"subCode":"200"}
403: Forbidden
{"status":"ERROR",
"subCode":"403",
"message":"Token is not valid"}
Curl
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/verifyToken' \
-H 'Authorization: Bearer {{Token}}' \

Verification

​

Verify bank account Ids and UPI Ids individually or in bulk.

Node
Python
Java
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
//Validation validation = new Validation(payouts);

get
Bank verification sync

/payout/v1/validation/bankDetails
Verify a bank account and IFSC combination. This is a sync verification request. The operation returns a success response in two cases: 1. The bank account or IFSC or both are invalid. 2. The bank account and IFSC combination are verified. Additionally, if a request is made again using the same bank account details while the previous request is already being processed you will get response stating that the request is in process along with the refId. To fetch the status of such request you can use the Get Verification Status API, by passing the refId as bvRefId.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
name
required
string
Name of the persons account to be validated, only alphanumeric and white spaces (100 character limit)
phone
required
string
Phone number
bankAccount
required
string
Bank account to be validated (6 to 40 character limit)
ifsc
required
string
IFSC of the bank account to be validated (standard IFSC format) - length 11, first four bank IFSC and 5th 0
Response
200: OK
{
"status": "SUCCESS",
"subCode": "200",
"message": "Amount Deposited Successfully",
"data": {
"nameAtBank": "John Doe",
"accountExists": "YES",
"amountDeposited": "1.28",
"refId": "123456"
}
}
​
{
"status": "SUCCESS",
"subCode": "200",
"message": "Invalid ifsc provided",
"data": {
"accountExists": "NO"
}
}
​
In case of validation being processed
​
{
"status": "SUCCESS",
"subCode": "202",
"message": "Validation in process check after some time"
"data": {
"refId": "123456"
}
}
422: Unprocessable Entity
{
"status": "ERROR",
"subCode": "422",
"message": "Please provide a valid IFSC code"
}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Amount Deposited Successfully

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

422

Please provide a valid name

ERROR

422

Please provide a valid bank account

ERROR

422

Please provide a valid IFSC code

ERROR

422

Please provide a valid phone number

ERROR

412

Insufficient balance to process this request

ERROR

400

Service temporarily unavailable. Please try again later

ERROR

422

Invalid ifsc provided

ERROR

422

Invalid bank account number or ifsc provided

ERROR

520

Could not verify bank account details

ERROR

520

Something went wrong

ERROR

520

Unknown error occurred

ERROR

520

Validation attempt failed

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.ValidateBankDetails({
name: "John Doe",
phone: "9876543210",
bankAccount: "026291800001191",
ifsc: "YESB0000262"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
v_det = Validations.bank_details_validation(name="JOHN", phone="9876543210", bankAccount="026291800001191",ifsc="YESB0000262")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Validation validation = new Validation(payouts);
validation.validateBankDetails(
"JOHN", "9876543210", "026291800001191", "YESB0000262"));
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/validation/bankDetails?name=John&phone=9876543210&bankAccount=026291800001191&ifsc=YESB0000262' \
-H 'Authorization: Bearer {{Token}}'

get
Bank verification async

/payout/v1/asyncValidation/bankDetails
Verify a bank account and IFSC combination. This is an async verification request. The operation returns a success response in two cases: 1. The bank account or IFSC or both are invalid. 2. The bank account and IFSC combination are verified. Benefits: 1. The API response is much faster for the async BAV endpoint. The async BAV response takes <100 ms as compared to a median value of 2-5 sec for the sync API. 2. The asynchronous API can handle a higher TPM (transactions per minute) as compared to the synchronous API. The async API allows us to handle up to 1000 transactions per minute. 3. You need to call the getValidationStatus API, to get the final status.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
userId
optional
string
A unique Id to identify Bank verification user, alphanumeric and underscore (_) allowed (40 character limit)
name
required
string
Name of the persons account to be validated, only alphanumeric and white spaces (100 character limit)
phone
required
string
Phone number
bankAccount
required
string
Bank account to be validated (6 to 40 character limit)
ifsc
required
string
IFSC of the bank account to be validated (standard IFSC format) - length 11, first four bank IFSC and 5th 0
Response
200: OK
In case of UserId not provided in the request
​
{
"status": "SUCCESS",
"subCode": "200",
"message": "Validation request accepted successfully",
"data": {
"bvRefId": "123456"
}
}
​
In case of UserId provided in the request
​
{
"status": "SUCCESS",
"subCode": "200",
"message": "Validation request accepted successfully",
"data": {
"userId": "user1234"
}
}
422: Unprocessable Entity
{
"status": "ERROR",
"subCode": "422",
"message": "Please provide a valid IFSC code"
}
​
If Invalid format of userId
​
{
"status": "ERROR",
"subCode": "422",
"message": "userId can contain only aphabets , numbers and underscore"
}
​
If same userId used again
​
{
"status": "ERROR",
"subCode": "409",
"message": "userId already exists"
}
​
{
"status": "ERROR",
"subCode": "520",
"message": "Validation attempt failed"
}

Response Codes

Staus

Sub Code

Message

SUCCESS

200

Request Accepted

ERROR

422

Input not in expected format

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.ValidateBankDetails({
name: "John Doe",
phone: "9876543210",
bankAccount: "026291800001191",
ifsc: "YESB0000262"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
v_det = Validations.bank_details_validation(name="JOHN", phone="9876543210", bankAccount="026291800001191",ifsc="YESB0000262")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Validation validation = new Validation(payouts);
validation.validateBankDetails(
"JOHN", "9876543210", "026291800001191", "YESB0000262"));
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/asyncValidation/bankDetails?name=John&phone=9876543210&bankAccount=026291800001191&ifsc=YESB0000262' \
-H 'Authorization: Bearer {{Token}}'

get
Get verification status

/payout/v1/getValidationStatus/bank
Get the statuses of the bank validation request by providing the bvRefId or userId.
Request
Response
Request
Query Parameters
bvRefId
required
string
Bank verification reference id
userId
optional
string
Bank verification user id
Response
200: OK
Response with bvRefId in request
​
{
"status": "SUCCESS",
"subCode": "200",
"message": "Bank Account details verified successfully.",
"data": {
"bvRefId": "123456",
"nameAtBank": "John Doe",
"accountExists": "YES",
"amountDeposited": "1.60",
"bankAccount": "026291800001191",
"ifsc": "YESB0000262",
"utr": "012341234123"
}
}
​
Response with userId in request
​
{
"status": "SUCCESS",
"subCode": "200",
"message": "Bank Account details verified successfully.",
"data": {
"userId": "user1234",
"nameAtBank": "John Doe",
"accountExists": "YES",
"amountDeposited": "1.60",
"bankAccount": "026291800001191",
"ifsc": "YESB0000262",
"utr": "012341234123"
}
}
​
In case of validation being processed
​
{
"status": "SUCCESS",
"subCode": "202",
"message": "Validation in process check after some time"
}
422: Unprocessable Entity
If none of the parameters are given
{
"status": "ERROR",
"subCode": "422",
"message": "Either bvRefId or userId should be provided in the request"
}
​
if both are given in the request
{
"status": "ERROR",
"subCode": "422",
"message": "Either one of bvRefId or userId should be provided in the request"
}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Successful Bank validation

ERROR

404

No such BV reference Id

ERROR

520

Bank Account Validation Failed

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.GetValidationStatus({
bvRefId: "123456",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
status = Validations.get_bank_validation_status(bvRefId="123456")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.ValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Validation validation = new Validation(payouts);
validation.getValidationStatus(bvRefId, null, null);
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/getValidationStatus/bank?bvRefId=123456' \
-H 'Authorization: Bearer {{Token}}'

get
UPI verification

/payout/v1/validation/upiDetails
Verify whether a UPI handle exists. You receive a customer name at the bank in the response for valid UPIs.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
name
required
string
name of the account to be validated, only alphabets and white space (100 character limit)
vpa
required
string
VPA of account to be validated, alphanumeric, period (.), hyphen (-), at sign (@) and underscore (_) allowed (100 character limit) Note: Underscore (_) and dot (.) gets accepted before and after at sign (@), but hyphen (-) get accepted only before the at sign (@)
Response
200: OK
{ "status": 1,
"subCode": "200",
"message": "VPA verification successful",
"data": { "nameAtBank": "JANE DOE", "accountExists": "Yes" } }
​
{ "status": 1,
"subCode": "200",
"message": "No Account linked with VPA",
"data": { "accountExists": "No"} }
​
422: Unprocessable Entity
{ "status": 0,
"subCode": "422",
"message": "Either VPA or name invalid"}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Amount Deposited Successfully

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

422

Please provide a valid name

ERROR

422

Please provide a valid UPI VPA

ERROR

422

Please provide a valid phone number

ERROR

412

Insufficient balance to process this request

ERROR

400

Service temporarily unavailable. Please try again later

ERROR

422

Invalid UPI VPA provided

ERROR

520

Could not verify bank account details

ERROR

520

Something went wrong

ERROR

520

Unknown error occurred

ERROR

520

Validation attempt failed

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.ValidateUPIDetails({
name: "John Doe"
vpa: "success@upi"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
upi_valid= Validations.upi_validation(name="John Doe", vpa="success@upi")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Validation validation = new Validation(payouts);
validation.validateBankDetails(
"JOHN", "9876543210", "026291800001191", "YESB0000262"));
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/validation/upiDetails?name=John&vpa=success@upi \
-H 'Authorization: Bearer {{Token}}'

post
Bulk bank verification

/payout/v1/bulkValidation/bankDetails
Request bank validations in bulk. It is an asynchronous process, call the get bulk verification API to get the result.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
bulkValidationId
required
string
Unique Identifier for the corresponding request, alphanumeric and underscore (_) allowed
entries
required
array
An array of bank account objects to be validated
Response
200: OK
Request body For Bank Account(Authorization Bearer token in header)
{ "bulkValidationId":"testid1",
"entries":[
{ "name":"John Doe",
"bankAccount":"026291800001191",
"ifsc":"YESB0000262",
"phone":"9876543210"},
{ "name":"Doe John",
"bankAccount":"0001001289877623",
"ifsc":"SBIN0008752",
"phone":"9876543210"}]}
​
Response
{"status": "SUCCESS",
"subCode": "200",
"message": "Bulk Validation requested successfully. Please check later for processing status.",
"data": { "bulkValidationId": "testid1" }}
409: Conflict
{"status": "ERROR",
"subCode": "409",
"message": "Bulk Validation Id already exists"}
422: Unprocessable Entity
{ "status": "ERROR",
"subCode": "422",
"message": "Mandatory Parameters missing in the request" }

Response Codes

Status

SubCode

Message

SUCCESS

200

Bulk Validation requested successfully. Please check later for processing status

ERROR

520

Unknown error occurred at bulk bank validation

ERROR

520

Error in Bulk Validation

ERROR

520

Bulk Validation request failed

Bank account object fields

Field name

Description

name

account holders name (alphanumeric and space allowed)

phone

account holders phone

bankAccount

account number to be validated (6 to 40 characters allowed)

ifsc

IFSC of account to be validated (standard IFSC format) - length 11, first four bank IFSC and 5th 0

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.ValidateBulkBankActivation({
bulkValidationId: "testid1",
entries: [
{ name:"John Doe",
bankAccount:"00011020001772",
ifsc:"HDFC0000001",
phone:"9876543210"
}
],
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
entry = [{ "name":"John Doe", "bankAccount":"00011020001772", "ifsc":"HDFC0000001", "phone":"9876543210"},{ "name":"Doe John", "bankAccount":"026291800001191", "ifsc":"YESB0000262", "phone":"9876543210"}]
​
b_valid = Validations.bulk_bank_validation(bulkValidationId="testid1", entries=entry)
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
BulkValidationRequest request = new BulkValidationRequest()
.setBulkValidationId("testid1")
.setEntries(new BulkValidationRequest.Payload[]{
new BulkValidationRequest.Payload()
.setName("John Doe")
.setBankAccount("00011020001772")
.setIfsc("HDFC0000001")
.setPhone("9876543210"),
new BulkValidationRequest.Payload()
.setName("Doe John")
.setBankAccount("026291800001191")
.setIfsc("YESB0000262")
.setPhone("9876543210")});
String bulkValidationId = validation.validateBulkBankActivation(request);
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/bulkValidation/bankDetails' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{Token}}'
-d '{
"bulkValidationId": "testid1",
"entries": [
{ "name":"John Doe",
"bankAccount":"00011020001772",
"ifsc":"HDFC0000001",
"phone":"9876543210"
},
,
{
" name": "Doe John",
"bankAccount": "026291800001191",
"ifsc": "YESB0000262",
"phone": "9876543210"
}
]
}'

get
Get bulk verification status

/payout/v1/getBulkValidationStatus
Get the statuses of bulk bank validation requests by providing the bulkValidationId.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
BulkValidationId
required
string
Id of the bulk validation whose statuses are to be retrieved
bankAccount
optional
string
particular bank account whose status needs to be retrieved
ifsc
optional
string
particular ifsc of whose status needs to be retrieved
Response
200: OK
{"status": "SUCCESS",
"subCode": "200",
"message": "Bulk Validation requested successfully.
Please check later for processing status.",
"data": { "bulkValidationId": "testid1" }}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Successful Bulk validation

ERROR

404

Bulk Validation Id does not exist

ERROR

404

No records found with the details provided.

ERROR

520

Error while fetching data

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Validation} = cfSdk.Payouts;
​
const response = await Validation.GetBulkValidationStatus({
bulkValidationId: "testid1",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.validations import Validations
​
status = Validations.get_bulk_bank_validation_status(bulkValidationId="testid1", bankAccount=
"00011020001772", ifsc="HDFC0000001")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Validation;
import com.cashfree.lib.domains.request.BulkValidationRequest;
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Validation validation = new Validation(payouts);
validation.getBulkValidationStatus(bulkValidationId, null, null);
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/getBulkValidationStatus?bulkValidationId=testid1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{Token}}'