Payouts API

Learn more about Cashfree Payouts APIs.

Guidelines

Below are some of the points you must be aware of while calling Payouts APIs:

  • All API responses are in JSON format.

  • POST requests should include ContentType: application/json

  • All API response have status, subCode, message, and data.

  • Subcode is the status subcode of the response-All requests to Cashfree that are processed by the server return HTTP 200. Use the status flag to determine if the request was successfully processed. Check the error subcodes here.

  • Certain APIs support pagination. If an API does support pagination, Cashfree does not return more than 10 items per request. Pass the lastReturnId if received as a part of the response to continue fetching. If lastReturnId is not present, no further item exists.

We recommended you to scan error sub-code and not error messages.

Postman collection

Get started quickly with Cashfree payouts APIs by downloading the following collection and importing it in Postman.

Host URL

Use the following host URLs based on your specific environment.

Environment

Host URL

Test

​https://payout-gamma.cashfree.com​

Prod

​https://payout-api.cashfree.com​

Authentication

Calling the Authentication APIs allows you to get and verify bearer tokens returned by Cashfree. Cashfree require these token for all further communication.

  • Cashfree libraries automatically call the Authorize API and internally store the token.

  • Do not store the token in an insecure manner. Regenerating a new token does not invalidate the already generated token. Token generated from one IP address cannot be used from a different IP address.

  • Token generated is valid for 300 seconds. Please ensure that you recall the authorize API once the token has expired.

  • Token generated is valid for 300 seconds. Please ensure that you recall the authorize API once the token has expired.

  • Ensure your IP is whitelisted. To whitelist your IP or if you have a dynamic IP, click here for more details.

post
Authorize

/payout/v1/authorize
To authenticate with the Cashfree system and obtain the authorization bearer token, call the authorize API. All other API calls must have this token as Authorization header in the format 'Bearer <token>' (without quotes) for them to get processed.
Request
Response
Request
Headers
X-Cf-Signature
optional
string
Signature to be sent if IP is not whitelisted
X-Client-Secret
required
string
ClientSecret
X-Client-Id
required
string
ClientId
Response
200: OK
{
"status": "SUCCESS",
"subCode": "200",
"message": "Token is valid"
}
​
401: Unauthorized
{"status":"ERROR",
"subCode":"401",
"message":"Invalid clientId and clientSecret combination"}
Curl
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/authorize' \
-H 'X-Client-Id: {{client id}}' \
-H 'X-Client-Secret: {{client secret}}' \

Cashfree libraries store the token internally and have their internal verification logic. This API does not apply to them.

post
Verify token

/payout/v1/verifyToken
Verify the bearer token generated. If the token does not exist, is invalid, or has expired, the response "Token is not valid" is returned. Regenerate token incase of token expiry for making API calls ( use /payout/v1/authorize for this).
Request
Response
Request
Headers
Authorization
required
string
Bearer token to be verified
Response
200: OK
{"status":"SUCCESS",
"message":"Token is valid",
"subCode":"200"}
403: Forbidden
{"status":"ERROR",
"subCode":"403",
"message":"Token is not valid"}
Curl
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/verifyToken' \
-H 'Authorization: Bearer {{Token}}' \

Account

The Cashfree account APIs contain information about the ledger and available balance. Also, information on how to initiate the withdrawal and internal transfers from your Cashfree payouts account.

get
Get balance

/payout/v1/getBalance
Get ledger balance and available balance of your account. Available balance is ledger balance minus the sum of all pending transfers (transfers triggered and processing or pending now).
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Response
200: OK
{"status":"SUCCESS",
"subCode":"200",
"message":"Ledger balance for the account",
"data": {"balance":"214735.50", "availableBalance":"173980.50"}}
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const response = await cfSdk.Payouts.GetBalance();
Python
from cashfree_sdk.payouts.transfers import Transfers
b = Transfers.get_balance()
Java
import com.cashfree.lib.clients.Payouts;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
payouts.getBalance();
​
}
​
Curl
curl -X GET \
https://{{Host%20Url}}payout/v1/getBalance \
-H 'Authorization: Bearer {{Token}}\

post
Self withdrawal

/payout/v1/selfWithdrawal
Request a self withdrawal at Cashfree. Self withdrawal is allowed for maximum of 3 times in a day. The API response will either result in an ERROR or SUCCESS response. The status of the withdrawal request is available on the dashboard.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
withdrawalId
required
string
Unique identifier for the withdrawal, alphanumeric allowed (50 character limit)
amount
required
number
Amount to be withdrawn, decimal (>= 1.00)
remarks
optional
string
Remarks, if any. Alphanumeric and white space (70 character limit)
Response
200: OK
{"status": "SUCCESS",
"message": "Request submitted successfully. Withdrawal Id : W55",
"statusCode": "200"}
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const response = await cfSdk.Payouts.SelfWithdrawal({
withdrawalId: "testWithdrawal1"
amount: "1.00"
});
Python
from cashfree_sdk.payouts.transfers import Transfers
withd = Transfers.self_withdrawal(withdrawalId="withdraw1", amount=1.1, remarks="withdrawal request")
Java
import com.cashfree.lib.clients.Payouts;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
//self withdrawal is under construction
payouts.selfWitdrawal();
​
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/selfWithdrawal' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{Token}}\
-d '{
"withdrawlId": "1",
"amount": 2
}'

post
Internal transfer

/payout/v1/internalTransfer
Request an internal transfer at Cashfree. Internal transfer is useful for multiple Payouts accounts. The API response will either result in an ERROR or SUCCESS response.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
amount
required
number
Amount to be transferred. Number (>=1)
rechargeAccount
required
string
Cashfree internal recharge account number. Alphanumeric allowed
Response
200: OK
{
"status": "SUCCESS",
"subCode": "200",
"message": "Internal Transfer Successful"
}
404: Not Found
{
"status": "ERROR",
"subCode" "404",
"message" "Recharge Account not found"
}
422: Unprocessable Entity
{
"status": "ERROR",
"message" "Account not configured. Please reach out to accoount manager"
"subCode" "422"
}
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const response = await cfSdk.Payouts.InternalTransfer({
amount: 1.1,
rechargeAccount: "492372992"
});
Python
from cashfree_sdk.payouts.transfers import Transfers
transfer = Transfers.internal_transfer(amount=1.1, rechargeAccuont="492372992")
Java
import com.cashfree.lib.clients.Payouts;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
​
payouts.internalTransfer();
​
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/internalTransfer' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{Token}}\
-d '{
"ammount": 1.1,
"rechargeAccount": "492372992"
}'

Beneficiary

A beneficiary is a data object that stores the necessary information about the person who is the intended recipient for the payouts. A payout cannot be initiated to that particular account unless a beneficiary is successfully added.

For batch transfers adding a beneficiary is not required. Cashfree implicitly handles beneficiary creation.

Node
Python
Java
Node
const cfSdk = require('cashfree-sdk');
const {Beneficiary} = cfSdk.Payouts;
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.beneficiary import Beneficiary
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Beneficiary;
import com.cashfree.lib.domains.BeneficiaryDetails;
​
//Call to initialize beneficiary object
//Beneficiary bene = new Beneficiary(payouts);

If the bank account details are incorrect (customer name does not match/mismatch in IFSC), the beneficiary status is automatically changed to INVALID.

post
Add beneficiary

/payout/v1/addBeneficiary
Add a beneficiary to your Cashfree account by providing the bank account number, IFSC, and other required details. You can only request a transfer if the account has been successfully added as a beneficiary already.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
beneId
required
string
Unique Beneficiary Id to identify the beneficiary. Alphanumeric and underscore (_) allowed (50 character limit)
name
required
string
Beneficiary name, only alphabets and white space (100 character limit)
email
required
string
Beneficiaries email, string in email Id format (Ex: johndoe_1@cashfree.com) - should contain @ and dot (.) - (200 character limit)
phone
required
string
Beneficiaries phone number, phone number registered in India (only digits, 8 - 12 characters after stripping +91)
bankAccount
optional
string
Beneficiary bank account (9 - 18 alphanumeric character limit)
ifsc
optional
string
Accounts IFSC (standard IFSC format) - length 11, first four bank IFSC and 5th digit 0
vpa
optional
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 (@)
cardNo
optional
string
Beneficiaries card number, only digits. Starting with 4 or 5 only (16 character limit)
address1
required
number
Beneficiaries address, alphanumeric and space allowed (but script, HTML tags gets sanitized or removed) (150 character limit)
address2
optional
string
Beneficiary address, alphanumeric and space allowed (but script, HTML tags gets sanitized or removed) (150 character limit)
city
optional
string
Beneficiary city, only alphabets and white space (50 character limit)
state
optional
string
Beneficiary state, only alphabets and white space (50 character limit)
pincode
optional
integer
Beneficiaries pincode, only numbers (6 character limit)
Response
200: OK
Response
{"status":"SUCCESS",
"subCode":"200",
"message":"Beneficiary added successfully"
}
409: Conflict
Response
{"status":"ERROR",
"subCode":"409",
"message":"Beneficiary Id already exists"}
412: Precondition Failed
Response
{"status":"ERROR",
"subCode":"412",
"message":"Post data is empty or not a valid JSON"}
422: Unprocessable Entity
{
"status": "ERROR",
"subCode": "422",
"message": "Please provide a valid Bank IFSC code."
}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Beneficiary added successfully

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

409

Beneficiary Id already exists

ERROR

422

Please provide a valid Beneficiary Id

ERROR

422

Please provide a valid email

ERROR

422

Please provide a valid name

ERROR

422

Please provide a valid Phone Number

ERROR

422

Please provide a valid Bank Account

ERROR

422

Please provide a valid Bank IFSC code

ERROR

422

Please provide a valid Virtual Payee Address

ERROR

422

Please provide a valid Address

ERROR

422

Please provide a valid City Name

ERROR

422

Please provide a valid State Name

ERROR

422

Please provide a valid Pin code

ERROR

409

Entered bank Account is already registered

ERROR

412

Beneficiary group is not an active group

ERROR

412

Cannot add yourself as a beneficiary

ERROR

520

Adding beneficiary Failed

ERROR

422

Please provide a valid MasterCard or Visa card number

ERROR

422

Please provide a masked card number of a valid MasterCard or Visa card

ERROR

422

Invalid details provided

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Beneficiary} = cfSdk.Payouts;
​
const response = await Beneficiary.Add({
"beneId": "JOHN180127",
"name": "john doe",
"email": "johndoe@cashfree.com",
"phone": "9876543210",
"bankAccount": "00011020001773",
"address1" : "ABC Street",
"city": "Bangalore",
"state":"Karnataka",
"pincode": "560001"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.beneficiary import Beneficiary
​
bene_add = Benefeciary.add(beneId="JOHN18012", name="john doe", email="johndoe@cashfree.com", phone="9876543210", address1="ABC Street", bankAccount="00001111222233", ifsc="HDFC0000001")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Beneficiary;
import com.cashfree.lib.domains.BeneficiaryDetails;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Beneficiary beneficiary = new Beneficiary(payouts);
​
BeneficiaryDetails beneficiaryDetails = new BeneficiaryDetails()
.setBeneId("JOHN18012")
.setName("john doe")
.setEmail("johndoe@cashfree.com")
.setPhone("9876543210")
.setBankAccount("00001111222233")
.setIfsc("HDFC0000001")
.setAddress1("ABC Street")
.setCity("Bangalore")
.setState("Karnataka")
.setPincode("560001");
​
beneficiary.addBeneficiary(beneficiaryDetails);
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/addBeneficiary' \
-H 'Authorization: Bearer {{Token}}' \
-d '{
"beneId": "JOHN18011343",
"name": "john doe",
"email": "johndoe@cashfree.com",
"phone": "9876543210",
"bankAccount": "00111122233",
"ifsc": "HDFC0000001",
"address1": "ABC Street",
"city": "Bangalore",
"state": "Karnataka",
"pincode": "560001"
}'

get
Get beneficiary details

/payout/v1/getBeneficiary/<beneId>
Get the details of a particular beneficiary.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
beneId
required
string
Beneficiary Id
Response
200: OK
{"status":"SUCCESS",
"subCode":"200",
"message":"Details of beneficiary",
"data": {"beneId":"JOHN18011",
"name":"John",
"groupName":"DEFAULT",
"email":"johndoe@cashfree.com",
"phone":"9876543210",
"address1":"ABCavenue",
"address2":"",
"city":"Bangalore",
"state":"Karnataka",
"pincode":"0",
"bankAccount":"00001111222233",
"ifsc":"HDFC0000001", "status":"VERIFIED"}}
404: Not Found
{"status":"ERROR",
"subCode":"404",
"message":"Beneficiary does not exist"}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Details of beneficiary

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

404

Beneficiary does not exist

ERROR

520

Unknown error occurred

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Beneficiary} = cfSdk.Payouts;
​
const response = await Beneficiary.GetDetails({
"beneId": "JOHN18011",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.beneficiary import Beneficiary
​
bene_details = Benefeciary.get_bene_details("JOHN18011")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Beneficiary;
import com.cashfree.lib.domains.BeneficiaryDetails;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Beneficiary beneficiary = new Beneficiary(payouts);
beneficiary.getBeneficiaryDetails("JOHN18011");
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/getBeneficiary/JOHN18011' \
-H 'Authorization: Bearer {{Token}}' \

get
Get beneficiary id

/payout/v1/getBeneId
Get the beneficiary id by providing the bank account number and ifsc.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
bankAccount
optional
string
Beneficiaries bank account number, alphanumeric ( >=6 and <= 40 characters)
ifsc
optional
string
Beneficiaries bank's IFSC code (standard IFSC format) - length 11, first four IFSC and 5th 0
Response
200: OK
{"status": "SUCCESS",
"subCode": "200",
"message": "beneId retrieved successfully",
"data": { "beneId": "JOHN18011"}}
404: Not Found
{"status": "ERROR",
"subCode": "404",
"message": "Beneficiary not found with given bank account details"}

Response Codes

Status

Sub Code

Message

SUCCESS

200

beneId retrieved successfully

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

422

Please provide a valid bank account and ifsc

ERROR

422

Please provide both bank account and ifsc

ERROR

404

Beneficiary not found with given bank account details

ERROR

520

Error while fetching beneId

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Beneficiary} = cfSdk.Payouts;
​
const response = await Beneficiary.GetBeneId({
bankAccount: "00001111222233"
ifsc: "HDFC000001"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.beneficiary import Beneficiary
​
bene_id = Benefeciary.get_bene_id("00001111222233", "HDFC0000001")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Beneficiary;
import com.cashfree.lib.domains.BeneficiaryDetails;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Beneficiary beneficiary = new Beneficiary(payouts);
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/getBeneId?bankAccount=00111122233&ifsc=HDFC0000001' \
-H 'Authorization: Bearer {{Token}}' \

post
Remove beneficiary

/payout/v1/removeBeneficiary
Remove an existing beneficiary from a list of added beneficiaries.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
beneId
required
string
Beneficiaries Id to delete, alphanumeric and underscore allowed (50 character limit)
Response
200: OK
{ "status":"SUCCESS",
"subCode":"200",
"message":"Beneficiary removed"}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Beneficiary removed

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

412

beneId missing in the request

ERROR

404

Beneficiary does not exist with given Id

ERROR

520

Unknown error occurred

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Beneficiary} = cfSdk.Payouts;
​
const response = await Beneficiary.Remove({
beneId: "JOHN18011",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.beneficiary import Benefeciary
​
remove_bene = Benefeciary.remove_bene("JOHN18011")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Beneficiary;
import com.cashfree.lib.domains.BeneficiaryDetails;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Beneficiary beneficiary = new Beneficiary(payouts);
beneficiary.removeBeneficiary("JOHN18012")
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/removeBeneficiary' \
-H 'Authorization: Bearer {{Token}}' \
-d '{
"beneId" : "JOHN18011"
} '

get
Get Beneficiary History

/payout/v1/beneHistory
The beneHistory API allows you to fetch the transaction history for a particular beneficiary for a desired period of time. Note: 1. This API is rate-limited, it supports 100 requests per minute. 2. This API supports pagination. Use page parameters to display the next pages.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
beneId
required
string
The beneficiary id that you have created. Alphanumeric characters accepted.
startDate *
optional
string
Start date for the desired period. Format - yyyy-mm-dd
endDate *
optional
string
End date for the desired period. Format - yyyy-mm-dd
perPage
optional
number
Number of transactions to be displayed on the page. Maximum = 25. Default value set is 25.
page
optional
number
Will show the latest transfers on the first page. Minimum = 1. Default value set is 1.
Response
200: OK
{
"status": "SUCCESS",
"subCode": "200",
"message": "Data retrieved successfully",
"data": {
"transfers": [
{
"transferDate": "2020-06-16",
"amount": "1",
"mode": "IMPS",
"beneId": "John Doe",
"status": "SUCCESS"
},
{
"transferDate": "2020-05-28",
"amount": "1",
"mode": "NEFT",
"beneId": "John Doe",
"status": "SUCCESS"
},
{
"transferDate": "2020-05-15",
"amount": "1.1",
"mode": "IMPS",
"beneId": "John Doe",
"status": "SUCCESS"
},
{
"transferDate": "2020-05-15",
"amount": "1.1",
"mode": "IMPS",
"beneId": "John Doe",
"status": "SUCCESS"
},
{
"transferDate": "2020-05-15",
"amount": "1",
"mode": "IMPS",
"beneId": "John Doe",
"status": "SUCCESS"
}
]
}
}
422: Unprocessable Entity
{
"status": "ERROR",
"subCode": "422",
"message": "Please provide a valid beneId"
}

If start date is provided, end date is a required field. End date has to be a day less than today’s date.

Response Codes

Status

Subcode

Message

Description

Data

SUCCESS

200

Data retrieved successfully.

Request processed successfully.

transferDate Amount

beneId

Status

ERROR

422

Requested date range is invalid.

Input is not in expected format.

​

ERROR

422

Page value should be minimum 1.

Input is not in expected format.

​

ERROR

422

Please provide a valid Beneficiary Id.

Input is not in expected format.

​

ERROR

405

Invalid request URL or HTTP method.

Method not allowed.

​

ERROR

403

Token is invalid.

Forbidden

​

ERROR

520

Unknown error occurred.

Error while processing the request.

​

ERROR

429

Too many requests.

API request limit crossed.

​

Transfers

Transfer funds and check the status of the transfer to recipients using various modes, including bank transfer, Paytm, amazon pay, UPI, and cards, etc.

Node
Python
Java
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.transfers import Transfers
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Transfers;
import com.cashfree.lib.domains.request.BatchTransferRequest;
import com.cashfree.lib.domains.request.RequestTransferRequest;
​
//Transfers transfer = new Transfers(payouts);

Transfer statuses

List of possible transfer statuses returned by Cashfree.

Transfer Status

Description

SUCCESS

Transfer completed successfully. Acknowledged flag in the response tells whether the beneficiary bank has provided acknowledgment of the transfer request.

ERROR

There was an error while requesting the transfer. See sub status code received for more details on why it failed. Example: Wrong IFSC.

FAILED

The transfer has failed.

PENDING

The request is getting processed. Query transfer status (/getTransferStatus) after some time to see whether the request was successful/failed.

REVERSED

Transfer rejected by the beneficiary bank. The payout balance gets credited back with the amount charged. Note: You don't receive this when you are attempting a transfer but might see this when querying for transfer status (after a couple of hours). Please configure the webhook endpoint (discussed later) to be notified in such cases.

post
Standard transfer sync

/payout/v1/requestTransfer
Request an amount transfer at Cashfree by providing beneficiary id, amount, and transfer id. This is a sync transfer request. Once you trigger the requestTransfer API, the transfer to the beneficiary account will be attempted immediately and the bank's reference number will be returned in the API response. The median time for the response is 2 to 5 seconds.
Request
Response
Request
Headers
Authorization
required
string
Bearer Auth Token
Body Parameters
beneId
required
string
Beneficiary Id, alphanumeric
amount
required
number
amount to be transferred, decimal(>= 1.00)
transferId
required
string
A unique Id to identify this transfer, alphanumeric and underscore (_) allowed (40 character limit)
transferMode
optional
string
Mode of transfer, banktransfer by default, Allowed values are: banktransfer, upi, paytm, amazonpay, and card
remarks
optional
string
Additional remarks, if any, alphanumeric and white spaces allowed (70 characters limit)
Response
200: OK
Response
{"status":"SUCCESS",
"subCode":"200",
"message":"Transfer completed successfully",
"data": {"referenceId":"10023",
"utr":"P16111765023806",
"acknowledged": 1}}
404: Not Found
Response
{"status":"ERROR",
"subCode":"404",
"message":"Beneficiary doesnot exist"}
422: Unprocessable Entity
Response
{"status":"ERROR",
"subCode":"422",
"message":"Remarks can have only numbers,alphabets and whitespaces"}

Response Codes

Status

Sub code

Message

SUCCESS

200

Transfer completed successfully

SUCCESS

201

Transfer Scheduled for next working day

PENDING

201

Awaiting confirmation from beneficiary bank

PENDING

201

Transfer request pending at the bank

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

403

This feature is not available for your account

ERROR

403

Transfer mode is not available for your account

ERROR

412

Token missing in the request

ERROR

412

beneId missing in the request

ERROR

412

amount missing in the request

ERROR

412

transferId missing in the request

ERROR

422

Invalid amount passed

ERROR

422

Invalid transferId passed

ERROR

422

No Payee Virtual Address associated with the beneficiary

ERROR

422

Remarks can have only numbers, alphabets and whitespaces

ERROR

409

Transfer Id already exists

ERROR

404

Beneficiary does not exist

ERROR

422

Beneficiary details not valid

ERROR

422

No Bank account or Ifsc associated with the beneficiary

ERROR

412

Not enough available balance in the account

ERROR

412

Please wait 30 minutes after adding the beneficiary

ERROR

412

Transfer amount is less than minimum amount of Rs.100

ERROR

412

Transfer amount is greater than the maximum amount of Rs.100000

ERROR

422

Invalid ifsc code provided for bank account

ERROR

422

Invalid bank account number or ifsc provided

ERROR

422

Transfer request to paytm wallet failed

ERROR

400/520

Transfer attempt failed at the bank

ERROR

520

Transfer request triggered.No response from bank

ERROR

403

Transfer to this beneficiary not allowed

ERROR

412

Transfer limit for beneficiary exceeded

ERROR

412

Transfer limit for your account exceeded

ERROR

412

Invalid transfer mode passed in the request

ERROR

412

Transfer mode not enabled for the account

ERROR

412

Invalid Tag passed in the request

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
​
const response = await Transfers.RequestTransfer({
"beneId": "JOHN18011",
"transferId": "tranfer001234",
"amount": "1.00",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.transfers import Transfers
​
tnx_req = Transfers.request_transfer(beneId="JOHN18011", amount="100.1", transferId="DEC2017", transferMode="banktransfer", remarks="Test transfer")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Transfers;
import com.cashfree.lib.domains.request.BatchTransferRequest;
import com.cashfree.lib.domains.request.RequestTransferRequest;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Transfers transfer = new Transfers(payouts);
​
RequestTransferRequest request = new RequestTransferRequest()
.setBeneId("JOHN18011")
.setAmount(new BigDecimal("1.00"))
.setTransferId("javasdktestJAN2019");
transfers.requestTransfer(request);
}
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/requestTransfer' \
-H 'Authorization: Bearer {{Token}}' \
-d '{
"beneId": "JOHN18011",
"amount": "1.00",
"transferId": "JUNOB2018"
}'

​

This API gives responses other than SUCCESS and ERROR. Please look at the list of transfer statuses here.

post
Standard transfer async

/payout/v1/requestAsyncTransfer
Request an amount transfer at Cashfree by providing beneficiary id, amount, and transfer id. This is an async transfer request. Once you trigger the requestAsyncTransfer API, Cashfree verifies your request and returns the Cashfree referenceId. The transfer to beneficiary account will be attempted within the next 60 seconds and you may query the transfer status after 60 seconds. This API is ideal if you want to process very high volumes through Cashfree. Benefits: 1. The API response is much faster for the async transfer endpoint. The async transfer response takes <100 ms as compared to a median value of 2-5 sec for the sync payout transfer API. 2. The asynchronous API can handle a higher TPM (transactions per minute) as compared to the synchronous API. The async API allows us to handle up to 1000 transactions per minute.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
beneId
required
string
Beneficiary Id, alphanumeric allowed
amount
required
string
Amount to be transferred, decimal (>= 1.00)
transferId
required
string
A unique id to identify this transfer, alphanumeric and underscore (_) allowed (40 character limit)
transferMode
optional
string
Mode of transfer, banktransfer by default. Allowed values are banktransfer, upi, paytm, amazonpay, and card
remarks
optional
string
Additional remarks, if any. alphanumeric and white spaces allowed (70 characters limit)
Response
200: OK
Response
{
"status": "ACCEPTED",
"subCode": "201",
"message": "Transfer Initiated",
"data": {
"referenceId": "107260"
}
}
422: Unprocessable Entity
Response
{"status":"ERROR",
"subCode":"422",
"message":"Remarks is invalid"}

Response Codes

Status

Sub code

Message

SUCCESS

200

Transfer completed successfully

SUCCESS

201

Transfer Scheduled for next working day

PENDING

201

Awaiting confirmation from beneficiary bank

PENDING

201

Transfer request pending at the bank

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

403

This feature is not available for your account

ERROR

403

Transfer mode is not available for your account

ERROR

412

Token missing in the request

ERROR

412

beneId missing in the request

ERROR

412

amount missing in the request

ERROR

412

transferId missing in the request

ERROR

422

Invalid amount passed

ERROR

422

Invalid transferId passed

ERROR

422

No Payee Virtual Address associated with the beneficiary

ERROR

422

Remarks can have only numbers, alphabets and whitespaces

ERROR

409

Transfer Id already exists

ERROR

404

Beneficiary does not exist

ERROR

422

Beneficiary details not valid

ERROR

422

No Bank account or Ifsc associated with the beneficiary

ERROR

412

Not enough available balance in the account

ERROR

412

Please wait 30 minutes after adding the beneficiary

ERROR

412

Transfer amount is less than minimum amount of Rs.100

ERROR

412

Transfer amount is greater than the maximum amount of Rs.100000

ERROR

422

Invalid ifsc code provided for bank account

ERROR

422

Invalid bank account number or ifsc provided

ERROR

422

Transfer request to paytm wallet failed

ERROR

400/520

Transfer attempt failed at the bank

ERROR

520

Transfer request triggered.No response from bank

ERROR

403

Transfer to this beneficiary not allowed

ERROR

412

Transfer limit for beneficiary exceeded

ERROR

412

Transfer limit for your account exceeded

ERROR

412

Invalid transfer mode passed in the request

ERROR

412

Transfer mode not enabled for the account

ERROR

412

Invalid Tag passed in the request

Curl
Curl
curl -X POST \
'http://{{Host%20Url}}/payout/v1/requestAsyncTransfer' \
-H 'Authorization: Bearer {{Token}}' \
-d '{
"beneId": "JOHN18011343",
"amount": "1.00",
"transferId": "JUNOB2018"
}'

get
Get transfer status

/payout/v1/getTransferStatus
Get details of a particular transfer. You can either pass referenceId or transferId to fetch the details.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
referenceId
optional
string
referenceId of the transaction
transferId
optional
string
transferId of the transaction One of the query parameters has to be used.
Response
200: OK
{"status": "SUCCESS",
"subCode": "200",
"message": "Details of transfer with transferId 159381033b123",
"data": {"transfer":
{ "referenceId": 17073,
"bankAccount": "026291800001191",
"beneId": "ABCD_123",
"amount": "20.00",
"status": "SUCCESS",
"utr": "1387420170430008800069857",
"addedOn": "2017Β­-01Β­-07 20:09:59",
"processedOn": "2017Β­-01Β­-07 20:10:05",
"acknowledged": 1 }}}
404: Not Found
{"status":"ERROR",
"subCode":"404",
"message":"referenceId is invalid or doesnot exist"}

Response Codes

Status

Sub Code

Message

SUCCESS

200

Details of transfer with referenceId (or transferId) XXXX

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

404

referenceId is invalid or does not exist

ERROR

404

transferId is invalid or does not exist

ERROR

422

Please provide referenceId or transferId to fetch details

ERROR

520

Unknown error occurred

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
​
const response = await Transfers.GetTransferStatus({
"transferId": "tranfer001234",
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.transfers import Transfers
​
tnx_stats = Transfers.get_transfer_status(referenceId="14057")
//
tnx_stats = Transfers.get_transfer_status(transferId="JUNOB2018")
Java
import com.cashfree.lib.clients.Payouts;
import com.cashfree.lib.clients.Transfers;
import com.cashfree.lib.domains.request.BatchTransferRequest;
import com.cashfree.lib.domains.request.RequestTransferRequest;
​
public static void main(){
​
Payouts payouts = Payouts.getInstance(
Environment.PRODUCTION, "<client_id>", "<client_secret>");
payouts.init();
Transfers transfer = new Transfers(payouts);
transfers.getTransferStatus("83345068", null);
}
Curl
curl -X GET \
'http://{{Host%20Url}}?referenceId=14057&transferId=JUNOB2018' \
-H 'Authorization: Bearer {{Token}}' \

Transfers can have multiple statuses, along with SUCCESS and ERROR. Please look at the list of transfer statuses here.

post
Batch transfer

/payout/v1/requestBatchTransfer
API to create multiple transfers to multiple beneficiaries. This API accepts an array of transfer objects under the batch field.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Body Parameters
batchTransferId
required
string
Unique Id of the Batch Transfer, alphanumeric and underscore allowed (60 character limit)
batchFormat
required
string
format of the batch transfers, valid values are: BENEFICIARY_ID: With this value, beneId and transferMode must be passed in the transfer object within the batch array alphanumeric and underscore allowed (60 character limit) If batchFormat is set to any of the below values, transfers will only be processed via specified mode. BANK_ACCOUNT: With this value, Additional details such as bankAccount, ifsc, name, email, phone must be passed in the transfer object within the batch array UPI: With this value, Additional details such as vpa, name, email, phone must be passed in the transfer object within the batch array PAYTM: With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array AMAZONPAY: With this value, Additional details such as name, email, phone must be passed in the transfer object within the batch array
deleteBene
optional
boolean
Flag to delete and read new beneficiaries if a beneficiary with the same Beneficiary Id is available. When the batch transfer format is BANK_ACCOUNT
batch
required
array
An array of transfer objects
Response
200: OK
Request body For Bank Account(Authorization Bearer token in header)
Batch_Format: "BANK_ACCOUNT"
{"batchTransferId" : "Test_Bank_Account_Format_45",
"batchFormat": "BANK_ACCOUNT" ,
"deleteBene" : 1,
"batch" : [
{"transferId" : "PTM_00121241112",
"amount" : "12",
"phone" : "9999999999",
"bankAccount" : "9999999999" ,
"ifsc" : "PYTM0_000001",
"email" : "johndoe@cashfree.com",
"name": "John Doe"},
{"transferId" : "PTM_00052312126",
"amount" : "12",
"phone" : "9999999999",
"bankAccount" : "9999999999" ,
"ifsc" : "PYTM0000001",
"email" : "johndoe@cashfree.com",
"name": "John Doe" }
]
}
​
Response
{ "status": SUCCESS,
"subCode": "200",
"message": "Request accepted",
"data": { "referenceId": 1594 }}
​
Request body for Beneficiary(Authorization Bearer token in header)
Batch_Format: "BENEFICIARY_ID"
{"batchTransferId" : "Test_Beneficiary_Format_45",
"batchFormat":"BENEFICIARY_ID",
"batch" : [
{"transferId" : "PTM_00121241112",
"amount" : "12","beneId" :
"b01" ,
"remarks" : "working"}
]
}
​
OR ( Amazon Pay batch transfer with beneId already present )
​
Batch_Format: "BENEFICIARY_ID"
{"batchTransferId": "test_batch_format_12",
"batchFormat": "BENEFICIARY_ID",
"batch": [{
"beneId": "JOHN180123",
"transferId": "tranfer001234",
"amount": "1",
"transferMode": "amazonpay"
}]
}
​
Response
{ "status": "SUCCESS",
"subCode": "200",
"message": "Batch Transfer requested successfully. Please check later for processing status.",
"data": { "referenceId": 1594 }}
409: Conflict
{"status": "ERROR",
"subCode": "409",
"message": "Batch TransferId abc-12356 already exists"}
422: Unprocessable Entity
{ "status": "ERROR",
"subCode": "422",
"message": "Parameters missing in request" }

​

Transfer object fields

Field Name

Description

transferId

A unique transfer id.

amount

Amount to be transferred.

beneId

The id of the beneficiary, this field must be passed if the batch format option is BENEFICIARY_ID.

transferMode

Required only when batchFormat is set to BENEFICIARY_ID, mode of transfer for each transfer in batch needs to be set.

Allowed values are: banktransfer, upi, paytm, and amazonpay

bankAccount

Bank account number for payout, this field must be passed if the batch format option is BANK_ACCOUNT.

ifsc

IFSC of corresponding bank account, this field must be passed if the batch format option is BANK_ACCOUNT.

vpa[optional]

VPA of corresponding user, this field must be passed if the batch format option is UPI.

name

Name of the account holder, this field must be passed if the batch format option is BANK_ACCOUNT.

email[optional]

Email of the beneficiary, this field must be passed if the batch format option is BANK_ACCOUNT.

phone

The phone of the beneficiary, this field must be passed if the batch format option is BANK_ACCOUNT/PAYTM/AMAZONPAY

remarks[optional]

Remarks, if any.

Currently, batch transfer supports transfers to bank accounts, UPI, Paytm, and Amazon Pay. If the beneficiary object does not have valid details attached to it, the transfer fails.

Response Codes

Status

Sub Code

Message

SUCCESS

200

Batch Transfer requested successfully. Please check later for processing status.

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

520

Unknown error occurred at batchTransfer

ERROR

520

Batch Transfer request failed

ERROR

520

Error in batch transfer

ERROR

403

Permission Denied

ERROR

422

Batch transfer id is missing

ERROR

422

Batch format is missing

ERROR

409

Invalid Batch Format

ERROR

409

Batch TransferId already exists

ERROR

422

Invalid Batch Transfer Id provided

ERROR

422

Please provide at least one transfer entry

ERROR

422

The maximum number of entries allowed per file is 500, please try again.

ERROR

422

Transfer Parameters missing in the request

ERROR

520

Unknown error occurred

Node
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
​
const response = await Transfers.RequestBatchTransfer(
{batchTransferId : "Test_Bank_Account_Format_45",
batchFormat: "BANK_ACCOUNT" ,
deleteBene : 1,
batch : [
{transferId : "PTM_00121241112",
amount: "12",
phone : "9999999999",
bankAccount : "9999999999" ,
ifsc : "PYTM0_000001",
email : "johndoe@cashfree.com",
name: "John Doe"}
]
​

get
Get batch transfer status

/payout/v1/getBatchTransferStatus
Call this API to get the status of the Batch Transfer.
Request
Response
Request
Headers
Authorization
required
string
Bearer auth token
Content-Type
required
string
application/json
Query Parameters
batchTransferId
required
string
Batch Transfer Id to fetch the status
Response
200: OK
{"status" : "SUCCESS",
"subCode": "200",
"message": "Data retrieved successfully",
"data":{
"rowCount" : 2,
"referenceId" : 1582,
"transfers": [
{"beneId":"9999999999_18875",
"transferId":"PTM_00121241112",
"referenceId":1523969542,
"bankAccount":"9999999999",
"ifsc":"PYTM0000001", "amount":"12.00",
"remarks":"", "status":"SUCCESS",
"utr":"W1532082925", "addedOn":"2018-07-20",
"processedOn":"2018-07-20" },
{ "beneId":"9999999999_18875",
"transferId":"PTM_00052312126",
"referenceId":1523969543,
"bankAccount":"9999999999",
"ifsc":"PYTM0000001",
"amount":"12.00",
"remarks":"",
"status":"SUCCESS",
"utr":"W1532082926",
"addedOn":"2018-07-20",
"processedOn":"2018-07-20"}
]
}
}
​
​
{"status" :
"SUCCESS",
"subCode": "200",
"message": "Data retrieved successfully",
"data":{
"rowCount" : 2,
"referenceId" : 1582,
"transfers": [
{"beneId":"9999999999_18875",
"transferId":"PTM_00121241112",
"referenceId":1523969542,
"bankAccount":"9999999999",
"ifsc":"PYTM0000001",
"amount":"12.00",
"remarks":"",
"status":"SUCCESS",
"utr":"W1532082925",
"addedOn":"2018-07-20",
"processedOn":"2018-07-20" },
{ "beneId":"9999999999_18875",
"transferId":"PTM_00052312126",
"referenceId":1523969543,
"bankAccount":"9999999999",
"ifsc":"PYTM0000001",
"amount":"12.00",
"remarks":"",
"status":"SUCCESS",
"utr":"W1532082926",
"addedOn":"2018-07-20",
"processedOn":"2018-07-20"}
]
}
}
404: Not Found
{ "status": "ERROR",
"subCode": "404",
"message": "Batch Transfer Id does not exist" }

Response Codes

Status

Sub Code

Message

SUCCESS

200

Data retrieved successfully

PENDING

201

Entries are not processed yet

ERROR

403

Token is not valid

ERROR

403

IP not whitelisted

ERROR

412

Token missing in the request

ERROR

404

Bulk Transfer Id does not exist

ERROR

520

Error while fetching data

ERROR

520

Unknown error occured at batchTransfer

Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
​
const response = await Tranfers.GetBatchTransferStatus({<