> ## 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. # 模拟交易 · 概述 > DeCard 托管模式沙盒模拟接口总览页：4 个 simulation/ 接口（KYC 模拟令牌 / 充值模拟 / 授权模拟 v1·v2）覆盖「KYC → 充值 → 授权消费」最小完整流程，仅沙盒可用。 ## 上线前，先在沙盒验证完整流程 无需动用真实资金，也不会影响真实持卡人，您就能在沙盒中完成「KYC → 充值 → 授权消费」流程，提前验证 KYC、余额变动以及 Webhook / WebSocket 通知处理。作为持牌发卡机构并拥有自有 BIN，DCS 提供一组沙盒模拟接口，帮助您在接入卡组织前充分测试集成逻辑。 **模拟接口仅用于沙盒 / 非生产环境。** 全部 4 个 `simulation/*` 接口均归在「开放接口模拟器」组内，请勿在生产环境调用。 ## 可用模拟能力 DeCard 托管模式提供 **4 个模拟接口**，覆盖 3 类能力。逐接口的请求 / 响应详见后文「逐接口参考」。 | 能力 | 接口 | 模拟了什么 | 对应真实能力 | | ---------------------- | ------------------------------------------- | --------------------------------- | --------------------------------------------------------- | | **KYC 模拟令牌** | `POST /simulation/v1/generate-kyc-token` | 为指定用户生成一枚 KYC 模拟令牌，供沙盒走通 KYC 流程 | KYC / H5 引导页 | | **充值模拟（FOMO）** | `POST /simulation/v1/deposit` | 模拟一笔链上加密货币到账（FOMO 渠道），触发用户余额和充值流程 | 加密货币充值 | | **授权模拟（消费 / 退货 / 冲正）** | `POST /simulation/v2/fund-auth`（用 `cardId`） | 模拟一笔卡授权请求，可选消费 / 退货 / 消费冲正 | [授权交易](../managing-transactions/authorizing-transactions) | 沙盒模拟接口与影响范围 沙盒模拟接口与影响范围 > DeCard 托管模式没有链上抵押（collateral）与支付路由（transfer）概念，故**不提供**对应的 `collateral-funding` / `transfer-transactions` 模拟；授权流程在系统内一次性完成，也**不提供**独立的 `settlement` / `authorization-updates` / `authorization-reversals` / `3ds-challenges` 模拟接口。需要测试这些场景时，见下方「模拟范围说明」。 ## 前置条件 | 前置项 | 说明 | 谁做 | | ---------------------- | --------------------------------------------------------------------------------------------------- | ------ | | 沙盒 API 密钥 | `ApiKey` + `SecretKey`，用于鉴权（`X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN`） | DCS 提供 | | 一个已注册用户 | 先在沙盒走通用户注册，拿到 `externalUserId` | 接入机构 | | 一张可用的卡 | 用模拟 KYC 令牌走通 KYC，再申请卡，拿到 `cardId` | 接入机构 | | Webhook / WebSocket 订阅 | 配好回调与实时推送，以便观察模拟产生的事件 | 接入机构 | * 您已开通企业（Enterprise）账户。如尚未获取密钥，请参考 [前置准备](../../getting-started/first-steps) 与 [鉴权指南](../../integration-resources/overview)。 * 所有请求须按鉴权指南携带签名头。本页 curl 示例省略部分头部细节，只聚焦业务字段与沙盒地址。 * **所有示例中的 `externalUserId`、`cardId`、卡号后 4 位、充值地址、令牌、`YOUR_API_KEY` 均为占位 / 脱敏值，请勿在请求或日志中写入任何真实终端用户 PII 或真实密钥。** ## 沙盒环境地址 | 环境 | Base URL | | ---- | ----------------------------------- | | 沙盒环境 | `https://api.thedecard-sandbox.com` | | 生产环境 | `https://api.thedecard.com` | > 模拟接口仅在**沙盒环境**可用。 ## 开始模拟 1. **获取沙盒访问权限。** 向 DCS 申请沙盒 `ApiKey` / `SecretKey`。模拟接口仅在沙盒环境可用。 2. **造一个测试用户与测试卡。** 用 `POST /simulation/v1/generate-kyc-token` 为用户生成 KYC 模拟令牌，走通 KYC 后申请卡，拿到 `cardId`。详见 [用户注册](../signing-up-a-customer/overview) 与 [卡管理 · 申请卡](../managing-cards/issuing-cards)。 3. **配好 Webhook 与 WebSocket。** 模拟会触发与真实交易同样的事件推送，配好接收端便于观察。见 [Webhook 与 WebSocket](../../integration-resources/webhook-websocket)。 4. **发起模拟。** 先用 `POST /simulation/v1/deposit` 模拟一笔充值到账，再用 `POST /simulation/v2/fund-auth` 模拟一笔消费，观察余额与流水变化。 ## 逐接口参考 > 所有接口共用全站统一响应结构 `{ code, message, messageDetail, data }`——**无 `success` 布尔字段**；成功码字面量 `code = SYS_SUCCESS`。判断请求是否被成功受理以 `code == SYS_SUCCESS` 为准，业务结果以 `data` 内字段为准。`messageDetail` 为面向终端用户的提示对象，包含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl` 七个可选子字段；通常各子字段为空字符串。 ### 一 · 生成 KYC 模拟令牌 为指定用户生成一枚 KYC 模拟令牌，供沙盒走通 KYC 流程。 ``` POST /simulation/v1/generate-kyc-token ``` ```json theme={null} { "externalUserId": "usr_xxxxxxxx" } ``` | 字段 | 类型 | 必填 | 说明 | | ---------------- | ------ | -- | ------- | | `externalUserId` | string | 是 | 外部用户 ID | 成功响应： ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": { "token": "" } } ``` | 字段 | 说明 | | ------------ | ----------------------- | | `data.token` | KYC 模拟令牌，用于在沙盒走通 KYC 流程 | ### 二 · 模拟充值（FOMO 渠道） 模拟一笔链上加密货币到账（FOMO 渠道），相当于在沙盒中模拟一次充值地址收款，从而触发用户余额和充值流程。**这是模拟链上到账，不是法币充值。** ``` POST /simulation/v1/deposit ``` ```json theme={null} { "chain": "Polygon", "currency": "USDC", "amount": 100.0, "address": "<链上充值地址>" } ``` | 字段 | 类型 | 必填 | 说明 | | ---------- | ------ | -- | ------------------------------------------------------------------------------------------------------------------- | | `chain` | string | 是 | 链名称，取值 `Ethereum` / `SOL` / `BASE` / `Polygon` / `TRON` | | `currency` | string | 是 | 币种，取值 `USDC` / `USDT` | | `amount` | number | 是 | 充值金额（小数形式） | | `address` | string | 是 | 充值地址。地址格式随 `chain` 不同：EVM 链（Ethereum/Polygon/BASE）以 `0x` 开头；Solana（`SOL`）为 base58 格式；TRON 以 `T` 开头。请填入用户在该链上的实际充值地址 | 本接口支持的网络和币种以本表为准：**5 个网络（Ethereum / SOL / BASE / Polygon / TRON）× 2 种稳定币（USDC / USDT）**。该表适用于沙盒模拟，可能与生产环境的支持范围不同。真实充值地址、网络与币种配置属于「资金充提 · 加密货币充值」组，本页不展开。 成功响应（无业务数据，`data` 为 `null`）： ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": null } ``` ### 三 · 模拟授权（消费 / 退货 / 冲正） 模拟一笔卡授权请求。DeCard 托管模式用**单个 `fund-auth` 接口 + `authType` 枚举**覆盖消费、退货、消费冲正三种场景。 卡片以 `cardId` 精确定位（不使用卡号后 4 位——同一用户名下后 4 位可能重复，存在歧义）。 **请求：** ``` POST /simulation/v2/fund-auth ``` ```json theme={null} { "externalUserId": "usr_xxxxxxxx", "cardId": "card_xxxxxxxx", "authType": "EXPEND", "amount": 12.50, "currency": "USD" } ``` | 字段 | 类型 | 必填 | 说明 | | ---------------- | ------ | -- | -------------------------------------------------- | | `externalUserId` | string | 是 | 外部用户 ID | | `cardId` | string | 是 | 卡 ID | | `authType` | string | 是 | 授权类型（见下表枚举） | | `amount` | number | 是 | 金额（小数形式），单位为元 / 美元 / 新币等 | | `currency` | string | 是 | 交易币种，常规币种如 `USD` / `RMB` / `SGD` / `EUR` / `JPY` 等 | **`authType` 枚举：** | 值 | 含义 | | ---------- | ---- | | `EXPEND` | 消费 | | `REFUND` | 退货 | | `REVERSAL` | 消费冲正 | > DeCard 托管模式通过这一个 `fund-auth` 接口 + `authType` 覆盖消费 / 退货 / 冲正，**没有**独立的清算（settlement）、授权冲正（reversal）、授权更新(authorization-update)等接口；`settle` / `reverse-hold` / `partial-reversal` / `tip-update` 等概念在 DeCard 托管模式中不存在。 成功响应： ```json theme={null} { "code": "SYS_SUCCESS", "message": null, "messageDetail": {}, "data": { "approved": false, "errorCode": "<拒绝时的错误码>" } } ``` | 字段 | 类型 | 说明 | | ---------------- | ------- | ------------ | | `data.approved` | boolean | 是否授权通过 | | `data.errorCode` | string | 错误码（授权被拒时返回） | `code == SYS_SUCCESS` 仅表示模拟请求被正确受理，**不代表授权通过**——授权业务结果须看 `data.approved`。 ## 常见模拟组合 ### 完成「充值 → 消费 → 查余额」最小流程 ```bash theme={null} # 1. 模拟一笔链上充值到账（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. 模拟一笔消费授权 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. 查询用户余额，确认可用/冻结余额已按预期变化 # 见「用户余额」页：user-asset 接口 ``` ### 测试退货与冲正 把第 2 步的 `authType` 换成 `REFUND`（退货）或 `REVERSAL`（消费冲正），重复调用并观察余额与流水的反向变化，以验证您的系统在这些场景下的状态流转是否正确。 ## 模拟范围说明 * **授权在系统内一次性完成**——不提供独立的清算 / 授权更新 / 授权冲正模拟接口；消费 / 退货 / 冲正全部由 `fund-auth` 的 `authType` 表达。 * **不涉及链上抵押与支付路由**——不提供相关模拟接口。 * **3DS 认证在发卡侧完成**，不提供独立的 3DS 模拟接口；需要测试 3DS 处理时，见 [3DS 转发](../managing-transactions/3ds-forwarding)。 ## 下一步 * 理解授权在系统内如何决策与占用余额，见 [授权交易](../managing-transactions/authorizing-transactions)。 * 查看模拟充值 / 消费后用户余额（`availableBalance` / `frozenBalance`）的变化，见 [用户余额](../managing-transactions/user-balance)。 * 真实的链上充值地址、链与币种配置，见 [加密货币充值](../virtual-accounts/crypto-deposit)。 * KYC 令牌在真实流程中的用法，见[接入资源 · 概述](../../integration-resources/overview)。