> ## 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.
# Sumsub KYC 资料共享
> 如果您已用 Sumsub 作为合规供应商，可通过 token 共享把已采集的用户验证资料复用给 DCS，免去用户重复认证。本页讲两种共享模式（线下约定，非 API 字段）、数据提供方/收取方两种接入方向，以及申请卡时如何传入 kycInfo.sumsubShareToken。
## 📄 正文
如果您已使用 [Sumsub](https://sumsub.com) 作为合规（身份验证）供应商，可以通过 Sumsub 的 **共享伙伴（Sharing Partners）** 机制，把已采集的用户验证资料共享给 DCS，从而简化 KYC 流程——无需让终端用户在 DCS 侧重复完成一次身份验证。
接入完成后，您在申请卡（开卡）请求中传入一个 Sumsub **share token**（字段 `kycInfo.sumsubShareToken`），DCS 即可凭该 token 从 Sumsub 获取并复用对应用户的验证资料，进入 KYC 审核后续流程。
> Sumsub token 共享需在**沙盒（UAT）与生产（PROD）两套环境**分别配置一次。沙盒环境的 token 不能用于生产，反之亦然——配置时务必确认环境一致。
## 两种接入方向
根据「谁采集、谁复用」用户验证资料，您与 DCS 之间存在两种 token 添加方向。请按您的实际角色选择对应步骤。
### 按角色配置 token 共享方向
**若您是数据提供方**（由您采集验证资料、共享给 DCS）：
1. 向 DCS 团队获取 UAT 与 PROD 对应的 partner token。
2. 在您的 Sumsub 平台进入 **Sharing Partners**（参考 [Sumsub 文档](https://docs.sumsub.com/docs/manage-sharing-partners)），按提示添加该 token。
3. 与 DCS 团队核对——DCS 的 Sumsub 平台应能看见您在 Sumsub 注册的名称。
**若您是数据收取方**（由 DCS 采集验证资料、共享给您；或您需要把 token 提供给 DCS）：
1. 在您的 Sumsub 平台获取 UAT 与 PROD 对应的 token，并分享给 DCS 员工。
2. DCS 添加完成后，请在您的 Sumsub 平台确认 **Donor 一览**中可见 DCS，并通知 DCS 结果。
### 步骤 3：生成 share token
在 Sumsub 侧为目标申请人生成 share token。share token 形如 `_act-sbx-***`（沙盒）/ `_act-***`（生产），**仅供示意，请勿写入任何真实 token**。
> Sumsub 的 share token 通常一次性使用，每次提交申请请生成新的 token；环境（沙盒/生产）须与 DCS 当前对接环境一致。
### 步骤 4：在申请卡请求中使用 share token
在申请虚拟卡 POST `/card/v1/virtual-card/apply` 请求中，把生成的 share token 放入 `kycInfo.sumsubShareToken`。
| 字段 | 类型 | 必填 | 约束 | 说明 |
| -------------------------- | ------ | -- | --------- | ------------------------------------------ |
| `kycInfo.sumsubShareToken` | string | 是 | 最大 500 字符 | Sumsub share token；DCS 凭此从 Sumsub 复用用户验证资料 |
**`kycInfo` 中没有模式字段**：申请卡请求体里，与 Sumsub token 相关的只有 `sumsubShareToken`。**不存在**任何模式枚举字段（如 `kycSubmitMode` / `sumsubShareTokenMode`）。共享关系由 Sumsub 后台的共享伙伴配置与签约决定，不在请求体中传递。
除 `sumsubShareToken` 外，`kycInfo` 还需提供一些不会从 Sumsub 获取的资料（如 `email`、POA 相关字段 `poaDocType`/`poaDocUrlList`/`poaDocDate`/`addressLine1`/`city`/`country` 等、就业与资金来源 `employmentStatus`/`occupation`/`sourceOfFunds`/`sourceOfWealth` 等）。完整字段以申请卡接口规格为准。
## 请求片段示例（脱敏）
> 以下 `kycInfo` 片段所有取值均为占位符，**请勿写入任何真实用户 PII（手机号/邮箱/证件/地址）或真实 token**。
```json theme={null}
{
"externalUserId": "",
"categoryId": 0,
"applyRef": "",
"kycInfo": {
"sumsubShareToken": "_act-sbx-***",
"email": "user@example.com",
"occupation": "",
"sourceOfFunds": ""
}
}
```
## 沙盒测试：生成模拟 KYC token
在沙盒（UAT）联调阶段，若您尚未接入真实的 Sumsub share token，可调用 DCS 提供的**模拟 token 接口**生成一个测试用 token：
POST `/simulation/v1/generate-kyc-token`
| 参数 | 类型 | 必填 | 说明 |
| ---------------- | ------ | -- | ------- |
| `externalUserId` | string | 是 | 外部用户 ID |
响应结构统一为 `{ code, message, messageDetail, data }`（无 `success` 布尔字段），模拟 token 在 `data.token` 中返回。其中 `messageDetail` 是一个对象结构（`message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`，正常成功时各字段为空），并非 `null`：
```json theme={null}
{
"code": "<成功码>",
"message": "",
"messageDetail": {
"message": "",
"title": "",
"type": "",
"icon": "",
"action": "",
"linkTitle": "",
"linkUrl": ""
},
"data": {
"token": "<模拟 token>"
}
}
```
**这是模拟/沙盒专用 token**，仅用于沙盒联调，与生产环境真实的 Sumsub share token 是两回事，请勿混用，也不要在生产环境使用。
## 常见问题排障
如果 Sumsub token 共享未按预期工作，请按以下常见原因逐项排查：
| 问题 | 症状 | 排查与解决 |
| -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Token 已被使用 | 提交申请后提示 token 无效或已过期 | Sumsub 的 share token **仅限一次性使用**。每次提交新的申请卡请求，请为同一申请人重新生成一个 share token，勿复用旧 token。 |
| 沙盒/生产环境不匹配 | token 在某一环境有效、另一环境报无效 | 您在 Sumsub 生成 token 时的环境（沙盒 / 生产）须与 DCS 当前对接环境一致。沙盒 token 不能用于 DCS 生产环境，反之亦然。切换环境时请确认 Sumsub Dashboard 底部的环境指示（黄色横幅 = 沙盒模式）。 |
| Sumsub 侧必要字段缺失 | KYC 申请创建失败或审核退回 | 如果您在 Sumsub 侧的申请人资料中缺少 DCS 要求的必要字段（如姓名、出生日期、国籍、地址等），DCS 将无法完成审核。**请提前向 DCS 确认当前卡项目（Program）在 Sumsub 侧的必配字段清单**，并确保生成 share token 前申请人资料中的所有必配字段均已填写完整。 |
> 若以上排查仍未解决，请联系 DCS 技术支持并提供具体的错误信息与发生时间。
## Sumsub POI / POA 配置基准（必读）
为确保您发送给 DCS 的 Sumsub token 能够通过验证，您在 Sumsub 后台的 POI（身份证明）与 POA（地址证明）配置**必须与 DCS 完全一致**。请严格按照以下截图进行配置；若配置不一致，将导致 token 无法通过验证、影响上线。
本配置可能因合规或监管要求的更新而不时调整，请以 DCS 最新通知为准。各国可接受证件类型及是否需要额外提供 POA 的对照表，详见 [KYC 证件说明](./kyc-documents)。
### 一、POI（身份证明）配置
#### 1. 身份验证
#### 2. 支持的身份证件
##### 2.1 黑名单国家（34 国）
以下证件一律**不接受**：护照、身份证、驾照及居留许可。
黑名单国家（34 国）：阿富汗、白俄罗斯、波斯尼亚和黑塞哥维那、布隆迪、中非共和国、刚果（金）、古巴、危地马拉、几内亚、几内亚比绍、海地、伊朗、伊拉克、黎巴嫩、利比亚、马里、摩尔多瓦、黑山、缅甸、尼加拉瓜、尼日尔、朝鲜、俄罗斯、塞尔维亚、索马里、南苏丹、苏丹、叙利亚、突尼斯、土耳其、乌克兰、委内瑞拉、也门、津巴布韦。
##### 2.2 对指定 9 国接受 POI 作为 POA
支持国家：台湾、澳大利亚、日本、韩国、越南、菲律宾、马来西亚、泰国、新加坡。请在 Sumsub 中按下列截图配置各国可接受的证件类型与子类型（subtype）。
**台湾 Taiwan** —— 接受护照（Passport）、身份证（ID Card，仅子类型 `twn.id.type1`）
**澳大利亚 Australia** —— 仅接受护照（Passport）
**日本 Japan** —— 接受护照、My Number Card、驾照（IP 地址须位于日本，若不符合要求，用户需额外提交护照进行验证）
**韩国 South Korea** —— 接受护照、身份证（仅子类型 `kor.id.type1`）
**越南 Vietnam** —— 接受护照、身份证（仅子类型 `vnm.id.type3`、`vnm.id.type4`）、驾照（仅子类型 `vnm.drvlic.type1`）
**菲律宾 Philippines** —— 接受护照、身份证（仅子类型 `phl.id.type11`）、驾照（仅子类型 `phl.drvlic.type1`）
**马来西亚 Malaysia** —— 接受护照、身份证（仅子类型 `mys.id.type1`）、驾照（仅子类型 `mys.drvlic.type1`）
**泰国 Thailand** —— 接受护照、泰国国家身份证（Thai National ID Card）
**新加坡 Singapore** —— 接受护照、新加坡身份证（NRIC）
#### 2.3 USA
#### 2.4 其他国家
护照 —— 仅单面；身份证、驾照及居留许可一律不接受。
### 二、POA（地址证明）配置
#### 1. 验证流程配置
如果 POI 证件不包含地址信息，用户将进入 POA（地址证明）验证流程。如果 POI 证件包含地址信息，但地址所属国家为日本且用户 IP 不在日本境内，则用户需额外提交护照以确认其国籍。
#### 2. 用户验证
注意：仅接受来自指定国家的地址证明（POA），具体以您与 DCS 的协议约定为准。
#### 3. 验证级别
**须拒绝美国居民的申请**（USA residents need to be rejected）。
***
## 下一步
* 共享资料被拒时的补件路径：[KYC 拒绝与补件](./kyc-rejections)
* 可接受的证件类型与 POA 要求：[KYC 证件说明](./kyc-documents)（同组）
* 合规能力总览与各子页导航：[合规 · 概述](../basic-concepts/compliance-kyc-flow)
* 申请卡接口完整字段规格：`POST /card/v1/virtual-card/apply`