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.

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"}
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"}
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"}
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"}
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"
} '

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.
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"}
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.
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"}
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
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"}

One of the Query Parameters has to be used.

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.

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" }
Node
Python
Java
Curl
Node
const cfSdk = require('cashfree-sdk');
const {Transfers} = cfSdk.Payouts;
​
const response = await Tranfers.GetBatchTransferStatus({
batchTransferId:Test_Bank_Account_Format_45"
});
Python
from cashfree_sdk.payouts import Payouts
from cashfree_sdk.payouts.transfers import Transfers
​
status = Transfers.get_batch_transfer_status(batchTransferId="Test_Bank_Account_Format_45")
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.getBatchTransferStatus("javasdkbatch12");
}
Curl
curl -X GET \
'http://{{Host%20Url}}/payout/v1/getBatchTransferStatus?batchTransferId=test_batch_format_01' \
-H 'Authorization: Bearer {{Token}}' \

​