Simulate Vendor Settlement | Cashfree

curl --request POST \
  --url https://sandbox.cashfree.com/pg/simulate/settlement/vendor \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "merchant_vendor_id": "vendor-001",
  "txn_time": "2026-01-01 10:00:00",
  "status": "SUCCESS"
}
'

{
  "simulation_id": "sim_103332852xk16dlG9zsoySmOVWTUW2t7FDv",
  "entity": "VENDOR_SETTLEMENTS",
  "payout_ids": [
    14934289844
  ],
  "simulation_status": "SUCCESS"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "something_not_found",
  "type": "invalid_request_error"
}

{
  "message": "Too many requests from IP. Check headers",
  "code": "request_failed",
  "type": "rate_limit_error"
}

{
  "message": "internal Server Error",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "internal_error",
  "type": "api_error"
}

POST

/

simulate

/

settlement

/

vendor

curl --request POST \
  --url https://sandbox.cashfree.com/pg/simulate/settlement/vendor \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --header 'x-client-id: <api-key>' \
  --header 'x-client-secret: <api-key>' \
  --data '
{
  "merchant_vendor_id": "vendor-001",
  "txn_time": "2026-01-01 10:00:00",
  "status": "SUCCESS"
}
'

{
  "simulation_id": "sim_103332852xk16dlG9zsoySmOVWTUW2t7FDv",
  "entity": "VENDOR_SETTLEMENTS",
  "payout_ids": [
    14934289844
  ],
  "simulation_status": "SUCCESS"
}

{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}

{
  "message": "authentication Failed",
  "code": "request_failed",
  "type": "authentication_error"
}

{
  "message": "something is not found",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "something_not_found",
  "type": "invalid_request_error"
}

{
  "message": "Too many requests from IP. Check headers",
  "code": "request_failed",
  "type": "rate_limit_error"
}

{
  "message": "internal Server Error",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "internal_error",
  "type": "api_error"
}

Authorizations

x-client-id

string

header

required

Client app ID. You can find your app id in the Merchant Dashboard.

x-client-secret

string

header

required

Client secret key. You can find your secret key in the Merchant Dashboard.

Headers

x-api-version

string

default:2026-01-01

required

API version to be used.

x-request-id

string

Request ID for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to Cashfree.

Body

application/json

The request body for simulating an Easy Split vendor settlement.

Object to simulate an Easy Split vendor settlement.

merchant_vendor_id

string

required

The vendor for which you want to simulate a settlement.

status

enum<string>

required

The simulation status. Possible values are INITIATED, SUCCESS or FAILED.

Available options:

INITIATED,

SUCCESS,

FAILED

merchant_order_ids

string[]

A list of orders for which you want to simulate a vendor settlement. Provide either merchant_order_ids or txn_time. If you omit both, the API returns a 404 error instead of simulating a settlement.

txn_time

string

The start time in IST, in the format YYYY-MM-DD HH:mm:ss, from which vendor entries are picked for simulating settlement. Required when merchant_order_ids is not provided, and ignored when it is. Unlike the txnTime field on the Simulate Settlement API, this field has no 7-day limit. Only transactions strictly after this time match, so pass a value earlier than the transaction time. A value equal to the transaction time does not match.

error_reason

string

Specifies the reason for the settlement failure. Any string value is accepted. The default value is used if this is not provided. This is required only if the status is FAILED.

Response

Vendor settlement simulation response.

Object returned when simulating an Easy Split vendor settlement.

simulation_id

string

A unique identifier for the simulation request.

entity

string

Entity type for which the simulation is performed. Example: "VENDOR_SETTLEMENTS".

payout_ids

number[]

List of simulated vendor payout IDs.

simulation_status

string

Status of the simulation request. Possible values are INITIATED, SUCCESS and FAILED.