Bank Account Verification API

Learn more about the Bank Account Verification API.
Guidelines
Below are the steps you must be aware of while calling Cashgram 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.
Cashfree Payouts Collection.json
Cashfree Payouts.postman_collection.json - 16KB
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" 
}
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"
}
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"
}
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"}
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" }
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" }}
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}}'
​
Cashgram API
Last updated 3 weeks ago
Environment	Host URL
Test	https://payout-gamma.cashfree.com
Prod	https://payout-api.cashfree.com
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
Bank Account Verification API

Guidelines

Postman collection

Host URL

Authentication

postAuthorize

postVerify token

Verification

getBank verification sync

getBank verification async

getGet verification status

getUPI verification

postBulk bank verification

Bank account object fields

getGet bulk verification status

​

post
Authorize

post
Verify token

get
Bank verification sync

get
Bank verification async

get
Get verification status

get
UPI verification

post
Bulk bank verification

get
Get bulk verification status
