Add Beneficiary

Use this API to add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. Before you request a transfer, ensure the account has been successfully added as a beneficiary.

This API will be retired soon. Please plan to migrate to the latest version, Beneficiary V2.

Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)

Click to view the response codes.

Sub Code	Status	Message	Next Action
200	SUCCESS	Beneficiary added successfully	-
400	ERROR	Please provide a valid VPA	Enter a valid VPA in the API request.
403	ERROR	Token is not valid	Enter a valid token in the request.
403	ERROR	IP not whitelisted	Whitelist the API.
403	ERROR	APIs not enabled. Fill out the details in the Support Form	Support Form
409	ERROR	Beneficiary Id already exists	Enter a unique ID for the beneficiary.
409	ERROR	Entered bank Account is already registered	Enter different bank account information.
412	ERROR	Token missing in the request	Enter a valid token in the request.
412	ERROR	Beneficiary group is not an active group
412	ERROR	Bank account and VPA are both provided in the request. Please add either of them to add the beneficiary.	Enter any of the information in the request.
412	ERROR	Cannot add yourself as a beneficiary	Enter an individual’s information apart from yours to add a beneficiary.
422	ERROR	Please provide a valid Beneficiary Id	Enter a valid beneficiary ID.
422	ERROR	Please provide a valid email	Enter a valid email address.
422	ERROR	Please provide a valid name	Enter a valid name.
422	ERROR	Please provide a valid Phone Number	Enter a valid phone number.
422	ERROR	Please provide a valid Bank Account	Enter valid bank account information.
422	ERROR	Please provide a valid Bank IFSC code	Enter a valid IFSC.
422	ERROR	Please provide a valid Virtual Payee Address	Enter a valid VPA.
422	ERROR	Please provide a valid Address	Enter a valid address.
422	ERROR	Please provide a valid City Name	Enter a valid city name.
422	ERROR	Please provide a valid State Name	Enter a valid state name.
422	ERROR	Please provide a valid Pin code	Enter a valid PIN code.
422	ERROR	Cashfree VBA/VPA cannot be added as a beneficiary	Enter a different VBA/VPA to add the beneficiary.
422	ERROR	Please provide a valid MasterCard or Visa card number	Enter a valid MasterCard or Visa card number.
422	ERROR	Please provide a masked card number of a valid MasterCard or Visa card	Enter a masked card number of a valid MasterCard or Visa card.
422	ERROR	Invalid details provided	Enter valid details of the beneficiary to add the beneficiary in the system.
520	ERROR	Adding beneficiary Failed	Re-enter the details or try again after some time.

Note: If you are attempting to create a transfer in the Sandbox environment, you can obtain the test data details from this link.

Headers

Authorization · string · required

Bearer auth token

Content-Type · string · required

application/json

Body

application/json

beneId · string · required

Unique Beneficiary ID to identify the beneficiary. Alphanumeric and underscore (_) allowed (50 character limit)

name · string · required

It is the name of the beneficiary. A maximum of 100 characters are allowed. Alphabets, numbers, white spaces ( ), and special characters are allowed.

email · string · required

Beneficiaries email, string in email Id format (Ex: [e-mail]) - should contain @ and dot (.) - (200 character limit)

phone · string · required

Beneficiaries phone number, phone number registered in India (only digits, 8 - 12 characters after stripping +91)

address1 · string · required

Beneficiaries address, alphanumeric and space allowed (but script, HTML tags gets sanitized or removed) (150 character limit)

bankAccount · string

Beneficiary bank account (9 - 18 alphanumeric character limit)

ifsc · string

Accounts IFSC (standard IFSC format) - length 11, first four bank IFSC and 5th digit 0

vpa · string

Beneficiary VPA, alphanumeric, dot (.), hyphen (-), at sign (@), and underscore () allowed (100 character limit). Note: underscore () and dot (.) gets accepted before and after at sign (@), but hyphen (-) get only accepted before at sign (@)

address2 · string

Beneficiary address, alphanumeric and space allowed (but script, HTML tags gets sanitized or removed) (150 character limit)

city · string

Beneficiary city, only alphabets and white space (50 character limit)

state · string

Beneficiary state, only alphabets and white space (50 character limit)

pincode · string

Beneficiaries pincode, only numbers (6 character limit)

Response

200

application/json

200

status · string

Example:

"SUCCESS"

subCode · string

Example:

"200"

message · string

Example:

"Beneficiary added successfully"