Sumsub KYC 资料共享 - DCS Technical Documentation

📄 正文

如果您已使用 Sumsub 作为合规（身份验证）供应商，可以通过 Sumsub 的 共享伙伴（Sharing Partners） 机制，把已采集的用户验证资料共享给 DCS，从而简化 KYC 流程——无需让终端用户在 DCS 侧重复完成一次身份验证。接入完成后，您在申请卡（开卡）请求中传入一个 Sumsub share token（字段 kycInfo.sumsubShareToken），DCS 即可凭该 token 从 Sumsub 获取并复用对应用户的验证资料，进入 KYC 审核后续流程。

Sumsub token 共享需在沙盒（UAT）与生产（PROD）两套环境分别配置一次。沙盒环境的 token 不能用于生产，反之亦然——配置时务必确认环境一致。

两种接入方向

根据「谁采集、谁复用」用户验证资料，您与 DCS 之间存在两种 token 添加方向。请按您的实际角色选择对应步骤。

按角色配置 token 共享方向

若您是数据提供方（由您采集验证资料、共享给 DCS）：

向 DCS 团队获取 UAT 与 PROD 对应的 partner token。
在您的 Sumsub 平台进入 Sharing Partners（参考 Sumsub 文档），按提示添加该 token。
与 DCS 团队核对——DCS 的 Sumsub 平台应能看见您在 Sumsub 注册的名称。

数据提供方：在自己的 Sumsub 平台 Sharing Partners 添加 token

若您是数据收取方（由 DCS 采集验证资料、共享给您；或您需要把 token 提供给 DCS）：

在您的 Sumsub 平台获取 UAT 与 PROD 对应的 token，并分享给 DCS 员工。
DCS 添加完成后，请在您的 Sumsub 平台确认 Donor 一览中可见 DCS，并通知 DCS 结果。

在 Sumsub 侧为目标申请人生成 share token。share token 形如 _act-sbx-***（沙盒）/ _act-***（生产），仅供示意，请勿写入任何真实 token。

Sumsub 的 share token 通常一次性使用，每次提交申请请生成新的 token；环境（沙盒/生产）须与 DCS 当前对接环境一致。

在申请虚拟卡 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。

{
  "externalUserId": "<externalUserId>",
  "categoryId": 0,
  "applyRef": "<applyRef-幂等键>",
  "kycInfo": {
    "sumsubShareToken": "_act-sbx-***",
    "email": "user@example.com",
    "occupation": "<occupation>",
    "sourceOfFunds": "<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：

{
  "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 证件说明。

一、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）。

Verification level - USA residents rejected

下一步

共享资料被拒时的补件路径：KYC 拒绝与补件
可接受的证件类型与 POA 要求：KYC 证件说明（同组）
合规能力总览与各子页导航：合规 · 概述
申请卡接口完整字段规格：POST /card/v1/virtual-card/apply

​📄 正文

​两种接入方向

​按角色配置 token 共享方向

​步骤 3：生成 share token

​步骤 4：在申请卡请求中使用 share token

​请求片段示例（脱敏）

​沙盒测试：生成模拟 KYC token

​常见问题排障

​Sumsub POI / POA 配置基准（必读）

​一、POI（身份证明）配置

​1. 身份验证

​2. 支持的身份证件

2.1 黑名单国家（34 国）

2.2 对指定 9 国接受 POI 作为 POA

​2.3 USA

​2.4 其他国家

​二、POA（地址证明）配置

​1. 验证流程配置

​2. 用户验证

​3. 验证级别

​下一步

📄 正文

两种接入方向

按角色配置 token 共享方向

步骤 3：生成 share token

步骤 4：在申请卡请求中使用 share token

请求片段示例（脱敏）

沙盒测试：生成模拟 KYC token

常见问题排障

Sumsub POI / POA 配置基准（必读）

一、POI（身份证明）配置

1. 身份验证

2. 支持的身份证件

2.3 USA

2.4 其他国家

二、POA（地址证明）配置

1. 验证流程配置

2. 用户验证

3. 验证级别

下一步