Skip to main content
POST
/
simulate
/
settlement
curl --request POST \
  --url https://sandbox.cashfree.com/pg/simulate/settlement \
  --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 '{
  "merchantOrderIds": [
    "7b6bd177-ce98-43bd-b4b2-0d341fbb0d63",
    "7b6bd2b7-c8h8-43bd-7g2h-9hc98h3482h2",
    "99bfb2b7-c8h8-0hbd-7g93-9uw9hg93bh93"
  ],
  "status": "SUCCESS"
}'
{
  "simulation_id": "sim_103332852xk16dlG9zsoySmOVWTUW2t7FDv",
  "entity": "SETTLEMENTS",
  "settlement_ids": [
    "14934289844"
  ],
  "simulation_status": "SUCCESS"
}

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:2025-01-01
required

API version to be used. Format is in YYYY-MM-DD.

ā€‹
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.

ā€‹
x-idempotency-key
string<UUID>

An idempotency key is a unique identifier you include with your API call. If the request fails or times out, you can safely retry it using the same key to avoid duplicate actions.

Body

application/json

The request body for simulating a settlement.

Object to simulate a settlement request.

ā€‹
status
enum<string>
required

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

Available options:
SUCCESS,
FAILED,
PENDING
ā€‹
merchantOrderIds
string[]

A list of orders for which you want to simulate settlement.

ā€‹
txnTime
string<ISO8601>

The start time (YYYY-MM-DD HH:mm:ss) from which transactions are picked for simulating settlement. You can pass a txnTime value for up to the last seven days.

ā€‹
errorReason
enum<string>

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

Available options:
"Due to some technical issues, your amount will be settled in the next settlement cycle.",
"Due to some technical issues, your amount will be settled in the next settlement cycle.",
"Bank account details you have provided is not active, write to care@cashfree.com with the updated account details.",
"Due to some technical issues at the bank, your amount will be settled in the next settlement cycle.",
"Beneficiary name you have provided is incorrect, write to care@cashfree.com with the updated details.",
"Unable to settle amount to this beneficiary account, write to care@cashfree.com with the updated account details.",
"Bank account details you have provided are invalid, write to care@cashfree.com with the updated account details.",
"The IFSC you have provided for the bank account is invalid, write to care@cashfree.com with the valid IFSC."

Response

Settlement simulation response.

Object to simulate a settlement request.

ā€‹
simulation_id
string

A unique identifier for the simulation request.

ā€‹
entity
string

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

ā€‹
settlement_ids
number[]

List of simulated settlement IDs.

ā€‹
simulation_status
string

Status of the simulation request. Example: "SUCCESS/FAILED/PENDING".