> ## Documentation Index > Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt > Use this file to discover all available pages before exploring further. # Simulating Transactions · Overview > The overview of the sandbox simulation endpoints for the DeCard-Managed model: four simulation/ endpoints (KYC simulation token, deposit simulation, authorization simulation v1 and v2) that together cover the minimal KYC → deposit → authorized spend loop. Sandbox only. ## Exercise the whole flow in the sandbox before you go live Without moving real money or touching real cardholders, you can assemble a complete KYC → deposit → authorized spend flow in the sandbox and validate your integration logic ahead of time (the KYC flow, balance movements, Webhook and WebSocket delivery handling). As a licensed issuer with its own BINs, DCS provides a set of sandbox simulation endpoints so that your integration is solid well before it reaches the card networks. **The simulation endpoints are for sandbox and non-production environments only.** All four `simulation/*` endpoints belong to the "open API simulator" group; never call them in production. ## What you can simulate The DeCard-Managed model offers **four simulation endpoints** across three capabilities. Requests and responses for each are covered below in "Endpoint reference". | Capability | Endpoint | What it simulates | Real capability it maps to | | -------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **KYC simulation token** | `POST /simulation/v1/generate-kyc-token` | Issues a KYC simulation token for a given user so you can walk the KYC flow in the sandbox | KYC / H5 guidance page | | **Deposit simulation (FOMO)** | `POST /simulation/v1/deposit` | Simulates an on-chain crypto deposit arriving (FOMO channel), triggering the user balance and deposit flow | Crypto deposits | | **Authorization simulation (spend / refund / reversal)** | `POST /simulation/v2/fund-auth` (uses `cardId`) | Simulates a card authorization request, as a spend, a refund or a spend reversal | [Authorizing Transactions](../managing-transactions/authorizing-transactions) | Sandbox simulation endpoints and their effects Sandbox simulation endpoints and their effects > The DeCard-Managed model has no concept of on-chain collateral or payment routing (transfers), so there are **no** matching `collateral-funding` / `transfer-transactions` simulations. Authorization is decided in a single pass inside the system, so there are also **no** standalone `settlement` / `authorization-updates` / `authorization-reversals` / `3ds-challenges` simulation endpoints. For how to test those scenarios, see "What is out of scope" below. ## Prerequisites | Item | Description | Who provides it | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------- | | Sandbox API credentials | `ApiKey` + `SecretKey`, used for authentication (`X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN`) | DCS | | A registered user | Complete user registration in the sandbox first and keep the `externalUserId` | Partner | | A usable card | Walk KYC with the simulation token, then apply for a card and keep the `cardId` | Partner | | Webhook / WebSocket subscription | Configure callbacks and real-time delivery so you can observe the events the simulations produce | Partner | * Your Enterprise account is active. If you do not have credentials yet, see [First Steps](../../getting-started/first-steps) and the [authentication guide](../../integration-resources/overview). * Every request must carry the signature headers described in the authentication guide. The curl examples on this page omit some header details and focus on the business fields and the sandbox host. * **Every `externalUserId`, `cardId`, last-4 value, deposit address, token and `YOUR_API_KEY` in the examples is a placeholder or masked value. Never put real end-user PII or real keys into requests or logs.** ## Sandbox host | Environment | Base URL | | ----------- | ----------------------------------- | | Sandbox | `https://api.thedecard-sandbox.com` | | Production | `https://api.thedecard.com` | > The simulation endpoints exist in the **sandbox** only. ## Getting started 1. **Get sandbox access.** Request sandbox `ApiKey` / `SecretKey` from DCS. The simulation endpoints are available in the sandbox only. 2. **Create a test user and a test card.** Use `POST /simulation/v1/generate-kyc-token` to mint a KYC simulation token for the user, walk KYC, then apply for a card and keep the `cardId`. See [Signing Up a Customer](../signing-up-a-customer/overview) and [Managing Cards · Issuing Cards](../managing-cards/issuing-cards). 3. **Set up Webhook and WebSocket.** Simulations fire the same events as real transactions, so having your receivers ready makes them easy to observe. See [Webhook + WebSocket](../../integration-resources/webhook-websocket). 4. **Run the simulations.** Start with `POST /simulation/v1/deposit` to simulate an incoming deposit, then `POST /simulation/v2/fund-auth` to simulate a spend, and watch the balance and transaction records change. ## Endpoint reference > All endpoints share the site-wide response envelope `{ code, message, messageDetail, data }` — with **no `success` boolean**; the success code literal is `code = SYS_SUCCESS`. Use `code == SYS_SUCCESS` to decide whether the request was accepted, and the fields inside `data` to read the business outcome. `messageDetail` is an object intended for display to the end user, with seven optional sub-fields: `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`; usually each sub-field is an empty string. ### 1 · Generate a KYC simulation token Mints a KYC simulation token for a given user so you can walk the KYC flow in the sandbox. ``` POST /simulation/v1/generate-kyc-token ``` ```json theme={null} { "externalUserId": "usr_xxxxxxxx" } ``` | Field | Type | Required | Description | | ---------------- | ------ | -------- | ---------------- | | `externalUserId` | string | Yes | External user ID | Successful response: ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": { "token": "" } } ``` | Field | Description | | ------------ | -------------------------------------------------------------- | | `data.token` | KYC simulation token, used to walk the KYC flow in the sandbox | ### 2 · Simulate a deposit (FOMO channel) Simulates an on-chain crypto deposit arriving (FOMO channel), the sandbox equivalent of faking a payment into a deposit address, which triggers the user balance and deposit flow. **This simulates an on-chain arrival, not a fiat top-up.** ``` POST /simulation/v1/deposit ``` ```json theme={null} { "chain": "Polygon", "currency": "USDC", "amount": 100.0, "address": "" } ``` | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `chain` | string | Yes | Chain name, one of `Ethereum` / `SOL` / `BASE` / `Polygon` / `TRON` | | `currency` | string | Yes | Currency, either `USDC` or `USDT` | | `amount` | number | Yes | Deposit amount (decimal) | | `address` | string | Yes | Deposit address. The format depends on `chain`: EVM chains (Ethereum/Polygon/BASE) start with `0x`; Solana (`SOL`) is base58; TRON starts with `T`. Use the user's actual deposit address on that chain | The chain and token matrix supported by this endpoint is exactly the one in the table above: **5 chains (Ethereum / SOL / BASE / Polygon / TRON) × 2 stablecoins (USDC / USDT)**. This matrix describes sandbox simulation and may differ from production coverage. Real deposit addresses and the chain and currency configuration belong to the deposits and withdrawals area (crypto deposits) and are not covered here. Successful response (no business payload, `data` is `null`): ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": null } ``` ### 3 · Simulate an authorization (spend / refund / reversal) Simulates a card authorization request. The DeCard-Managed model covers spend, refund and spend reversal with **a single `fund-auth` endpoint plus the `authType` enum**. The card is identified precisely by `cardId` (not by the last 4 digits of the card number, which can be ambiguous when one user holds several cards). **Request:** ``` POST /simulation/v2/fund-auth ``` ```json theme={null} { "externalUserId": "usr_xxxxxxxx", "cardId": "card_xxxxxxxx", "authType": "EXPEND", "amount": 12.50, "currency": "USD" } ``` | Field | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------- | | `externalUserId` | string | Yes | External user ID | | `cardId` | string | Yes | Card ID | | `authType` | string | Yes | Authorization type (see the enum table below) | | `amount` | number | Yes | Amount (decimal), in major currency units | | `currency` | string | Yes | Transaction currency, a standard code such as `USD` / `RMB` / `SGD` / `EUR` / `JPY` | **`authType` enum:** | Value | Meaning | | ---------- | -------------- | | `EXPEND` | Spend | | `REFUND` | Refund | | `REVERSAL` | Spend reversal | > The DeCard-Managed model covers spend, refund and reversal through this one `fund-auth` endpoint plus `authType`. There are **no** separate settlement, authorization reversal or authorization update endpoints; concepts such as `settle` / `reverse-hold` / `partial-reversal` / `tip-update` do not exist in the DeCard-Managed model. Successful response: ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": { "approved": false, "errorCode": "" } } ``` | Field | Type | Description | | ---------------- | ------- | -------------------------------------------------------- | | `data.approved` | boolean | Whether the authorization was approved | | `data.errorCode` | string | Error code (returned when the authorization is declined) | `code == SYS_SUCCESS` only means the simulation request was accepted correctly; it **does not mean the authorization was approved**. Read `data.approved` for the authorization outcome. ## Common patterns ### Run the minimal deposit → spend → check balance loop ```bash theme={null} # 1. Simulate an on-chain deposit arriving (USDC on Polygon) curl -X POST https://api.thedecard-sandbox.com/simulation/v1/deposit \ -H "Content-Type: application/json" \ -H "X-DAPI-API-KEY: YOUR_API_KEY" \ -H "X-DAPI-TIMESTAMP: MILLIS_TIMESTAMP" \ -H "X-DAPI-SIGN: YOUR_SIGNATURE" \ -H "X-DAPI-NONCE: 12345" \ -d '{ "chain": "Polygon", "currency": "USDC", "amount": 100.0, "address": "" }' # 2. Simulate a spend authorization curl -X POST https://api.thedecard-sandbox.com/simulation/v2/fund-auth \ -H "Content-Type: application/json" \ -H "X-DAPI-API-KEY: YOUR_API_KEY" \ -H "X-DAPI-TIMESTAMP: 1760943263227" \ -H "X-DAPI-NONCE: 12346" \ -H "X-DAPI-SIGN: YOUR_SIGNATURE" \ -d '{ "externalUserId": "usr_xxxxxxxx", "cardId": "card_xxxxxxxx", "authType": "EXPEND", "amount": 12.50, "currency": "USD" }' # 3. Query the user balance and confirm available/frozen balances moved as expected # See the "User Balance" page: the user-asset endpoints ``` ### Test refunds and reversals Change `authType` in step 2 to `REFUND` (refund) or `REVERSAL` (spend reversal), repeat the call, and watch balances and transaction records move in the opposite direction. That confirms your system transitions state correctly in these scenarios. ## What is out of scope * **Authorization is decided in a single pass inside the system**, so there are no separate settlement, authorization update or authorization reversal simulation endpoints; spend, refund and reversal are all expressed through `authType` on `fund-auth`. * **On-chain collateral and payment routing are not involved**, so no simulation endpoints exist for them. * **3DS authentication is completed on the issuing side**, so there is no standalone 3DS simulation endpoint. To test 3DS handling, see [3DS Forwarding](../managing-transactions/3ds-forwarding). ## Next steps * To understand how authorization is decided and how it holds balance inside the system, see [Authorizing Transactions](../managing-transactions/authorizing-transactions). * To see how user balances (`availableBalance` / `frozenBalance`) move after a simulated deposit or spend, see [User Balance](../managing-transactions/user-balance). * For real on-chain deposit addresses and the chain and currency configuration, see [Crypto Deposit](../virtual-accounts/crypto-deposit). * For how the KYC token is used in the real flow, see [Authentication and Integration Resources](../../integration-resources/overview).