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

# 沙盒与测试概述

> 沙盒环境总览：后端支持哪些模拟能力、沙盒/生产环境地址、模拟前的前置条件，以及 fund-auth 模拟接口的最小请求/响应示例。逐场景的模拟用例见 模拟交易。

## 📄 正文

无论您是想验证授权回调能否正确解析，还是想在上线前测试「刷卡 → 授权转发 → 入账」完整流程，都可以在沙盒环境中完成。测试不需要接入真实卡组织或使用真实资金，也不会影响真实持卡人。DCS 为接入机构提供与生产环境采用相同授权流程的沙盒环境，便于在接入早期反复验证授权决策逻辑。

### 后端是否支持模拟？

**支持，但范围有限。** 截至当前版本，合作伙伴自管接口提供 **1 个模拟接口**：

| 能力                         | 接口                                       | 状态           |
| -------------------------- | ---------------------------------------- | ------------ |
| 模拟一笔授权请求（消费 / 退货 / 消费冲正）   | `POST /open-api/simulation/v1/fund-auth` | ✅ 已提供（仅沙盒环境） |
| 模拟清算（Capture / Settlement） | —                                        | 规划中          |
| 模拟部分清算 / 多笔清算              | —                                        | 规划中          |
| 模拟 3DS Challenge           | —                                        | 规划中          |
| 模拟保证金充值 / 额度变更             | —                                        | 规划中          |

> 当前沙盒模拟能力聚焦于「授权」环节，清算、3DS、保证金等独立模拟接口尚在规划中。如您在测试中需要模拟上述场景，请与 DCS 团队联系以确认可行的替代方案。

### 沙盒能为您做什么

`fund-auth` 模拟接口会触发一次**真实的授权转发流程**：DCS 收到模拟请求后，按生产同样的流程把授权通知推送到接入机构配置的 `authUrl`，由接入机构返回放行 / 拒绝决策。因此它适合用于：

* 验证授权通知的 **RSA 双向签名 + 加解密** 是否正常；
* 验证接入机构的**授权决策逻辑**（额度判断、风控规则、超时处理）；
* 验证 `EXPEND`（消费）、`REFUND`（退货）、`REVERSAL`（消费冲正）三类场景下，您的系统状态流转是否正确。

### 沙盒环境地址

| 环境   | Base URL                            |
| ---- | ----------------------------------- |
| 沙盒环境 | `https://api.thedecard-sandbox.com` |
| 生产环境 | `https://api.thedecard.com`         |

<Warning>
  模拟接口仅在**沙盒环境**可用。生产环境会直接拦截该路径并返回 `OPERATION_NOT_SUPPORT`，请勿在生产环境调用 `simulation` 相关接口。
</Warning>

### 开始模拟前的前置条件

| 前置项       | 说明                                          | 谁做         |
| --------- | ------------------------------------------- | ---------- |
| 沙盒 API 密钥 | `api_key` + `secret_key`，用于 HMAC-SHA256 鉴权  | DCS 提供     |
| RSA 密钥对   | 接入机构生成 `external_public_key` 并上传，DCS 提供己方公钥 | 接入机构 + DCS |
| `authUrl` | 接收授权通知的回调地址，须可被沙盒访问                         | 接入机构       |
| 一张可用的卡    | 先在沙盒走完「创建用户 → KYC → 申请卡」，拿到 `cardId`        | 接入机构       |
| 企业保证金额度   | 沙盒侧需有可用额度，否则授权会被拒                           | DCS 配置     |

> 鉴权头、RSA 密钥生成（`openssl`）与 IP 白名单的完整说明，见 [接入与鉴权](../../integration-resources/authentication)。

### 最小请求示例

```bash theme={null}
curl -X POST https://api.thedecard-sandbox.com/open-api/simulation/v1/fund-auth \
  -H "Content-Type: application/json" \
  -H "X-DAPI-API-KEY: <your_api_key>" \
  -H "X-DAPI-TIMESTAMP: <timestamp-ms>" \
  -H "X-DAPI-NONCE: <10000-99999>" \
  -H "X-DAPI-SIGN: <signature>" \
  -d '{
    "cardId": "<您在沙盒创建的卡 ID>",
    "authType": "EXPEND",
    "amount": 12.50,
    "currency": "USD"
  }'
```

**请求字段**（接口：`POST /open-api/simulation/v1/fund-auth`）：

| 字段         | 类型     | 必填 | 说明                                                 |
| ---------- | ------ | -- | -------------------------------------------------- |
| `cardId`   | string | 是  | 卡 ID                                               |
| `authType` | string | 是  | 授权类型：`EXPEND`（消费）/ `REFUND`（退货）/ `REVERSAL`（消费冲正）  |
| `amount`   | number | 是  | 金额（小数形式），单位为元 / 美元 / 新币等                           |
| `currency` | string | 是  | 交易币种，3 位 ISO 货币代码（如 `USD` / `SGD` / `EUR` / `JPY`） |

### 最小响应示例

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

**响应字段**：

| 字段               | 类型      | 说明                               |
| ---------------- | ------- | -------------------------------- |
| `data.approved`  | boolean | 是否授权通过（即接入机构在 `authUrl` 返回的决策结果） |
| `data.errorCode` | string  | 拒绝时的错误码                          |

> **统一响应结构**：所有接口都返回 `{ code, message, messageDetail, data }`。`code` 表示系统调用结果（如 `SYS_SUCCESS`），业务结果须以 `data` 内字段（此处为 `approved`）为准——`code=SYS_SUCCESS` 仅代表请求被正确受理，不代表授权通过。请勿仅凭 `code` 判断业务成败。`messageDetail` 为面向终端的提示对象，平时可能为 `null`。响应结构的完整约定见 [接入与鉴权](../../integration-resources/authentication)。

### 完整流程验证建议

1. 调 `fund-auth`（`authType=EXPEND`）→ 观察 DCS 是否向您的 `authUrl` 推送授权通知；
2. 在 `authUrl` 侧验签、解密、做出决策并签名返回；
3. 检查 `fund-auth` 响应中的 `data.approved` 是否与您返回的决策一致；
4. 再用 `authType=REFUND` / `REVERSAL` 重复，验证退货与冲正路径。

## 下一步

逐场景的模拟用例（消费 / 退货 / 冲正，以及清算、部分/多笔、3DS 等待确认能力的处理建议），见 [模拟交易](./simulating-transactions)。