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

# 快速开始

> 在沙盒环境用最短路径完成第一张可用卡的完整流程：发送验证码 → 注册用户 → 获取开卡引导链接 → 接收开卡 Webhook → 管理卡片 → 入金与模拟消费。

本页带您在沙盒环境用**推荐的最佳实践路径**发出第一张可用卡。作为持牌、自有 BIN 的发卡机构，DCS 的托管模式让发卡、KYC、授权与清算都在同一套 API 内完成，您无需自建任何卡核心能力。

本页只走一条最简路径（手机号注册、托管引导页开卡、单张虚拟卡、单一币种入金）；完整的 KYC 流程、链/币种矩阵、卡管理与对账见各自专页。

***

## 开始前

请确认您已完成以下准备（详见 [前置准备](./first-steps)）：

* 已了解 **DeCard 托管模型**：授权决策在 DCS 系统内完成，持卡人将资金转入 DCS 托管，DCS 据其可用资产实时决定卡额度（见 [概述](./overview)）。
* 已领取调用凭证 **API Key / Secret Key**。
* 已向 DCS 提供**网络出口 IP**（DCS 启用接口白名单机制）。
* **Webhook 回调地址**（必配）：本流程的开卡结果依赖 Webhook 送达，未配置将无法完成步骤 4。
* **WebSocket 连接**（可选）：如需实时推送余额变动、交易结果等，可额外配置，详见 [Webhook 与 WebSocket](../integration-resources/webhook-websocket)。

> 环境地址 —— 沙盒：`https://api.thedecard-sandbox.com`；生产：`https://api.thedecard.com`。

> **鉴权**：所有请求需携带 `X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN` 四个头并计算 HMAC-SHA256 签名。完整规则（签名拼接公式、防重放说明及代码示例）见 [鉴权指南](../integration-resources/overview)。下文示例为聚焦业务字段**省略了鉴权头**，实际调用时必须携带。`SecretKey` 仅在本地参与签名计算，绝不上送。

> **路径前缀**：DeCard 托管模式各模块直接使用 `/account/`、`/card/`、`/crypto/`、`/user-asset/`、`/redirect/`、`/simulation/` 前缀（无 `/open-api/` 前缀）。

<Warning>
  下文所有手机号、用户 ID、地址等示例值均为**脱敏占位**，请替换为您自己的真实值。
</Warning>

***

## 📄 正文

全程 6 步。整体形态是：**您调 API 发起，持卡人在 DCS 托管页面完成敏感操作，结果通过 Webhook 回到您这里。**

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-quickstart-flow-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=b645cb5e64c23a50eb581a9e5ea9e086" alt="快速开始六步时序图" width="560" height="798" data-path="imgs/diagrams/va-quickstart-flow-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-quickstart-flow-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=a70ba55da25a469caea8da84578318ac" alt="快速开始六步时序图" width="560" height="798" data-path="imgs/diagrams/va-quickstart-flow-dark.svg" />
</Frame>

> 上图为**生产路径**。沙盒下步骤 6 的入金与消费改用模拟器接口，见该步说明。

### 步骤 1: 发送短信验证码

DeCard 托管模式下用户以「手机号 + 短信 OTP」两段式注册。先为目标手机号请求一条验证码：

```http theme={null}
POST /captcha/v1/send-mobile-code
```

```json theme={null}
{
  "mobileCode": "SG",
  "mobile": "91234567",
  "externalUserId": "",
  "behavioral": "REGISTER"
}
```

> `mobileCode` 为手机号国家码（ISO 2 位，如 `SG` / `CN` / `US`）；`mobile` 为本机号码（不加区号）。新用户注册时 `externalUserId` 留空。
> `behavioral` 是**场景枚举**，标识本次验证码的用途，取值 `REGISTER`（注册）/ `CARD_UNFROZEN`（解冻卡）/ `WITHDRAW`（提现）。注册场景填 `REGISTER`。

成功响应（结构统一为 `{code, message, messageDetail, data}`，成功码 `code = SYS_SUCCESS`）：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": ""
}
```

> 本接口的 `data` 固定为空字符串——验证码通过短信下发，不在响应体里返回。以 `code = SYS_SUCCESS` 判断是否成功即可。
> 关于响应结构：`messageDetail` 成功时通常为 `null`；在失败或需要前端提示的场景下，它是一个**对象**（含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl` 等字段）。本页后续示例为聚焦业务字段，结构一律按成功态展示。

### 步骤 2: 注册用户

凭上一步收到的短信验证码完成注册：

```http theme={null}
POST /account/v1/register
```

```json theme={null}
{
  "mobileCode": "SG",
  "mobile": "91234567",
  "smsCode": "<短信验证码>"
}
```

> 手机号注册需 `mobileCode` + `mobile` + `smsCode` **三者同时提供**。
> DCS 另支持邮箱注册路径（`email` + `emailCode`），与手机号路径**严格互斥**——`smsCode` 与 `emailCode` 同时传会被拒绝并返回 `SMS_EMAIL_CODE_MUTUALLY_EXCLUSIVE`。本页只走手机号路径，邮箱路径见 [用户注册](../how-to-use/signing-up-a-customer/overview)。

响应的 `data` 字段**直接返回** `externalUserId`（字符串），后续所有接口以它标识用户，请务必保存：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c"
}
```

### 步骤 3: 获取开卡引导链接

**这是推荐的开卡方式。** KYC 与开卡都在 DCS 托管的 H5 页面内完成——持卡人的证件、人脸等敏感材料直接提交给 DCS，不经过您的后端，您无需承担这部分合规与存储责任。

```http theme={null}
POST /redirect/v2/guidance-link
```

```json theme={null}
{
  "action": "KYC_GUIDE",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "successRedirectUrl": "https://your-app.example.com/kyc/success",
  "errorRedirectUrl": "https://your-app.example.com/kyc/failed",
  "language": "en"
}
```

> `action`、`externalUserId`、`successRedirectUrl`、`errorRedirectUrl` **四者必填**。
> `language` 取值为**小写连字符**形式且**大小写敏感**：`zh` / `en` / `ko` / `ja` / `zh-Hant` / `th` / `vi`。传入白名单以外的值会被静默降级为默认语言，不会报错——请严格按此列表传。
> 完整参数（`theme` / `mode` / `primaryColor` / `selectCardPageShow` 等）见 [H5 KYC 与开卡引导页](../integration-resources/h5-kyc-guidance)。

响应的 `data` 就是一次性引导链接（字符串），把它交给持卡人在浏览器打开即可：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": "https://h5.thedecard-sandbox.com/en/kyc?secret=xxxxxxxx"
}
```

> ⏱ **链接有效期 5 分钟**（服务端 secret TTL 为 300 秒），过期后页面失效需重新申请。
> 因此**不要用邮件、工单等异步渠道下发链接**——请在持卡人处于活跃会话时即时生成、即时跳转；用户中途放弃后重新进入，也应重新调本接口取新链接，不要缓存复用。

> **两个前置校验会直接拦下请求，接入时请预先处理**：
>
> * 该用户 KYC 已是 `PASS` 或 `PENDING` 时返回 `OPERATION_UNSUPPORTED`——不允许重复发起。
> * 触发当日进件限流时返回 `KYC_APPLY_LIMIT_EXCEEDED`——请做好重试节流与用户提示。

### 步骤 4: 接收卡申请 Webhook

持卡人在托管页完成提交后，**开卡结果通过 `CARD_APPLY` Webhook 推送给您**。本流程中接入机构不主动发起开卡请求，因此这是拿到 `applyId` 的唯一途径（`cardId` 在开卡成功后也可用步骤 5 的查卡接口取到）。

> 同一事件会**同时投递到 Webhook 与 WebSocket 两个通道**（服务端先推 WS 再推 Webhook），两边数据内容一致。只接 Webhook 即可完成本流程；接了 WebSocket 的话注意做去重。

`CARD_APPLY` 事件的 `data` 结构：

| 字段              | 类型      | 说明                            |
| :-------------- | :------ | :---------------------------- |
| `applyId`       | string  | 申请 ID，补件时需要                   |
| `cardId`        | string  | 卡 ID，仅开卡成功后有值                 |
| `categoryId`    | Long    | 卡类别 ID，由持卡人在托管页选卡时确定，接入机构无需传入 |
| `network`       | string  | 卡组织（如 `VISA`）                 |
| `currency`      | string  | 卡币种                           |
| `applyRef`      | string  | 申请幂等字段                        |
| `status`        | string  | 申请状态，见下表                      |
| `errorCode`     | string  | 失败原因，仅 `FAILED` 时提供           |
| `needExtraInfo` | boolean | 是否需要补充材料，见下方分支                |

`status` 只有 **3 个公开值**（KYC 通过、卡创建成功等内部中间状态统一显示为 `PENDING`）：

| 值         | 是否终态 | 含义与动作                                  |
| :-------- | :--- | :------------------------------------- |
| `PENDING` | 否    | 处理中。若同时 `needExtraInfo = true`，走下方补件分支 |
| `SUCCEED` | 是    | 开卡成功，`cardId` 已可用，进入步骤 5               |
| `FAILED`  | 是    | 开卡失败，读 `errorCode` 判断原因                |

<Warning>
  收到 Webhook 后请**在 2 秒内返回 `2xx`**（DCS 侧 connectTimeout 与 socketTimeout 均为 2000 ms），建议先存储再异步处理业务，否则会被判超时并重复投递。详见 [Webhook 与 WebSocket](../integration-resources/webhook-websocket)。
</Warning>

#### 补件分支：`needExtraInfo = true`

当 KYC 需要持卡人补充材料时，Webhook 会带 `needExtraInfo = true`。此时用 **同一个 `applyId`** 再申请一条补件引导链接：

```http theme={null}
POST /redirect/v2/guidance-link
```

```json theme={null}
{
  "action": "KYC_EXTRA_DOC",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "applyId": "A100001",
  "successRedirectUrl": "https://your-app.example.com/kyc/success",
  "errorRedirectUrl": "https://your-app.example.com/kyc/failed"
}
```

> `KYC_EXTRA_DOC` 场景下 `applyId` **必填**，缺失返回 `OPERATION_UNSUPPORTED`；`applyId` 不属于该用户返回 `PERMISSION_DENIED`；该申请的 `needExtraInfo` 不为 `true` 时同样返回 `OPERATION_UNSUPPORTED`——**请以 Webhook 的 `needExtraInfo` 为准再发起，不要盲目调用**。

持卡人补件完成后，DCS 会再次推送 `CARD_APPLY`，直至 `status` 进入 `SUCCEED` 或 `FAILED` 终态。

### 步骤 5: 卡管理

拿到 `cardId` 后即可进入卡的日常管理。

**查持卡列表 / 单卡详情**

```http theme={null}
GET /card/v2/detail?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c
```

> `externalUserId` 必填；`cardId` 可选，留空返回该用户全部卡，传入则查单张。
> 返回字段含 `cardStatus`（`NORMAL` / `FROZEN` / `CANCELLED`）、`cardNo`（脱敏）、`cardHolder`、`physicalCardStatus` 等。

**把完整卡号展示给持卡人**

出于 PCI 合规，完整卡号、CVV、有效期**不会**通过 API 返回到您的后端。请用 `CARD_INFO` 引导页，由持卡人在 DCS 托管页面直接查看：

```http theme={null}
POST /redirect/v2/guidance-link
```

```json theme={null}
{
  "action": "CARD_INFO",
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "successRedirectUrl": "https://your-app.example.com/card/back",
  "errorRedirectUrl": "https://your-app.example.com/card/error"
}
```

> `CARD_INFO` / `CREATE_PHYSICAL_CARD` / `ACTIVE_PHYSICAL_CARD` / `UPDATE_PIN` 这四个 `action` **必须携带 `cardId`**，且该用户须已有卡，否则请求会被拒绝。

**冻结 / 解冻**

```http theme={null}
POST /card/v2/block
```

```json theme={null}
{
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "block": true
}
```

> `block = true` 冻结、`false` 解冻。响应 `data` 为布尔值，表示本次冻结/解冻操作是否成功（`true` = 成功 / `false` = 失败）。

<Warning>
  **解冻需要二次验证**：`block = false` 时必须额外传 `smsCode` 或 `emailCode`，请先用步骤 1 的验证码接口以 `behavioral = CARD_UNFROZEN` 下发。冻结则不需要。
</Warning>

> 实体卡申请与激活、重置 PIN 等其余能力见 [卡管理](../how-to-use/managing-cards/overview)。

### 步骤 6: 入金与模拟消费

**入金 —— 生产环境**

查该用户的加密充值地址，向该地址链上转账即可：

```http theme={null}
GET /crypto/v2/deposit-address?externalUserId=4dc3e854-...&network=<链>&coin=<币种>
```

> 三个参数均必填。v2 返回 `network` / `address` / `coin` / `fxRate` / `status`。

<Warning>
  本接口不返回最小充值额与所需链上确认数。**如果您需要向持卡人提示"最少充多少、要等几个确认"，请从 `network-coin` 配置获取（`minConfirm` 等字段）或另行维护该配置。** 链与币种矩阵见 [加密货币充值](../how-to-use/virtual-accounts/crypto-deposit)。
</Warning>

**入金 —— 沙盒环境**

沙盒用模拟器直接给用户账户充值，便于联调：

```http theme={null}
POST /simulation/v1/deposit
```

```json theme={null}
{
  "chain": "<链>",
  "currency": "USDT",
  "amount": 100.0,
  "address": "<该用户的入金地址>"
}
```

> 模拟资金充入用户的加密入金地址，`address` 取自上一步的 `deposit-address`。

**确认余额**

```http theme={null}
GET /user-asset/v1/balance?externalUserId=4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c
```

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": [
    { "asset": "USDT", "logo": "", "network": "", "free": 100.0, "freeze": 0.0, "total": 100.0 }
  ]
}
```

> 余额字段：`free` = 可用、`freeze` = 冻结、`total` = 总额（API 实际字段名以此为准）。返回的是**数组**，请按 `asset` 遍历。

**模拟一笔消费**

用模拟器发起一笔卡授权，验证您的 Webhook 处理与额度变化：

```http theme={null}
POST /simulation/v2/fund-auth
```

```json theme={null}
{
  "externalUserId": "4dc3e854-xxxx-xxxx-xxxx-91a98b3d832c",
  "cardId": "1234567890123456789",
  "authType": "EXPEND",
  "amount": 10.0,
  "currency": "USD"
}
```

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

> 推荐用 **v2**（以 `cardId` 定位卡，与步骤 4 拿到的 `cardId` 直接衔接）；v1 用 `cardMantissa`（卡号后四位）定位，仅为兼容保留。
> `authType` 枚举：`EXPEND`（消费）| `REFUND`（退货）| `REVERSAL`（消费冲正）。
> 授权在 **DCS 系统内**依用户可用资产完成，`approved` 即授权结果。沙盒模拟会产生真实交易记录、触发 Webhook 并更新余额，但不涉及真实资金。完整场景见 [模拟交易](../how-to-use/simulating-transactions/overview)。

至此，第一张可用卡已发出并完成入金，也已验证一笔模拟消费。

***

## 下一步

* **完整 KYC 流程与状态机** → [合规](../basic-concepts/compliance-kyc-flow) — KYC 申请、审核、POA 补充与 AML 处理的完整流程
* **引导页全部 action 与参数** → [H5 KYC 与开卡引导页](../integration-resources/h5-kyc-guidance) — 7 个 action 的适用场景、语言与主题定制、链接有效期
* **申请实体卡、换卡、重置 PIN** → [卡管理](../how-to-use/managing-cards/overview) — 卡的全生命周期管理
* **加密充值链/币种矩阵、链上提现** → [资金充提](../how-to-use/virtual-accounts/crypto-deposit) — 多链充值与提现
* **沙盒模拟交易全场景** → [模拟交易](../how-to-use/simulating-transactions/overview) — 消费、退货、冲正等全部交易类型
* **鉴权头与 HMAC-SHA256 签名规则** → [鉴权指南](../integration-resources/overview) — 必带头列表、签名拼接公式、防重放说明与代码示例
* **Webhook & WebSocket 实时推送** → [Webhook 与 WebSocket](../integration-resources/webhook-websocket) — 全部 9 类事件的数据结构、重试与幂等处理