Get Beneficiary V2

Use this API to get the details of a particular beneficiary from your account. You can pass either beneficiary_id or the combination of bank_account_number and bank_ifsc to fetch the details.

Click to view the response codes.

HTTP Status Code	Error Code	Message	Next Action
200	-	-	-
400	too_many_parameters_in_request	Please provide either bank_account_number and bank_ifsc together or beneficiary_id alone. Do not include all three parameters in the request	Please provide either bank_account_number and bank_ifsc together or beneficiary_id alone. Do not include all three parameters in the request.
400	bank_ifsc_missing	bank_ifsc : should be provided with the request if bank_account_number is provided	Provide a valid bank_ifsc if bank_account_number is provided.
400	bank_account_number_missing	bank_account_number: should be provided with the request if bank_ifsc is provided	Provide a valid bank_account_number is bank_ifsc is provided.
400	beneficiary_identifiers_missing	beneficiary_identifiers_missing beneficiary_identifiers : Either beneficiary_id or the combination of bank_account_number and bank_ifsc has to be provided with the request	Please provide either beneficiary_id or the combination of bank_account_number and bank_ifsc.
400	beneficiary_id_length_exceeded	beneficiary_id : should not be more than 50 characters long. value received: test_bene_id	Enter a valid beneficiary_id
400	beneficiary_id_invalid	beneficiary_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev	Enter a valid beneficiary_id.
400	bank_account_number_length_exceeded	bank_account_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345	Provide a valid bank_account_number.
400	bank_account_number_length_short	bank_account_number : should not be less than 4 characters long. value received: 12	Provide a valid bank_account_number.
.400	bank_account_number_invalid	bank_account_number : should be alphanumeric. value received: 123@	Provide a valid bank_account_number.
400	bank_ifsc_invalid	bank_ifsc : please provide a valid IFSC. value received: SBIN00708410	Provide a valid bank_ifsc.
404	beneficiary_not_found	Beneficiary does not exist	Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary.
404	beneficiary_not_found	Beneficiary with the given bank_account_number and bank_ifsc does not exist	Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary
404	beneficiary_not_found	Beneficiary exists with the given bank_account_number but a different bank_ifsc	If the required a beneficiary does not exist, use CREATE API to create a new beneficiary

Authorizations

x-client-id · string · header · required

Client ID. You can find your app id in the Merchant Dashboard.

x-client-secret · string · header · required

Client secret key. You can find your secret in the Merchant Dashboard.

Headers

x-api-version · string · default: 2024-01-01 · required

It is the API version to be used. The accepted format is YYYY-MM-DD.

x-request-id · string

It is the request ID for the API call. This ID can be used to resolve tech realted issues. Communicate this in your tech related queries to Cashfree Payments.

Query Parameters

beneficiary_id · string

It is the unique ID you created to identify the beneficiary while creating the beneficiary.

Maximum length: 50

bank_account_number · string

It is the bank account number of the beneficiary. If bank_account_number is passed in query, bank_ifsc should also be passed.

Required string length: 4 - 25

bank_ifsc · string

It is the IFSC information as present in the beneficiary's bank account information. If bank_ifsc is passed in query, bank_account_number should also be passed.

Required string length: 11

Response

200

application/json

OK

Contains the information of the created beneficiary

beneficiary_id · string

It displays the unique Id you created to identify the beneficiary.

Example:

"JOHN18011343"

beneficiary_name · string

It displays the name of the beneficiary.

Example:

"John Doe"

beneficiary_instrument_details · object

It displays the payment instrument details of the beneficiary.

Show child attributes

beneficiary_contact_details · object

It displays the contact details of the beneficiary.

Show child attributes

beneficiary_status · enum<string>

It displays the current status of the beneficiary. Possible values are as follows

• VERIFIED: Beneficiary is verified and is available for payouts
• INVALID: Beneficiary is invalid
• INITIATED: Beneficiary verification initiated
• CANCELLED: Beneficiary verification cancelled
• FAILED: Failed to verify beneficiary
• DELETED: Beneficiary is deleted

Available options:

VERIFIED,

INVALID,

INITIATED,

CANCELLED,

FAILED,

DELETED

Example:

"VERIFIED"

added_on · string

It displays the time of the addition of the beneficiary in UTC.

Example:

"2023-11-22T12:38:22Z"