Order status simulation

The TransFi Sandbox includes a set of Simulation APIs that let you drive your integration end-to-end without waiting for real-world events. You can call a simulation endpoint to instantly move an order to any target status — and have the corresponding webhook fired automatically.

Note: All simulation endpoints are strictly for the Sandbox environment and require a valid MID header in every request.

Simulate Order Status Update

Use this endpoint to move an existing order (or prefund) to a target status. The update is accepted asynchronously — your request returns immediately with a 202 Accepted, and the status transitions (including any intermediate states) are applied in the background with webhooks fired at each step.

Request

curl --location 'https://sandbox-api.transfi.com/v3/simulation/order' \
--header 'MID: YOUR_MID' \
--header 'Content-Type: application/json' \
--header 'Authorization: ******' \
--data '{
    "orderId": "OR-2603130504320558904",
    "status": "fund_settled"
}'

Request Parameters

Parameter	Type	Required	Description
`orderId`	String	Yes	The ID of the order or prefund to update. Prefund IDs begin with `PF-`; order IDs begin with `OR-`.
`status`	String	Yes	The target status to simulate. See the table below for allowed values per order type.
`errorCode`	String	No	An optional error code to attach when simulating a failure or review status. See error code table.

Allowed Statuses by Order Type

The statuses you can simulate depend on the order's type and fund flow. The simulation engine automatically fires all intermediate status events to reach the target state.

Order Type	Fund Flow	Allowed Target Statuses
`payin`	`fiat`	`fund_settled`, `fund_failed`, `manual_review`, `expired`
`gaming`	`fiat`	`fund_settled`, `completed`, `fund_failed`, `manual_review`, `expired`
`payout`	`fiat`	`fund_settled`, `fund_failed`, `manual_review`
`fiat_prefund`	—	`fund_settled`, `completed`, `fund_failed`, `manual_review`, `expired`
`payin`	`crypto`	`asset_settled`, `expired`
`payout`	`crypto`	`asset_deposited`
`crypto_prefund`	—	`completed`, `expired`
`buy`	`fiat_to_crypto`	`fund_deposited`, `fund_deposit_failed`, `manual_review`, `asset_settled`, `asset_settle_failed`, `expired`
`sell`	`crypto_to_fiat`	`asset_deposited`, `fund_settled`, `fund_failed`, `manual_review`, `expired`
`swap`	`fiat_to_fiat`	`fund_deposited`, `fund_deposit_failed`, `manual_review`, `fund_settled`, `fund_failed`, `expired`
`swap`	`crypto_to_crypto`	`asset_deposited`, `asset_settled`, `asset_settle_failed`, `expired`

Gaming order types are not supported for simulation.

Allowed Error Codes

Error codes are only valid for certain failure and review statuses. Passing errorCode for any other status will return a 400 error. If you omit errorCode for a status that supports one, the default code listed below is used.

Error Code	Applicable Status	Description
`PAYMENT_NOT_COMPLETED`	`fund_deposit_failed`, `fund_failed`	User cancelled the payment or did not complete within the session.
`NAME_NOT_MATCHED`	`fund_deposit_failed`, `fund_failed`	User name on the sender's bank account did not match TransFi records.
`BEHAVIORAL_CHECK_FAILED`	`fund_deposit_failed`, `fund_failed`	Biometric check of the user's device failed.
`AMOUNT_MISMATCH`	`fund_deposit_failed`, `fund_failed`	The payment amount does not match the expected amount.
`AUTHENTICATION_FAILED`	`fund_deposit_failed`, `fund_failed`	User authentication failed.
`BANK_ACCOUNT_ALREADY_IN_USE`	`fund_deposit_failed`, `fund_failed`	This bank account is already linked to another user.
`BANK_UNDER_MAINTENANCE`	`fund_deposit_failed`, `fund_failed`	There was a technical issue with the bank.
`DECLINED_BY_BANK`	`fund_deposit_failed`, `fund_failed`	Bank declined the transaction.
`INVALID_ACCOUNT_DETAILS`	`fund_deposit_failed`, `fund_failed`	The provided account details are invalid.
`OTHERS`	`fund_deposit_failed`, `fund_failed`	An unexpected error occurred.
`TRANSACTION_FAILED`	`asset_settle_failed`	Transaction has failed.
`VALIDATION_FAILED`	`asset_settle_failed`	Validation has failed for the transaction.
`OTHERS`	`asset_settle_failed`	An unexpected error occurred.
`BEHAVIORAL_CHECK_IN_REVIEW`	`manual_review`	Biometric check of the user's device is under review.
`NAME_NOT_MATCHED`	`manual_review`	User name on the sender's bank account did not match TransFi records.
`TRANSACTION_EXPIRED`	`expired`	Payment was not completed within the time limit.

Response

{
  "status": "success",
  "data": {
    "message": "Order status update accepted for processing",
    "code": "ORDER_STATUS_UPDATE_ACCEPTED"
  }
}

For the full API specification, see Simulate Order Status Update.