Cashfree Payments Developer Documentation

POST

beneficiary

curl --request POST \
  --url https://sandbox.cashfree.com/payout/beneficiary \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '{
  "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_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"
}

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

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

beneficiary_contact_details

object

It should contain the contact details of the beneficiary.

beneficiary_instrument_details

object

Beneficiary instrument details

Response

201 - application/json

Contains the information of the created beneficiary

added_on

string

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

beneficiary_contact_details

object

It displays the contact details of the beneficiary.

beneficiary_id

string

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

beneficiary_instrument_details

object

It displays the payment instrument details of the beneficiary.

beneficiary_name

string

It displays the name of the beneficiary.

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

Was this page helpful?

Get Beneficiary V2 Remove Beneficiary V2

curl --request POST \
  --url https://sandbox.cashfree.com/payout/beneficiary \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '{
  "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_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"
}

Payout APIs

V2

V1

One Escrow

Cashgram

Create Beneficiary V2

Authorizations

Headers

Body

Response