> ## 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.

# 模拟交易：授权、清算、退款、部分清算、多笔清算与 3DS

> 逐场景讲 fund-auth 模拟接口：鉴权与请求头、请求/响应字段、EXPEND / REFUND / REVERSAL 三类授权方向能驱动哪些场景、推荐回归顺序，以及当前尚未提供独立模拟入口的场景。沙盒环境与前置条件见 沙盒与测试概述。

## 模拟交易

无论您是刚接通授权回调、还是准备上线前做最后回归，都可以在沙盒里用一个接口完整验证「刷卡—授权—退货—冲正」流程，验证您的 `authUrl` 决策逻辑与 `webhookUrl` 入账逻辑是否正确，全程不动用真实资金、不触碰真实卡组织。DCS 是持牌发卡机构，沙盒环境与生产环境共享同一套授权转发流程，您在沙盒里跑通的对接逻辑可平滑迁移到生产。

在合作伙伴自管方案中，额度由接入机构**掌握**、授权由接入机构**决策**。因此沙盒模拟的核心价值，在于**驱动一次真实的授权转发**：DCS 收到模拟交易后，会像处理真实刷卡一样，把授权请求转发到您配置的 `authUrl`，等待您返回放行/拒绝，再据此回调 `webhookUrl`。

> 谁做什么
>
> * **DCS**：接收模拟请求 → 生成交易 → 向 `authUrl` 发起授权转发 → 按您的决策回调 `webhookUrl`。
> * **接入机构**：发起模拟请求 → 在 `authUrl` 返回授权决策 → 在 `webhookUrl` 接收并入账。

***

## 接口：模拟授权请求

**`POST /open-api/simulation/v1/fund-auth`**

模拟一笔授权请求（消费 / 退货 / 消费冲正），用于在沙盒中触发完整的授权转发与 Webhook 通知流程。

> 此接口为**沙盒（QA/DEV）专用**。在生产环境调用会被拦截并返回 `OPERATION_NOT_SUPPORT`。

### 鉴权与请求头

与所有 `/open-api/` 接口一致，需携带鉴权头并设置 `Content-Type: application/json`。完整规则见 [接入鉴权](../../integration-resources/authentication)。

| Header             | 必填 | 说明                            |
| ------------------ | -- | ----------------------------- |
| `Content-Type`     | 是  | 固定 `application/json`         |
| `X-DAPI-API-KEY`   | 是  | DCS 交付的 `apiKey`              |
| `X-DAPI-TIMESTAMP` | 是  | 请求时间戳（毫秒，UTC），用于防重放           |
| `X-DAPI-NONCE`     | 是  | 随机数，取值范围 `[10000, 99999]`，防重放 |
| `X-DAPI-SIGN`      | 是  | HMAC-SHA256 签名（十六进制小写）        |

### 请求参数

| 字段         | 类型     | 必填 | 说明                                                            | 约束               |
| ---------- | ------ | -- | ------------------------------------------------------------- | ---------------- |
| `cardId`   | string | 是  | 卡 ID。卡须处于可用状态                                                 | —                |
| `authType` | string | 是  | 授权类型：`EXPEND` 消费 / `REFUND` 退货 / `REVERSAL` 消费冲正              | 枚举三选一            |
| `amount`   | number | 是  | 金额（小数形式），正数，单位为该币种主单位（元 / 美元 / 新币等）                           | 整数位 ≤ 10，小数位 ≤ 2 |
| `currency` | string | 是  | 交易币种，ISO 4217 三位货币代码（`USD` / `CNY` / `SGD` / `EUR` / `JPY` 等） | —                |

> 本接口（`POST /open-api/simulation/v1/fund-auth`）当前**不支持**指定商户名（merchantName）、商户类别码（MCC）或主动指定拒绝原因（declineReason）等参数；如后续有相关需求请联系 DCS 团队。

### 请求示例（消费）

```json theme={null}
{
  "cardId": "CARD_20250101XXXX",
  "authType": "EXPEND",
  "amount": 50.00,
  "currency": "USD"
}
```

### 响应示例

成功调用返回统一响应结构，授权结果在 `data` 中：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "approved": true,
    "errorCode": null
  }
}
```

授权被拒（例如您的 `authUrl` 返回拒绝）时：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "approved": false,
    "errorCode": "XXXX"
  }
}
```

### 响应字段

| 字段               | 类型      | 说明                   |
| ---------------- | ------- | -------------------- |
| `data.approved`  | boolean | 该笔模拟授权是否最终通过         |
| `data.errorCode` | string  | 未通过时的错误码（具体码值见错误码字典） |

> 关于统一响应结构 `{code, message, messageDetail, data}`：`code` 为系统级状态（如 `SYS_SUCCESS`），`message`/`messageDetail` 为提示信息。

<Warning>
  请注意：**HTTP 调用成功 + `code=SYS_SUCCESS` 并不代表授权通过**。本接口的「授权是否通过」以 `data.approved` 为准——`approved=false` 时，`code` 同样可能返回 `SYS_SUCCESS`。请勿仅凭响应状态判断业务结果。错误码归类见[错误码字典](../transactions/decline-codes)。
</Warning>

***

## 模拟能驱动哪些场景

DCS 沙盒以 `authType` 区分三类授权方向，覆盖授权转发的核心回路：

| authType   | 模拟动作 | 资金方向            | 典型用途                            |
| ---------- | ---- | --------------- | ------------------------------- |
| `EXPEND`   | 消费   | OUTGOING（占用额度）  | 验证 `authUrl` 放行/拒绝决策、Webhook 入账 |
| `REFUND`   | 退货   | INCOMING（退回）    | 验证退货回调与对账方向                     |
| `REVERSAL` | 消费冲正 | INCOMING（撤销原授权） | 验证撤销/释放冻结的处理                    |

### 推荐的回归顺序

1. **建一张可用卡**：先在沙盒走完开卡流程（见 [虚拟卡申请](../cards/virtual-card)），拿到 `cardId`。
2. **配好回调地址**：确认 `authUrl` 与 `webhookUrl` 已配置并能接收（见 [Webhook 配置](../webhooks/configuration)）。
3. **模拟一笔消费**：`authType=EXPEND` 发起 → 在 `authUrl` 返回放行 → 检查 `data.approved=true` 且 `webhookUrl` 收到对应事件。
4. **模拟拒绝**：在 `authUrl` 返回拒绝 → 检查 `data.approved=false` 与 `errorCode`。
5. **模拟退货 / 冲正**：分别用 `REFUND` / `REVERSAL` 验证 INCOMING 方向的回调与对账。

> 模拟交易会生成**真实的交易/授权记录**并触发**真实的 Webhook**，与生产同构，因此可直接用于端到端验证。授权/交易记录字段与 Webhook 事件结构见 [事件与数据结构](../webhooks/events-and-schema) 与 [授权与清算全场景](../transactions/auth-and-settlement)。

***

## 暂不支持的独立模拟场景

DCS 当前沙盒仅提供 `fund-auth` 一个模拟入口，覆盖消费 / 退货 / 冲正。以下场景**尚无独立模拟接口**，对接时请用文档约定的回调结构进行联调，或联系 DCS 团队协助构造：

| 场景                                | 状态   | 说明                                                                                 |
| --------------------------------- | ---- | ---------------------------------------------------------------------------------- |
| 独立的清算/结算（settlement/capture）模拟    | 暂不提供 | 当前无独立「清算」模拟接口；清算行为请参考 [清算场景：部分/超额/多笔](../transactions/capture-scenarios) 的真实回调结构联调 |
| 增量授权（authorization update，如加小费）   | 暂不提供 | 无独立增量模拟入口                                                                          |
| 部分/超额/多笔清算                        | 暂不提供 | 无独立模拟入口；语义见 [清算场景](../transactions/capture-scenarios)                              |
| 3DS 挑战（OTP/challenge）模拟           | 暂不提供 | 无独立 3DS 模拟接口；3DS 转发机制见 [3DS 转发](../transactions/3ds)                               |
| 抵押品 / 保证金充值（collateral funding）模拟 | 不适用  | 合作伙伴自管方案中额度由接入机构掌握、授权由接入机构决策，沙盒不提供面向终端用户的资金充值模拟入口                                  |

> DCS 当前以单一 `fund-auth` 接口 + 三种 `authType` 覆盖授权转发主回路。如需上表中尚未提供独立模拟入口的场景联调，请联系 DCS 团队协助。

***

## 下一步

模拟跑通后，建议对照 [授权与清算全场景](../transactions/auth-and-settlement) 核对每种 `authType` 在您系统中的入账方向，并在 [上线前检查](../../customer-success/pre-go-live) 完成最终回归。