> ## 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.
# 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.
Cashfree no longer support adding beneficiaries with Paytm UPI handles.
| 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 |
## OpenAPI
````yaml post /beneficiary
openapi: 3.0.0
info:
version: '2024-01-01'
title: Cashfree Payout APIs
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
email: developers@cashfree.com
name: API Support
url: https://discord.com/invite/QdZkNSxXsB
description: >-
Cashfree's Payout APIs provide developers with a streamlined pathway to
integrate advanced payout capabilities into their applications, platforms
and websites.
servers:
- url: https://sandbox.cashfree.com/payout
description: Sandbox server
- url: https://api.cashfree.com/payout
description: Production server
security: []
tags:
- name: V2 Apis
description: >-
Collection of APIs to transfer funds to beneficiaries and manage
beneficiaries.
externalDocs:
url: https://api.cashfree.com/payout
description: This url will have the information of all the APIs.
paths:
/beneficiary:
post:
tags:
- Beneficiary v2
summary: Create Beneficiary V2
description: >-
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.
operationId: PayoutCreateBeneficiary
parameters:
- $ref: '#/components/parameters/apiVersionHeader'
- $ref: '#/components/parameters/xRequestIDHeader'
- $ref: '#/components/parameters/xCfSignature'
requestBody:
description: Find the request parameters to create a beneficiary
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBeneficiaryRequest'
examples:
bene_creation_request_v2:
$ref: '#/components/examples/create_beneficiary_request_v2'
bene_creation_request_with_only_vpa:
$ref: '#/components/examples/bene_creation_request_with_only_vpa'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Beneficiary'
examples:
create_beneficiary_success_response_v2:
$ref: '#/components/examples/get_beneficiary_success_v2'
'400':
description: Bad request error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
bene_id_too_long:
$ref: '#/components/examples/bene_id_too_large_v2'
invalid_bene_id_due_unacceptable_characters:
$ref: >-
#/components/examples/invalid_bene_id_due_unacceptable_characters
bank_account_given_ifsc_not_given:
$ref: >-
#/components/examples/bank_account_given_ifsc_not_given_in_get_v2
bank_ifsc_given_account_not_given:
$ref: >-
#/components/examples/bank_ifsc_given_account_not_given_in_get_v2
bank_account_number_too_large:
$ref: '#/components/examples/bank_account_number_too_large'
bank_account_number_too_short:
$ref: '#/components/examples/bank_account_number_too_short'
bank_account_invalid:
$ref: '#/components/examples/bank_account_invalid'
invalid_ifsc:
$ref: '#/components/examples/invalid_ifsc'
'403':
description: Forbidden error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
APIDisabled:
$ref: '#/components/examples/APIsDisabledExampleV2'
'409':
description: Duplicate error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
duplicate_bene_id:
$ref: '#/components/examples/duplicate_bene_creation_response'
bene_exist_for_bank_account:
$ref: '#/components/examples/bene_exist_for_bank_account_and_ifsc'
'422':
description: Unprocessable error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorV2'
examples:
same_as_source_error:
$ref: '#/components/examples/same_bene_as_source_v2'
VBA_beneficiary_not_enabled:
$ref: '#/components/examples/vba_beneiciary_not_allowed'
deprecated: false
security:
- XClientID: []
XClientSecret: []
components:
parameters:
apiVersionHeader:
in: header
name: x-api-version
required: true
description: It is the API version to be used. The accepted format is YYYY-MM-DD.
schema:
type: string
description: It is the API version to be used.
default: '2024-01-01'
example: '2024-01-01'
xRequestIDHeader:
in: header
name: x-request-id
description: >-
Request ID for the API call. Can be used to resolve tech issues.
Communicate this in your tech related queries to Cashfree.
required: false
schema:
type: string
example: 4dfb9780-46fe-11ee-be56-0242ac120002
xCfSignature:
in: header
name: x-cf-signature
description: Signature to be sent if IP is not whitelisted.
required: false
schema:
type: string
schemas:
CreateBeneficiaryRequest:
title: Create Beneficiary request body
description: Find the request parameters to create a beneficiary
type: object
required:
- beneficiary_id
- beneficiary_name
properties:
beneficiary_id:
example: JOHN18011343
type: string
maxLength: 50
description: >-
It is the unique ID you create to identify the beneficiary.
Alphanumeric, underscore ( _ ), pipe ( | ), and dot ( . ) are
allowed.
beneficiary_name:
example: John Doe
type: string
description: >-
It is the name of the beneficiary. The maximum character limit is
100. Only alphabets and whitespaces are allowed.
maxLength: 100
beneficiary_instrument_details:
type: object
description: Beneficiary instrument details
properties:
bank_account_number:
example: '00111122233'
type: string
maxLength: 25
minLength: 4
description: >-
It is the beneficiary bank account number. The value should be
between 9 and 18 characters. Alphanumeric characters are
allowed. You need to input bank_ifsc if bank_account_number is
passed.
bank_ifsc:
example: HDFC0000001
type: string
description: >-
It is the IFSC information of the beneficiary's bank account in
the standard IFSC format. The value should be 11 characters.
(The first 4 characters should be alphabets, the 5th character
should be a 0, and the remaining 6 characters should be
numerals.). You need to input bank_account_number if bank_ifsc
is passed.
vpa:
example: test@upi
type: string
description: >-
It is the UPI VPA information of the beneficiary. Only valid UPI
VPA information is accepted. It can be an Alphanumeric value
with only period (.), hyphen (-), underscore ( _ ), and at the
rate of (@). Hyphen (-) is accepted only before at the rate of
(@).
beneficiary_contact_details:
type: object
description: It should contain the contact details of the beneficiary.
properties:
beneficiary_email:
example: johndoe_1@cashfree.com
type: string
maxLength: 200
description: >-
It is the email address of the beneficiary. The maximum
character limit is 200. It should contain dot (.) and at the
rate of (@).
beneficiary_phone:
example: '9876543210'
type: string
description: >-
It is the phone number of the beneficiary. Only reigstered
Indian phone numbers are allowed. The value should be between 8
and 12 characters after stripping +91.
beneficiary_country_code:
example: '+91'
type: string
description: It is the country code (+91) of the beneficiary's phone number
beneficiary_address:
example: 177A Bleecker Street
type: string
description: It is the address information of the beneficiary.
beneficiary_city:
example: New York City
type: string
description: >-
It is the name of the city as present in the beneficiary's
address.
beneficiary_state:
example: New York
type: string
description: >-
It is the name of the state as present in the beneficiary's
address.
beneficiary_postal_code:
example: '560001'
type: string
description: >-
It is the PIN code information as present in the beneficiary's
address. The maximum character limit is 6. Only numbers are
allowed.
Beneficiary:
title: Create Beneficiary success response
description: Contains the information of the created beneficiary
type: object
properties:
beneficiary_id:
example: JOHN18011343
type: string
description: It displays the unique Id you created to identify the beneficiary.
beneficiary_name:
example: John Doe
type: string
description: It displays the name of the beneficiary.
beneficiary_instrument_details:
type: object
description: It displays the payment instrument details of the beneficiary.
properties:
bank_account_number:
example: '00111122233'
type: string
description: It displays the bank account of the beneficiary.
bank_ifsc:
example: HDFC0000001
type: string
description: >-
It displays the IFSC information of the beneficiary's bank
account.
vpa:
example: test@upi
type: string
description: It displays the UPI VPA information of the beneficiary.
beneficiary_contact_details:
type: object
description: It displays the contact details of the beneficiary.
properties:
beneficiary_email:
example: johndoe1@cashfree.com
type: string
description: It displays the email address of the beneficiary.
beneficiary_phone:
example: '9876543210'
type: string
description: >-
It displays the phone number of the beneficiary without the
country code.
beneficiary_country_code:
example: '+91'
type: string
description: It displays the country code of the beneficiary's phone number.
beneficiary_address:
example: 177A Bleecker Street
type: string
description: It displays the address of the beneficiary.
beneficiary_city:
example: New York City
type: string
description: >-
It displays the name of the city as present in the beneficiary's
address.
beneficiary_state:
example: New York
type: string
description: >-
It displays the name of the state as present in the
beneficiary's address.
beneficiary_postal_code:
example: '560001'
type: string
description: >-
It displays the PIN code as present in the beneficiary's
address.
beneficiary_status:
example: VERIFIED
type: string
enum:
- VERIFIED
- INVALID
- INITIATED
- CANCELLED
- FAILED
- DELETED
description: >-
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
added_on:
example: '2023-11-22T12:38:22Z'
type: string
description: It displays the time of the addition of the beneficiary in UTC.
ErrorV2:
title: Error
description: Error Response for non-2XX cases
type: object
properties:
type:
type: string
description: Type of the error received
code:
type: string
description: Code of the error received
message:
type: string
description: Detailed message explaining the response
examples:
create_beneficiary_request_v2:
description: >-
Find the request body for creating a beneficiary with all the available
information
summary: Create beneficiary with all the available information
value:
beneficiary_id: JOHN18011343
beneficiary_name: John Doe
beneficiary_instrument_details:
bank_account_number: '1223334444'
bank_ifsc: HDFC0000001
vpa: test@upi
beneficiary_contact_details:
beneficiary_email: sample@cashfree.com
beneficiary_phone: '9876543210'
beneficiary_country_code: '+91'
beneficiary_address: 177A Bleecker Street
beneficiary_city: New York City
beneficiary_state: New York
beneficiary_postal_code: '560011'
bene_creation_request_with_only_vpa:
description: Beneficiary creation with only vpa
summary: Create beneficiary with only VPA
value:
beneficiary_id: JOHN18011343
beneficiary_name: John Doe
beneficiary_instrument_details:
vpa: test@upi
beneficiary_contact_details:
beneficiary_email: sample@cashfree.com
beneficiary_phone: '9876543210'
beneficiary_country_code: '+91'
beneficiary_address: 177A Bleecker Street
beneficiary_city: New York City
beneficiary_state: New York
beneficiary_postal_code: '560011'
get_beneficiary_success_v2:
description: Example values for Get Beneficiary V2 success response
value:
beneficiary_id: JOHN18011343
beneficiary_name: John Doe
beneficiary_instrument_details:
bank_account_number: '1223334444'
bank_ifsc: HDFC0000001
vpa: test@upi
beneficiary_contact_details:
beneficiary_email: sample@cashfree.com
beneficiary_phone: '9876543210'
beneficiary_country_code: '+91'
beneficiary_address: 177A Bleecker Street
beneficiary_city: New York City
beneficiary_state: New York
beneficiary_postal_code: '560011'
beneficiary_status: VERIFIED
added_on: '2023-12-04T15:50:00Z'
bene_id_too_large_v2:
description: Length of beneficiary_id is more than maximum allowed
summary: Length of beneficiary_id exceeded the maximum limit
value:
type: invalid_request_error
code: beneficiary_id_length_exceeded
message: >-
beneficiary_id : should not be more than 50 characters long. value
received: kl12b3rkh1bv234lkbr3jl24tbrlk234bkt234t134kbr1hk34jr
invalid_bene_id_due_unacceptable_characters:
description: Beneficiary ID contains characters that are not allowed
summary: Beneficiary ID contains characters that are not allowed
value:
type: invalid_request_error
code: beneficiary_id_invalid
message: >-
beneficiary_id : should contain only letters, numbers, hyphen,
underscore, pipe, and dot. Value received: .\qewqefwqev
bank_account_given_ifsc_not_given_in_get_v2:
description: Bank account number is provided but ifsc is not provided
summary: Missing IFSC but bank account number is provided
value:
type: invalid_request_error
code: bank_ifsc_missing
message: >-
bank_ifsc : should be provided with the request if bank_account_number
is provided
bank_ifsc_given_account_not_given_in_get_v2:
summary: Missing bank account number but IFSC is provided
description: Bank ifsc is provided but bank account number is not provided
value:
type: invalid_request_error
code: bank_account_number_missing
message: >-
bank_account_number: should be provided with the request if bank_ifsc
is provided
bank_account_number_too_large:
description: Bank account number provided is too large
summary: Provided bank account number is too large
value:
type: invalid_request_error
code: bank_account_number_length_exceeded
message: >-
bank_account_number : should not be more than 25 characters long.
value received: 235142352346523462456345263452345
bank_account_number_too_short:
description: Bank account number provided is too short
summary: Provided bank account number is too short
value:
type: invalid_request_error
code: bank_account_number_length_short
message: >-
bank_account_number : should not be less than 4 characters long. value
received: 12
bank_account_invalid:
description: Bank account number contains characters that are not allowed
summary: Provided bank account number contains characters that are not allowed
value:
type: invalid_request_error
code: bank_account_number_invalid
message: 'bank_account_number : should be alphanumeric. value received: 123@'
invalid_ifsc:
description: Invalid value given for IFSC
summary: Invalid IFSC
value:
type: invalid_request_error
code: bank_ifsc_invalid
message: 'bank_ifsc : please provide a valid IFSC. value received: SBIN00708410'
APIsDisabledExampleV2:
summary: APIs disabled
description: Forbidden request. APIs are disabled
value:
type: invalid_request_error
code: apis_not_enabled
message: >-
APIs not enabled. Please fill out the [Support
Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1)
duplicate_bene_creation_response:
summary: Beneficiary exists with the given beneficiary ID
description: Beneficiary with given beneficiary id already exist
value:
type: invalid_request_error
code: beneficiary_id_already_exists
message: Beneficiary already exists with the given beneficiary_id
bene_exist_for_bank_account_and_ifsc:
description: Account number and ifsc are already registered as a beneficiary
summary: Account number and IFSC are already registered for a beneficiary
value:
type: invalid_request_error
code: beneficiary_already_exists
message: >-
Beneficiary already exists with the given
beneficiary_bank_account_number and beneficiary_ifsc
same_bene_as_source_v2:
description: Beneficiary account is the same as the source bank account
summary: Beneficiary account is the same as the source bank account
value:
type: invalid_request_error
code: beneficiary_account_same_as_source
message: >-
beneficiary_bank_account_number provided can not be same as source
bank account
vba_beneiciary_not_allowed:
description: >-
Adding virtual bank account as a beneficiary is not allowed for the
account
summary: Virtual bank account is not allowed for the beneficiary
value:
type: invalid_request_error
code: vba_bene_not_allowed
message: >-
Virtual bank account as beneficiary_bank_account_number is not allowed
for the account
securitySchemes:
XClientID:
type: apiKey
in: header
name: x-client-id
description: >-
Client app ID. You can find your app ID in the [Merchant
Dashboard](https://merchant.cashfree.com/payouts/developers/api-keys).
XClientSecret:
type: apiKey
in: header
name: x-client-secret
description: >-
Client secret key. You can find your secret key in the [Merchant
Dashboard]((https://merchant.cashfree.com/payouts/developers/api-keys).
````