Easy Split API

Cashfree uses API keys to allow access to the API. Once you have signed up at our merchant site, you will be able to see your AppId and SecretKey.

Cashfree expects the API key to be included in all API requests to the server. Use the endpoint /api/v1/credentials/verify to verify your credentials. X-Client-Id is your appID, and X-Client-Secret is your secretKey. You can view these details here.

All API responses are in JSON format. POST requests should include ContentType: application/json

End Points

Environment

URL

Test

https://test.cashfree.com/

Production

https://api.cashfree.com/

Postman Collection

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

get
Settlement Cycles

/api/v2/easy-split/vendors/settlement-cycles
Use this API to get the settlement cycles approved for your EasySplit account, which you can assign to your vendors.
Request
Response
Request
Headers
x-client-id
required
string
Client app Id
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Response
200: OK
{
"status": "OK",
"message": "Settlement Cycles Fetched",
"settlementCycles":
[
{
"id": "3",
"desc": "All transactions from 4:30 PM T-1 to 10:30 AM T+0 settled at 11AM T+0, and, 10:30 AM T+0 to 4:30PM T+0 at 5:00PM T+0"
}
]
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/vendors/settlement-cycles' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'Content-Type: application/json'

post
Create Merchant Vendor

/api/v2/easy-split/vendors
Use this API to add vendor details to your EasySplit account. You can settle funds to vendors only after you have added the vendors to your account.
Request
Response
Request
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Body Parameters
email
required
string
Vendor email ID, string in email ID format (Ex:[email protected]) should contain @ and dot (.)
status
required
string
Status of vendor either ACTIVE or BLOCKED when you create the vendor.
bank
required
object
Bank or UPI is mandatory. Bank details of vendor: Account number - Beneficiary bank account number (9 - 18 alphanumeric character limit). Account holder - Beneficiary name, only alphabets and white space allowed (100 character limit). IFSC - Beneficiary account IFSC (standard IFSC format - length 11, first four bank IFSC and 5th digit must be 0). Account number, account holder name, and IFSC must be included in the bank object. "bank": { "accountNumber": "123456789", "accountHolder": "John Doe", "ifsc": "IFSC0000004" }
upi
required
object
Bank or UPI is mandatory. UPI details of vendor: Account holder - Beneficiary name, only alphabets and white space allowed (100 character limit). VPA - Beneficiary UPI VPA. Alphanumeric, dot (.), hyphen (-), at sign (@), and underscore (_) allowed (100 character limit). Note: underscore (_) and dot (.) gets accepted before and after @, but hyphen (-) is only accepted before @ sign. Account holder name and vpa must be included in the upi object. "upi": { "accountHolder": "John Doe", "vpa": "[email protected]" }
phone
required
string
Beneficiaries phone number, phone number registered in India (only digits, 8 - 12 characters after excluding +91)
name
required
string
Name of the vendor.
id
required
string
Unique Vendor ID to identify the beneficiary. Alphanumeric and underscore (_) allowed.
settlementCycleId
required
integer
Settlement cycle of a vendor (eligible cycle values to be derived from settlement cycles API).
Response
200: OK
{
"message": "Vendor is added successfully",
"status": "OK"
}

Sample Code

curl --location --request POST 'https://api.cashfree.com/api/v2/easy-split/vendors' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
"email": "[email protected]",
"status": "ACTIVE/BLOCKED",
"bank":
{
"accountNumber": "12345678890",
"accountHolder": "John Doe",
"ifsc": "HDFC019345"
},
"upi":
{
"accountHolder": "Account Holder Name"
},
"phone": "1234567890",
"name": "VendorName1",
"id": "merchantVendorId1",
"settlementCycleId": 123
}'

Response Code

Sub Code

Status

Message

400

ERROR

Email ID not specified.

400

ERROR

Enter valid email ID.

400

ERROR

Please provide a valid status.

400

ERROR

Account number not specified.

400

ERROR

Bank account number should contain 9 to 30 alphanumeric characters.

400

ERROR

IFSC not specified.

400

ERROR

Enter valid IFSC.

400

ERROR

VPA not specified.

400

ERROR

Account holder name not specified.

400

ERROR

Invalid account holder name. Account holder name should include alphabets only.

400

ERROR

Phone number not specified.

400

ERROR

Please provide a valid Phone number

400

ERROR

Please provide a valid name.

400

ERROR

Invalid Name. Name should include alphabets only.

400

ERROR

Please provide a valid id.

400

ERROR

VendorId not specified.

400

ERROR

Incorrect settlement cycle ID. Enter valid ID.

400

ERROR

Bank or UPI, only one can be passed and not both

400

ERROR

Vendor account number or UPI address is required.

400

ERROR

Merchant is not Active.

400

ERROR

VendorId already exists. Enter unique VendorId.

400

ERROR

Enter valid UPI VPA.

400

ERROR

Incorrect settlement cycle ID. Enter valid ID.

500

ERROR

Failed to validate VPA

get
All Merchant Vendors

/api/v2/easy-split/vendors
Use this API to get the details of all vendors associated with your EasySplit account.
Request
Response
Request
Headers
x-client-id
required
string
Client app ID.
x-client-secret
required
string
Client secret key.
Content-Type
required
string
application/json
Query Parameters
page
optional
integer
Specify the page number you want to see (Default value is 0)
size
optional
integer
Specify the page size (Default value is 20)
Response
200: OK
{
"message": "Vendor details",
"status": "OK",
"vendorDetails":
[
{
"id": "FinalVendor2",
"name": "Final Vendor",
"addedOn": "2021-05-21 11:19:03",
"status": "DELETED",
"balance": 0
},
{
"id": "FinalVendor1",
"name": "FinalVendor",
"addedOn": "2021-05-21 11:18:10",
"status": "ACTIVE",
"balance": 0
},
{
"id": "NAV4",
"name": "Test UPI Vendor",
"addedOn": "2021-05-21 00:45:27",
"status": "DELETED",
"balance": 0
}
],
"totalPages": 32,
"totalElements": 94,
"first": false,
"last": false
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/vendors?page={{x}}&size={{y}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientId}}' \
--header 'Content-Type: application/json'

get
Vendor Details

/api/v2/easy-split/vendors/{vendorId}
Use this API to get the details of a vendor associated with your EasySplit account.
Request
Response
Request
Path Parameters
vendorId
required
string
Valid vendorId
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Response
200: OK
{
"message": "Vendor details",
"status": "OK",
"vendorDetails":
{
"id": "bulkTest48",
"name": "Manideep",
"addedOn": "2021-05-11 13:59:56",
"status": "ACTIVE",
"email": "[email protected]",
"phone": "8281554863",
"settlementCycleId": 1,
"bank":
{
"accountNumber": "5402039817",
"accountHolder": "Manideep",
"ifsc": "CITI0000004"
},
"upi": null,
"balance": 0
}
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/vendors/{{vendorId}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientId}}' \
--header 'Content-Type: application/json'

Response Code

Sub Code

Status

Message

404

ERROR

Vendor does not exist

put
Update Merchant Vendor

/api/v2/easy-split/vendors/{vendorId}
Use this API to edit the vendor details added to your EasySplit account.
Request
Response
Request
Path Parameters
vendorId
required
string
Valid vendor ID (you cannot update details for deleted vendors)
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Body Parameters
email
optional
string
Vendor email, string in email Id format (Ex: [email protected]) - should contain @ and dot (.)
status
optional
string
Status can be ACTIVE, BLOCKED or DELETED
bank
optional
object
Bank details of the vendor
upi
optional
object
UPI details of the vendor
phone
optional
string
Beneficiaries phone number, phone number registered in India (only digits, 8 - 12 characters after excluding +91)
name
optional
string
Name of the vendor
settlementCycleId
optional
integer
Settlement cycle of a vendor (eligible cycle values to be derived from settlement cycles API).
Response
200: OK
{
"message": "Vendor is updated successfully",
"status": "OK"
}

Sample Code

curl --location --request PUT 'https://api.cashfree.com/api/v2/easy-split/vendors/{{vendorId}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'Content-Type: application/json' \
--data-raw '
{
"email": "[email protected]",
"status": "ACTIVE/BLOCKED/DELETED",
"bank":
{
"accountNumber": "12345678890",
"accountHolder": "John Doe",
"ifsc": "HDFC019345"
},
"upi" :
{
"accountHolder": "Account Holder Name"
},
"phone": "1234567890",
"name": "VendorName1",
"settlementCycleId": 123
}'

Response Codes

Sub Code

Status

Message

400

ERROR

Enter valid email ID.

400

ERROR

Please provide a valid status.

400

ERROR

Bank account number should contain 9 to 30 alphanumeric characters.

400

ERROR

Enter valid IFSC.

400

ERROR

Invalid account holder name. Account holder name should include alphabets only.

400

ERROR

Please provide a valid Phone number

400

ERROR

Invalid Name. Name should include alphabets only.

400

ERROR

VendorId not specified.

400

ERROR

Incorrect settlement cycle ID. Enter valid ID.

400

ERROR

Bank or UPI, only one can be passed and not both

400

ERROR

Merchant is not Active.

404

ERROR

Vendor does not exist

400

ERROR

Enter valid UPI VPA.

400

ERROR

Incorrect settlement cycle ID. Enter valid ID.

500

ERROR

Failed to validate VPA

400

ERROR

Unable to edit. VendorId is deleted.

get
Vendor's All Settlements

/api/v2/easy-split/vendors/{vendorId}/settlements
Use this API to get all the settlement details for a vendor. This will help in reconciliation.
Request
Response
Request
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Query Parameters
page
optional
integer
Specify the page number you want to see. (Default value is 0)
size
optional
integer
Specify the page size (Default value is 20)
Response
200: OK
{
"message": "Vendor settlements",
"status": "OK",
"settlements":
[
{
"settlementId": 81,
"totalTransactionAmount": 0,
"totalAdjustmentAmount": -2,
"settlementServiceCharge": 0.1,
"settlementServiceTax": 0.02,
"settlementAmount": -1,
"status": "SUCCESS",
"initiatedOn": "2021-05-15T11:00:12",
"updatedOn": "",
"utr": "000000"
},
{
"settlementId": 72,
"totalTransactionAmount": 0,
"totalAdjustmentAmount": -1,
"settlementServiceCharge": 0.1,
"settlementServiceTax": 0.02,
"settlementAmount": 0,
"status": "SUCCESS",
"initiatedOn": "2021-05-13T11:00:11",
"updatedOn": "",
"utr": "000000"
}
],
"totalPages": 3,
"totalElements": 5,
"first": true,
"last": false
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/vendors/{{vendorId}}/settlements?page={{x}}&size={{y}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientId}}' \
--header 'Content-Type: application/json'

Response Codes

Sub Code

Status

Message

404

ERROR

Enter valid Vendor ID.

404

ERROR

No settlements found for this Vendor ID

get
Settlement Details by OrderId

/api/v2/easy-split/orders/{orderId}
Use this API to get details of all the settled and unsettled transactions of each vendor which were part of a particular order.
Request
Response
Request
Path Parameters
orderId
required
string
Valid Order ID for which split and settlement details are to be fetched.
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Response
200: OK
{
"message": "Order settlement details for vendors",
"status": "OK",
"vendors":
[
{
"id": "CITI_Vendor",
"settlementId": 81,
"settlementAmount": 1.00
},
{
"id": "IOB_Vendor",
"settlementId": 82,
"settlementAmount": 1.00
}
]
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/orders/{{orderId}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientId}}' \
--header 'Content-Type: application/json'

Response Codes

Sub Code

Status

Message

404

OK

Enter valid Order ID.

404

OK

No split for this Order ID.

get
Vendor Settlement by SettlementId

/api/v2/easy-split/vendors/{vendorId}/settlements/{settlementId}
Use this API to get all the settlement details of a particular settlement ID. This will help in reconciliation.
Request
Response
Request
Path Parameters
vendorId
required
string
Valid vendor ID
settlementId
required
string
Settlement ID is associated with a settlement made to a vendor. Can be derived from the Vendor's All Settlement API.
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Content-Type
required
string
application/json
Response
200: OK
{
"message": "Vendor settlement",
"status": "OK",
"settlement":
{
"settlementId": 61,
"totalTransactionAmount": 0,
"totalAdjustmentAmount": -7.00,
"settlementServiceCharge": 0.10,
"settlementServiceTax": 0.02,
"settlementAmount": -2.00,
"status": "SUCCESS",
"initiatedOn": "2021-05-11T17:00:03",
"updatedOn": "",
"utr": "000000"
}
}

Sample Code

curl --location --request GET 'https://api.cashfree.com/api/v2/easy-split/vendors/{{vendorId}}/settlements/{{settlementId}}' \
--header 'x-client-id: {{clientId}}' \
--header 'x-client-secret: {{clientKey}}' \
--header 'Content-Type: application/json'

Response Codes

Sub Code

Status

Message

400

OK

Enter valid Settlement ID.

404

OK

Enter valid Vendor ID.

post
Create Refund

/api/v1/order/refund
Use this API to initiate refunds.
Request
Response
Request
Headers
x-client-id
required
string
Client app ID
x-client-secret
required
string
Client secret key
Body Parameters
referenceId
required
string
Cashfree reference ID
refundAmount
required
number
Amount to be refunded. Should be lesser than or equal to the transaction amount. (Decimals allowed)
refundNote
optional
string
A refund note for your reference
isSplit
optional
boolean
Flag to identify if refund must be split. Values = True or False
merchantRefundId
optional
string
A merchant generated unique key to identify this refund. Required if refundType is INSTANT.
refundType
optional
string
INSTANT for instant refunds
splitDetails
optional
string
Parameter to specify the split amount. Valid vendor ID and amount must be specified to process the split. [{"merchantVendorId":"Test_23","amount":2.50},{"merchantVendorId":"Test_24","amount":3.60}]
Response
200: OK
{
“message”: “Refund created successfully”,
“status”: OK
“refundId” : 123455678
}

Sample Code

curl --location --request POST 'https://api.cashfree.com/api/v1/order/refund' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'appId={{clientId}}' \
--data-urlencode 'secretKey={{clientKey}}' \
--data-urlencode 'referenceId=1618416289' \
--data-urlencode 'refundAmount=10.00' \
--data-urlencode 'refundNote=RefundNote' \
--data-urlencode 'isSplit=true' \
--data-urlencode 'merchantRefundId=6389' \
--data-urlencode 'refundType=STANDARD' \
--data-urlencode 'splitDetails=[{"merchantVendorId":"test_1","amount":2.50},{"merchantVendorId":"Test_23","amount":3.60}]'

Response Codes

Status Code

Status

Message

400

ERROR

Bad Request. Provide split information if isSplit = true

400

ERROR

Bad request. Format of splitDetails is incorrect

400

ERROR

Invalid Request as isSplit is not true but vendor split passed

400

ERROR

Vendor {vendorId} is in DELETED state. Exclude this vendor from split to process the refund

400

ERROR

Vendor {vendorId} was not part of sale transactions. Cannot process refund

400

ERROR

Bad Request. No split allowed on this sale transaction.

400

ERROR

Invalid VendorId {vendorId}

400

ERROR

Duplicate Merchant Refund Id

400

ERROR

Refunds for this payment mode are not supported

400

ERROR

Can't refund flagged transaction

400

ERROR

Total refund cannot be greater than the refundable amount

400

ERROR

Can't process this refund. Please check transaction status for this transaction.

400

ERROR

Refunds cannot be initiated after 180 days of the transaction. Contact [email protected] to process this refund via alternative means.

404

ERROR

Given referenceId was not found