Bank Account Verification APIs

Bank Account Verification API Document v1.0

Introduction

Payout Fintech API is organised around REST. Our API has predictable resource-oriented URLs, accepts JSON request and returns response, and uses standard HTTP response codes, authentication, and verbs.

You can use our API in the sandbox and production environment. We provide two different API urls and tokens for sandbox and production.

Pass API token and content-type for all the requests in header, token will be shared to you in an email.

  • content-type: application/json
  • authorization: Bearer <Token>

Bank Account Verification API

Verify if the bank account exists, using the penny drop method.

  • URL: /bankaccount
  • Method: POST

Request

Parameters Range Datatype Required Description
requestId Max 36 string Y Unique identifier to identify request, it should be unique to avoid duplicate transactions
beneficiaryName Max 35 string Y Beneficiary name. Regular expression:[a-zA-Z0-9_-., ]
accountNo Max 30 string Y Beneficiary account number
ifscCode Exact 11 characters string Y Beneficiary ifsc code

Response

Parameters Datatype Description
requestId string Returns the request value
referenceNo string Reference number generated for the transaction.
beneficiaryName string Returns the request value
accountNo string Returns the request value
ifscCode string Returns the request value

Example

Request

{

   "requestId" :   "C_148",

   "beneficiaryName" :   "sathish",

   "accountNo" :   "50100088614080",

   "ifscCode" :   "HDFC0000847"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "C_148",

"referenceNo" :   "PFVR7k00ogFOfJVOnZWu",

"beneficiaryName" :   "sathish",

"accountNo" :   "50100088614080",

"ifscCode" :   "HDFC0000847"

}

}

Bank Account Verification Status API

Get the verification status of the bank account details by request Id, Return actual name at bank and status.

On statusCode "SUCCESS" case Compare the beneficiary Name value with nameAtBank field and decide.

  • URL: /bankaccount/{requestId}
  • Method: GET

Request

N/A

Response

Parameters Datatype Description
requestId string Unique value to identify the fund transfer request
referenceNo string Reference number generated for the fund transfer.
nameAtBank string Account name from the beneficiary bank records
statusCode string Returns the fund transfer statusCode
errorDescription string errorDescription only returns for the failure case

Example 1

Success

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "C_148",

"referenceNo" :   "PFVR7k00ogFOfJVOnZWu",

"nameAtBank" :   "sathish s",

"statusCode" :   "SUCCESS",

"errorDescription" :   ""

}

}

Example 2

Failure

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "req6",

"referenceNo" :   "PFVRR4jVOADH14ZdnRCz",

"nameAtBank" :   "",

"statusCode" :   "FAILURE",

"errorDescription" :   "REJECTED - Incorrect beneficiary account detail"

}

}

Bank Account Verification Sync API

Verify if the bank account exists, using the penny drop method with synchronous way it immediately returns the nameAtBank.

  • URL: /bankaccountsync
  • Method: POST

Request

Parameters Range Datatype Required Description
requestId Max 36 string Y Unique identifier to identify request, it should be unique to avoid duplicate transactions
beneficiaryName Max 35 string Y Beneficiary name. Regular expression:[a-zA-Z0-9_-., ]
accountNo Max 30 string Y Beneficiary account number
ifscCode Exact 11 characters string Y Beneficiary ifsc code

Response

Parameters Datatype Description
requestId string Unique value to identify the fund transfer request
referenceNo string Reference number generated for the fund transfer
nameAtBank string Account name from the beneficiary bank records
statusCode string Returns the fund transfer statusCode
errorDescription string errorDescription only returns for the failure case

Examples

In the sandbox environment the API always returns success and returns the beneficiaryName for nameAtBank value. To test the other case use the following account numbers / IFSC pairs

Test Account No. Test IFSC Code Test Case
<<Any account No>> <<Any valid IFSC>> Success case Example 1
100201599111115 UTIB0000006 Verification success but different nameAtBank Example 2
100201599111100 UTIB0000006 Verification failed Example 3

Example 1 - Success Case

Request

{

   "requestId" :   "C_148",

   "beneficiaryName" :   "sathish",

   "accountNo" :   "50100088614080",

   "ifscCode" :   "HDFC0000847"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "C_148",

"referenceNo" :   "PFVR7k00ogFOfJVOnZWu",

"nameAtBank" :   "sathish s",

"statusCode" :   "SUCCESS",

"errorDescription" :   ""

}

}

Example 2 - Success different Name

Request

{

   "requestId" :   "C_149",

   "beneficiaryName" :   "sathish",

   "accountNo" :   "100201599111115",

   "ifscCode" :   "UTIB0000006"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "C_149",

"referenceNo" :   "PFVR7k00ogFOfJVOnZWu",

"nameAtBank" :   "siva",

"statusCode" :   "SUCCESS",

"errorDescription" :   ""

}

}

Example 3 - Failure Case

Request

{

   "requestId" :   "C_150",

   "beneficiaryName" :   "sathish",

   "accountNo" :   "100201599111100",

   "ifscCode" :   "UTIB0000006"

}

Response

{

   "code" :   200,

   "message" :   "success",

   "data" : {  

"requestId" :   "C_150",

"referenceNo" :   "PFVRR4jVOADH14ZdnRCz",

"nameAtBank" :   "",

"statusCode" :   "FAILURE",

"errorDescription" :   "REJECTED - Incorrect beneficiary account detail"

}

}

Bank Account Verification Status List

status_code Status Meaning
SUCCESS success Bank account exists
FAILURE failure Penny drop failed, decide based on reason field
ERROR error Fund transfer error
PENDING pending Temporary status, it will be updated

API Success and Error Messages

Http Status Code

200 - Success

400 - Error

Sample Error Response

     {

      "code" :   400,

      "errorCode" :   5002,

      "message" :   "requestId already exists. Duplicate not allowed"

    }

Possible Errors

Common Validation Error

Error code 5001 is same for all validation errors

Error Messages
requestId is mandatory
requestId maximum length should not exceed 36 characters
beneficiaryName is mandatory
beneficiaryName maximum length should not exceed 35 characters
beneficiaryName should contains only [a-zA-Z0-9_-., ] character sets
accountNo is mandatory
accountNo maximum length should not exceed 30 characters
ifscCode is mandatory
ifscCode format is invalid
Insufficient balance for Account Verification Sync. API
Verification is under process for this account No. and IFSC. Please try after sometime
Other Possible Errors
Error Codes Error Messages
5002 requestId already exists. Duplicate not allowed
5004 requestId not found

Postman Collection

Login to your Sandbox / Production environment and Bank Account Verification API Postman Collection download from the dashboard.