Create Beneficiary V2

Use this API to add a beneficiary to your Cashfree Payments account by providing the bank account number, IFSC, and other required details. Ensure the successful creation of the benficiary in your account before initiating a transfer.

Click to view the response codes.

HTTP Status Code	Error Code	Message	Next Action
201	-	-	-
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_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	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.
400	beneficiary_purpose_invalid	beneficiary_purpose : invalid value provided. Value received: paytm	Provide a valid beneficiary_purpose.
409	beneficiary_id_already_exists	Beneficiary already exists with the given beneficiary_id	Provide a beneficiary_id that is not in use
409	beneficiary_already_exists	Beneficiary already exists with the given bank_account_number and bank_ifsc	Use the GET API to get the details of the existing beneficiary using bank_account_number and bank_ifsc
422	bank_account_number_same_as_source	bank_account_number provided is the same as source bank account	Enter a bank_account_number that is different from the source bank account
422	vba_beneficiary_not_allowed	Virtual bank account as bank_account_number for the beneficiary is not allowed	Enter the actual bank_account_number instead of the virtual account number

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.

Body

application/json

Find the request parameters to create a beneficiary

beneficiary_id · string · required

It is the unique ID you create to identify the beneficiary. Alphanumeric, underscore ( _ ), pipe ( | ), and dot ( . ) are allowed.

Maximum length: 50

Example:

"JOHN18011343"

beneficiary_name · string · required

It is the name of the beneficiary. The maximum character limit is 100. Only alphabets and whitespaces are allowed.

Maximum length: 100

Example:

"John Doe"

beneficiary_instrument_details · object

Beneficiary instrument details

Show child attributes

beneficiary_contact_details · object

It should contain the contact details of the beneficiary.

Show child attributes

Response

201

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"