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.
Get started quickly with Cashfree payouts APIs by downloading the following collection and importing it in Postman.
Use the following host URLs based on your specific environment.
Environment | Host URL |
Test | |
Prod |
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.
<token>
' (without quotes) for them to get processed.{"status":"SUCCESS","message":"Token generated","subCode":"200","data": {"token":"eyJ0eXA...fWStg","expiry":1564130052}}
{"status":"ERROR","message":"Invalid clientId and clientSecret combination","subCode":"401"}
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.
/payout/v1/authorize
for this){"status":"SUCCESS","message":"Token is valid","subCode":"200"}
{"status":"ERROR","subCode":"403","message":"Token is not valid"}
curl -X POST \'http://{{Host%20Url}}/payout/v1/verifyToken' \-H 'Authorization: Bearer {{Token}}' \
Verify bank account Ids and UPI Ids individually or in bulk.
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validations
import com.cashfree.lib.clients.Payouts;import com.cashfree.lib.clients.Validation;import com.cashfree.lib.domains.request.BulkValidationRequest;//Validation validation = new Validation(payouts);
refId
.
To fetch the status of such request you can use the Get Verification Status API, by passing the refId
as bvRefId
.
{"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"}}
{"status": "ERROR","subCode": "422","message": "Please provide a valid IFSC code"}
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 |
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;const response = await Validation.ValidateBankDetails({name: "John Doe",phone: "9876543210",bankAccount: "026291800001191",ifsc: "YESB0000262"});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsv_det = Validations.bank_details_validation(name="JOHN", phone="9876543210", bankAccount="026291800001191",ifsc="YESB0000262")
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 -X GET \'http://{{Host%20Url}}/payout/v1/validation/bankDetails?name=John&phone=9876543210&bankAccount=026291800001191&ifsc=YESB0000262' \-H 'Authorization: Bearer {{Token}}'
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"}}
{"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"}
Staus | Sub Code | Message |
SUCCESS | 200 | Request Accepted |
ERROR | 422 | Input not in expected format |
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;const response = await Validation.ValidateBankDetails({name: "John Doe",phone: "9876543210",bankAccount: "026291800001191",ifsc: "YESB0000262"});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsv_det = Validations.bank_details_validation(name="JOHN", phone="9876543210", bankAccount="026291800001191",ifsc="YESB0000262")
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 -X GET \'http://{{Host%20Url}}/payout/v1/asyncValidation/bankDetails?name=John&phone=9876543210&bankAccount=026291800001191&ifsc=YESB0000262' \-H 'Authorization: Bearer {{Token}}'
bvRefId or userId
.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"}
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"}
Status | Sub Code | Message |
SUCCESS | 200 | Successful Bank validation |
ERROR | 404 | No such BV reference Id |
ERROR | 520 | Bank Account Validation Failed |
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;const response = await Validation.GetValidationStatus({bvRefId: "123456",});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsstatus = Validations.get_bank_validation_status(bvRefId="123456")
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 -X GET \'http://{{Host%20Url}}/payout/v1/getValidationStatus/bank?bvRefId=123456' \-H 'Authorization: Bearer {{Token}}'
{ "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"} }
{ "status": 0,"subCode": "422","message": "Either VPA or name invalid"}
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 |
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;const response = await Validation.ValidateUPIDetails({name: "John Doe"vpa: "success@upi"});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsupi_valid= Validations.upi_validation(name="John Doe", vpa="success@upi")
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 -X GET \'http://{{Host%20Url}}/payout/v1/validation/upiDetails?name=John&vpa=success@upi \-H 'Authorization: Bearer {{Token}}'
{"status": "SUCCESS","subCode": "200","message": "Ifsc verification successful","data":{"bank": "HDFC BANK","ifsc": "HDFC0004110","neft": "Live","imps": "Live","rtgs": "Live""upi": "Not Live","ft": "Live","card": "Not Live","micr": 110240403,"nbin": 9240,"address": "HDFC BANK LTD WZ G 1 161 GROUND FLOOR UTTAM NAGAR MAIN ROAD NEW DELHI DELHI 110059","city": "DELHI","state": "DELHI","branch": "UTTAM NAGAR","ifscSubcode": "HDFC0","category": "DIRECT_MEMBER","swiftCode": ""}}
{"status": "ERROR","subCode": "400","message": "Invalid IFSC. IFSC Code should contain 11 characters"}
Response Codes
Status | SubCode | Message |
SUCCESS | 200 | IFSC verification successful |
ERROR | 400 | Invalid IFSC. IFS Code should contain 11 characters |
ERROR | 400 | Invalid IFSC. 5th character of IFSC Code should be 0 |
ERROR | 404 | IFSC not found. Try again with valid IFSC |
ERROR | 520 | Unknown error occurred! |
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" }}
{"status": "ERROR","subCode": "409","message": "Bulk Validation Id already exists"}
{ "status": "ERROR","subCode": "422","message": "Mandatory Parameters missing in the request" }
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 |
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 |
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"}],});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsentry = [{ "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)
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 -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"}]}'
bulkValidationId
.{"status": "SUCCESS","subCode": "200","message": "Bulk Validation requested successfully.Please check later for processing status.","data": { "bulkValidationId": "testid1" }}
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 |
const cfSdk = require('cashfree-sdk');const {Validation} = cfSdk.Payouts;const response = await Validation.GetBulkValidationStatus({bulkValidationId: "testid1",});
from cashfree_sdk.payouts import Payoutsfrom cashfree_sdk.payouts.validations import Validationsstatus = Validations.get_bulk_bank_validation_status(bulkValidationId="testid1", bankAccount="00011020001772", ifsc="HDFC0000001")
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 -X GET \'http://{{Host%20Url}}/payout/v1/getBulkValidationStatus?bulkValidationId=testid1' \-H 'Content-Type: application/json' \-H 'Authorization: Bearer {{Token}}'