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

# 上线前常见问题

> 无论您是交易所、钱包还是平台方，在正式上线前都需要完成以下准备：请 DCS 开通接入凭证与卡配置、确认 KYC 接入方式、提交回调与白名单信息，并在沙盒完成「注册 → KYC → 开卡 → 充值 → 消费」流程。本页通过问答和清单集中说明上线分工、用户注册与 KYC 资料、Sumsub 与 POA 接入方式、H5 引导页和接入配置，并附上线前自检清单。

DCS 是持牌、自有 BIN 的发卡机构。在 DeCard 托管模式下，**KYC 审核与授权决策均由 DCS 在系统内部完成**，您无需自建授权决策与抵押品管理——这与需要接入机构自管授权的合作伙伴自管（池账户）模式不同。上线前的配置工作由 DCS 与接入机构分工完成，本页会逐条标注「谁做」。

***

## DeCard 托管模式核心能力速览

以下为 DeCard 托管模式相较合作伙伴自管（池账户）模式的特色能力，在本套文档各专题页有详细说明。本页不展开细节，仅作为导航入口：

| 能力                         | 说明                                                                                 | 详见                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **独立账户余额模型**               | 每位终端用户拥有独立余额，由 `free`（可用）/ `freeze`（冻结）/ `total`（总额）三个字段描述；授权决策在 DCS 系统内部校验可用余额后完成 | [用户余额](../how-to-use/managing-transactions/user-balance)                    |
| **加密货币充提**                 | 支持多链多币种加密资产充值（链上到账后计入 DCS 账本）及提现                                                   | [加密货币充值](../how-to-use/virtual-accounts/crypto-deposit)                     |
| **QR Pay 扫码付**             | 持卡人可通过 QR 码完成支付                                                                    | [扫码付（QR Pay）](../how-to-use/managing-transactions/qr-pay)                   |
| **Apple Pay 与 Google Pay** | 支持 应用内一键绑卡（Push Provisioning）                                                      | [Apple Pay 与 Google Pay 绑卡](../how-to-use/managing-cards/push-provisioning) |
| **WebSocket 实时推送**         | 面向终端用户的实时消息推送能力（DeCard 托管特色能力）                                                     | [Webhook 与 WebSocket](../integration-resources/webhook-websocket)           |

***

## 上线前要做哪些准备？

DeCard 托管模式的接入机构在上线前需要完成下面这条主线，分工如下：

| 步骤                                             | 谁做         | 说明                                                                        |
| ---------------------------------------------- | ---------- | ------------------------------------------------------------------------- |
| 1. 开通接入凭证与卡配置（Program / categoryId）            | DCS        | 您告知需发行的卡类型（虚拟卡 / 实体卡）、卡组织、卡 BIN 与发行地区，DCS 为您生成接入凭证并配置对应的卡类别（`categoryId`） |
| 2. 确认 KYC 接入方式（Sumsub Share Token / DCS 托管 H5） | 接入机构 + DCS | 决定终端用户使用 Sumsub Share Token 嵌入开卡，还是使用 DCS 托管的 H5 KYC 引导页（详见下文）            |
| 3. 提交回调地址与网络出口 IP                              | 接入机构       | 向 DCS 提供 Webhook 回调地址；提交需加入白名单的网络出口 IP（详见下文）                              |
| 4. 接入实时通知（Webhook / WebSocket）                 | 接入机构       | 订阅卡状态、交易、KYC 状态等事件；WebSocket 用于面向终端用户的实时推送（DeCard 托管特色能力）                 |
| 5. 在沙盒完成第一张卡的联调                                | 接入机构       | 在沙盒完成「用户注册 → KYC → 开卡 → 充值 → 消费」完整流程                                      |
| 6. 切换生产环境                                      | 接入机构 + DCS | 领取生产接入凭证、切换至生产环境地址                                                        |

> 接入主线的端到端时序与前置项请参阅 [前置准备](../getting-started/first-steps) 与 [快速开始](../getting-started/quickstart)。

***

## 终端用户注册需要哪些信息？

DeCard 托管模式下，终端用户在系统内完成注册。注册有 **手机号** 与 **邮箱** 两条互斥路径，二选一即可：

| 注册路径      | 必填字段                                                  | 说明                                                                                               |
| --------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **手机号注册** | `mobileCode`（手机号国家码）+ `mobile`（手机号）+ `smsCode`（短信验证码） | 三者需同时提供。注：DeCard 托管使用 `mobileCode` / `mobile` 字段，与合作伙伴自管（池账户）模式的 `phoneCountryCode` / `phone` 不同 |
| **邮箱注册**  | `email`（邮箱）+ `emailCode`（邮箱验证码）                       | 两者需同时提供                                                                                          |

<Warning>
  **两条路径互斥**：`smsCode` 与 `emailCode` 不可同时传，同时传会被直接拒绝并返回 `SMS_EMAIL_CODE_MUTUALLY_EXCLUSIVE`；两条路径的字段都不满足则返回 `INVALID_PARAMETER`。
</Warning>

注册主线（接口以接口定义为准）：

1. 按所选路径调用 `POST /captcha/v1/send-mobile-code` **或** `POST /captcha/v1/send-email-code` 下发验证码；
2. `POST /account/v1/register` 提交对应路径的字段完成注册。

> 所有接口统一返回 `{code, message, messageDetail, data}` 结构，成功码 `code=SYS_SUCCESS`。详见 [鉴权指南](../integration-resources/overview)。
>
> 注册成功后系统会生成用户标识（`externalUserId`），后续 KYC、开卡、充值、查询均以该标识关联。`register` 接口会在响应的 `data` 字段中直接返回该标识（`data` 就是一个字符串），请在注册成功时保存。注册接口与字段的完整说明见 [用户注册](../how-to-use/signing-up-a-customer/overview)。
>
> 示例一律使用脱敏占位：手机号 `+65xxxxxxxx`、邮箱 `user@example.com`，**切勿** 在工单或日志中携带真实终端用户信息。

***

## 终端用户 KYC 需要准备哪些资料？

KYC 验证由 DCS 在系统内部完成自动审核与人工审核。终端用户需提供：

* **身份证明（POI）**：可接受的证件类型（如护照、身份证、驾照）因国家/地区而异，以 DCS 提供的证件白名单为准；
* **地址证明（POA）**：部分国家/地区或在 Sumsub 验证仅含 POI 时，需额外补充 POA；
* **自拍/活体（Selfie）**：用于核验证件与本人一致。

> 各国家/地区可接受的 POI/POA 白名单及是否必须 POA，见 [合规 · KYC 证件说明](./kyc-documents)。KYC 五种状态（`UNDO`/`INIT`/`PENDING`/`PASS`/`REFUSE`）见 [合规 · 概述](../basic-concepts/compliance-kyc-flow)。

<Warning>
  DeCard 托管模式当前**不提供** 企业申请（KYB）、最终受益人（UBO）、公司注册文件等企业级合规能力；上线前的资料清单仅面向**个人 KYC**。
</Warning>

KYC 审核时长与标准化拒绝原因码需根据卡产品配置和合规要求确认。`REFUSE` 是本次申请的最终状态；如需重新发起申请，系统限制 24 小时内最多提交 10 次（上限可配置）。

***

## KYC 用 Sumsub Share Token 还是 DCS 托管 H5？两种方式怎么选？

这取决于接入机构自身是否已有 KYC 能力：

| 接入机构的 KYC 方式   | 接入方式               | 要点                                                                                                              |
| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **已接入 Sumsub** | Sumsub Share Token | 接入机构在 Sumsub 完成验证后，把 Sumsub Share Token（字段 `sumsubShareToken`）交给 DCS，由 DCS 获取验证结果。若 Sumsub 仅含 POI 无 POA，需补充 POA |
| **无自有 KYC 能力** | DCS 托管 H5 引导页      | 通过 H5 引导链接（`/redirect/v*/guidance-link`）把用户引导到 DCS 托管的 KYC/开卡页面，由 DCS 收集证件并完成验证                                 |

使用 Sumsub 时，接入机构需在 Sumsub 平台为沙盒与生产环境分别配置 DCS 的合作伙伴令牌。**上线前请向 DCS 确认应使用哪种 Token 共享模式，并确保已与 Sumsub 签署对应合约**——未签约会影响上线。

> Sumsub KYC 资料共享的两种方式与接入步骤见 [Sumsub KYC 资料共享](./kyc-vendor)；H5 引导页参数见 [H5 KYC 与开卡引导页](../integration-resources/h5-kyc-guidance)。

***

## 跨境资金操作前需要做什么？（Travel Rule）

DeCard 托管模式遵循 Travel Rule（旅行规则）合规要求：**在为用户获取链上充值地址之前，用户必须先上传 Travel Rule 信息**（身份、资金来源、财富来源等）。

* 上传：`POST /account/v1/update-travel-rule`
* 查询：`GET /account/v2/query-travel-rule`

> 这是 DeCard 托管模式的合规特色能力，详见 [合规 · 旅行规则（Travel Rule）](../how-to-use/virtual-accounts/travel-rule)。

***

## 接入前置配置有哪些？

| 配置项                 | 用途                                  | 谁提供                                                                                                             |
| ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 接入凭证（API Key / 鉴权头） | API 调用的准入凭证与请求来源识别                  | **DCS 提供给您**（沙盒联系 DCS 团队）                                                                                       |
| API 基础地址（Base URL）  | 所有 API 请求的目标地址                      | 沙盒：`https://api.thedecard-sandbox.com`；生产：`https://api.thedecard.com`。详见 [前置准备](../getting-started/first-steps) |
| Webhook 回调地址        | 接收 DCS 推送的事件通知（卡状态、交易、KYC 状态、充值到账等） | **您提供给 DCS**                                                                                                    |
| 网络出口 IP（白名单）        | 加入 DCS 白名单的调用方出口 IP                 | **您提供给 DCS**                                                                                                    |

请按实际网络拓扑，分别提供沙盒与生产环境的出口 IP，避免上线时因白名单缺失被拒。

> 鉴权头与签名规则见 [接入资源 · 鉴权指南](../integration-resources/overview)；IP 白名单见 [IP 白名单](../integration-resources/ip-whitelisting)；Webhook 事件与 WebSocket 实时推送（DCS 托管特色）见 [Webhook 与 WebSocket 实时通知](../integration-resources/webhook-websocket)。

<Warning>
  接入凭证为敏感信息，**切勿** 写入工单、日志或外发邮件正文；生产凭证的领取方式请与 DCS 商务/技术对接确认。
</Warning>

***

## 上线前自检清单

* [ ] 已确认卡类型、卡组织、卡 BIN 与发行地区，DCS 已配置接入凭证与卡类别（`categoryId`）
  > （自证：能在沙盒成功请求 `/card/v2/detail` 等需鉴权的接口，返回非 401/403）
* [ ] 已与 DCS 确认 KYC 接入方式（Sumsub Share Token 或 DCS 托管 H5）；如使用 Sumsub，已完成合约与令牌设置
  > （自证：在沙盒能以选定方式完成一次完整 KYC 流程，最终状态达 `PASS`）
* [ ] 已确认个人 KYC 资料清单（POI / POA / 自拍），并核对各发行地区的证件白名单
  > （自证：按 [KYC 证件说明](./kyc-documents) 逐项比对，各发行地区所需证件均已准备就绪）
* [ ] 已向 DCS 提交 Webhook 回调地址与网络出口 IP（沙盒 + 生产）
  > （自证：联系 DCS 团队确认白名单已生效，或从沙盒后台触发测试推送验证回调端可达）
* [ ] 已接入实时通知（Webhook 事件订阅；如需面向终端用户实时推送，已联调 WebSocket）
  > （自证：可在 DCS 沙盒后台触发一条测试 Webhook，确认您的回调端能收到并验签通过）
* [ ] 已在沙盒完成「用户注册 → KYC → 开卡 → 充值 → 消费」完整流程
  > （自证：至少成功创建一张沙盒卡、完成一笔模拟充值并在 [用户余额](../how-to-use/managing-transactions/user-balance) 查询到可用余额、完成一笔模拟消费/授权）
* [ ] 已与 DCS 确认生产接入凭证领取方式并切换至生产环境地址
  > （自证：已确认生产 Base URL（`https://api.thedecard.com`）与生产凭证已就绪）

***

## 本组导航

* [上线后常见问题](./post-go-live) — 上线后运营期的常见问题处理：卡片消费/退款、加入移动钱包、交易争议与上报路径等。

## 下一步

* 准备上线主线与前置项，请看 [前置准备](../getting-started/first-steps) 与 [快速开始](../getting-started/quickstart)。
* 终端用户注册与 KYC 接入，请看 [注册用户](../how-to-use/signing-up-a-customer/overview) 与 [合规 · 概述](../basic-concepts/compliance-kyc-flow)。
* 卡片申请与管理，请看 [申请卡](../how-to-use/managing-cards/issuing-cards)。
* 上线后运营期问题，请收藏 [上线后常见问题](./post-go-live)（同组）。