模拟交易 · 概述

​

上线前，先在沙盒验证完整流程

​

可用模拟能力

DeCard 托管模式没有链上抵押（collateral）与支付路由（transfer）概念，故不提供对应的 collateral-funding / transfer-transactions 模拟；授权流程在系统内一次性完成，也不提供独立的 settlement / authorization-updates / authorization-reversals / 3ds-challenges 模拟接口。需要测试这些场景时，见下方「模拟范围说明」。

​

前置条件

• 您已开通企业（Enterprise）账户。如尚未获取密钥，请参考 前置准备 与 鉴权指南。
• 所有请求须按鉴权指南携带签名头。本页 curl 示例省略部分头部细节，只聚焦业务字段与沙盒地址。
• 所有示例中的 externalUserId、cardId、卡号后 4 位、充值地址、令牌、YOUR_API_KEY 均为占位 / 脱敏值，请勿在请求或日志中写入任何真实终端用户 PII 或真实密钥。

​

沙盒环境地址

模拟接口仅在沙盒环境可用。

​

开始模拟

1. 获取沙盒访问权限。 向 DCS 申请沙盒 ApiKey / SecretKey。模拟接口仅在沙盒环境可用。
2. 造一个测试用户与测试卡。 用 POST /simulation/v1/generate-kyc-token 为用户生成 KYC 模拟令牌，走通 KYC 后申请卡，拿到 cardId。详见 用户注册 与 卡管理 · 申请卡。
3. 配好 Webhook 与 WebSocket。 模拟会触发与真实交易同样的事件推送，配好接收端便于观察。见 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 模拟令牌

POST /simulation/v1/generate-kyc-token

{
  "externalUserId": "usr_xxxxxxxx"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": {
    "token": "<KYC 模拟令牌>"
  }
}

​

二 · 模拟充值（FOMO 渠道）

POST /simulation/v1/deposit

{
  "chain": "Polygon",
  "currency": "USDC",
  "amount": 100.0,
  "address": "<链上充值地址>"
}

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": null
}

​

三 · 模拟授权（消费 / 退货 / 冲正）

POST /simulation/v2/fund-auth

{
  "externalUserId": "usr_xxxxxxxx",
  "cardId": "card_xxxxxxxx",
  "authType": "EXPEND",
  "amount": 12.50,
  "currency": "USD"
}

DeCard 托管模式通过这一个 fund-auth 接口 + authType 覆盖消费 / 退货 / 冲正，没有独立的清算（settlement）、授权冲正（reversal）、授权更新(authorization-update)等接口；settle / reverse-hold / partial-reversal / tip-update 等概念在 DeCard 托管模式中不存在。

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {},
  "data": {
    "approved": false,
    "errorCode": "<拒绝时的错误码>"
  }
}

​

常见模拟组合

​

完成「充值 → 消费 → 查余额」最小流程

# 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 接口

​

测试退货与冲正

​

模拟范围说明

• 授权在系统内一次性完成——不提供独立的清算 / 授权更新 / 授权冲正模拟接口；消费 / 退货 / 冲正全部由 fund-auth 的 authType 表达。
• 不涉及链上抵押与支付路由——不提供相关模拟接口。
• 3DS 认证在发卡侧完成，不提供独立的 3DS 模拟接口；需要测试 3DS 处理时，见 3DS 转发。

​

下一步

• 理解授权在系统内如何决策与占用余额，见 授权交易。
• 查看模拟充值 / 消费后用户余额（availableBalance / frozenBalance）的变化，见 用户余额。
• 真实的链上充值地址、链与币种配置，见 加密货币充值。
• KYC 令牌在真实流程中的用法，见接入资源 · 概述。