> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/docs/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2).
Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)
| 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](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) | [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) |
| 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 the [test data page](/docs/payouts/payouts/integrations/data-to-test).
## OpenAPI
````yaml post /payout/v1/addBeneficiary
openapi: 3.0.0
info:
title: Payouts
version: 3.0.0
servers:
- url: https://payout-api.cashfree.com
description: Production
- url: https://payout-gamma.cashfree.com
description: Sandbox
security:
- {}
paths:
/payout/v1/addBeneficiary:
post:
summary: Add Beneficiary
description: >-
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.
operationId: create-beneficiary-11
parameters:
- name: Authorization
in: header
description: Bearer auth token
required: true
style: simple
explode: false
schema:
type: string
- name: Content-Type
in: header
description: application/json
required: true
style: simple
explode: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/v1_addBeneficiary_body'
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200'
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_403'
'409':
description: '409'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_409'
'412':
description: '412'
content:
text/plain:
schema:
$ref: '#/components/schemas/inline_response_412'
'422':
description: '422'
content:
text/plain:
schema:
$ref: '#/components/schemas/inline_response_422'
deprecated: false
security: []
components:
schemas:
v1_addBeneficiary_body:
required:
- address1
- beneId
- email
- name
- phone
type: object
properties:
beneId:
type: string
description: >-
Unique Beneficiary ID to identify the beneficiary. Alphanumeric and
underscore (_) allowed (50 character limit)
name:
type: string
description: >-
It is the name of the beneficiary. A maximum of 100 characters are
allowed. Alphabets, numbers, white spaces ( ), and special
characters are allowed.
email:
type: string
description: >-
Beneficiaries email, string in email Id format (Ex:
johndoe_1@cashfree.com) - should contain @ and dot (.) - (200
character limit)
phone:
type: string
description: >-
Beneficiaries phone number, phone number registered in India (only
digits, 8 - 12 characters after stripping +91)
bankAccount:
type: string
description: Beneficiary bank account (9 - 18 alphanumeric character limit)
ifsc:
type: string
description: >-
Accounts IFSC (standard IFSC format) - length 11, first four bank
IFSC and 5th digit 0
vpa:
type: string
description: >-
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 (@)
address1:
type: string
description: >-
Beneficiaries address, alphanumeric and space allowed (but script,
HTML tags gets sanitized or removed) (150 character limit)
address2:
type: string
description: >-
Beneficiary address, alphanumeric and space allowed (but script,
HTML tags gets sanitized or removed) (150 character limit)
city:
type: string
description: >-
Beneficiary city, only alphabets and white space (50 character
limit)
state:
type: string
description: >-
Beneficiary state, only alphabets and white space (50 character
limit)
pincode:
type: string
description: Beneficiaries pincode, only numbers (6 character limit)
inline_response_200:
type: object
properties:
status:
type: string
example: SUCCESS
subCode:
type: string
example: '200'
message:
type: string
example: Beneficiary added successfully
inline_response_403:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '403'
message:
type: string
example: >-
APIs not enabled. Please fill out the [Support
Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1)
inline_response_409:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '409'
message:
type: string
example: Beneficiary Id already exists
inline_response_412:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '412'
message:
type: string
example: Post data is empty or not a valid JSON
inline_response_422:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '422'
message:
type: string
example: Please provide a valid Bank IFSC code.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.