Skip to main content
POST
/
simulate
curl --request POST \
  --url https://sandbox.cashfree.com/pg/simulate \
  --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 '
{
  "entity": "PAYMENTS",
  "entity_id": "14934289844",
  "entity_simulation": {
    "payment_status": "FAILED",
    "payment_error_code": "ISSUER_NOT_AVAILABLE"
  }
}
'
{
  "entity": "PAYMENTS",
  "entity_id": "14934289844",
  "simulation_id": "sim_testmerchantid12340",
  "entity_simulation": {
    "payment_status": "FAILED",
    "payment_error_code": "ISSUER_NOT_AVAILABLE"
  }
}

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.

​
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

Request parameters to simulate payment.

​
entity
enum<string>
required

Entity type should be PAYMENTS, SUBS_PAYMENTS, SUBS_EXECUTION, SUBS_RESCHEDULE, or VBA_TRANSFER only.

Available options:
PAYMENTS,
SUBS_PAYMENTS,
SUBS_EXECUTION,
SUBS_RESCHEDULE,
VBA_TRANSFER
​
entity_id
string
required

If the entity type is PAYMENTS, the entity_id will be the cf_payment_id. If the entity type is SUBS_PAYMENTS, the entity_id will be the payment_id. If the entity type is SUBS_EXECUTION, the entity_id will be the execution_id. If the entity type is SUBS_RESCHEDULE, the entity_id will be the merchant transaction ID of the charge. If the entity type is VBA_TRANSFER, the entity_id will be the vba_account_number.

​
entity_simulation
entity_simulation · object

Entity simulation contains payment_status and payment_error_code. For SUBS_EXECUTION, payment_status supports SUCCESS or FAILED only, and payment_error_code is required when the status is FAILED.

Example:
{
  "payment_status": "FAILED",
  "payment_error_code": "ISSUER_NOT_AVAILABLE"
}
​
vba_simulation
vba_simulation · object

VBA simulation contains VBA and remitter information for simulation.

Example:
{
  "vba_ifsc": "YESB0CMSNOC",
  "utr": "utr",
  "amount": 10,
  "remitter_account": "808081pxqp242614HW",
  "remitter_ifsc": "IFSC",
  "remitter_name": "Test",
  "phone": "1234567891"
}

Response

Success response for simulating payment.

Payment simulation response.

​
simulation_id
string
​
entity
string
​
entity_id
string
​
entity_simulation
entity_simulation · object

Entity simulation contains payment_status and payment_error_code.

Example:
{
  "payment_status": "FAILED",
  "payment_error_code": "ISSUER_NOT_AVAILABLE"
}