申请 KYC - DCS Technical Documentation

方式一：Sumsub Share Token —— 用户已在接入机构自建的 Sumsub 完成认证，直接把 Share Token 交给 DCS，免传证件文件；
方式二：证件文件上传 —— 由接入机构自行收集证件并上传给 DCS。

两种方式创建同一种 KYC 工单，状态机与查询/回调完全一致。

📄 正文

无论您是交易所、钱包还是平台方，都可以通过一次 API 调用把用户 KYC 信息提交给 DCS——这是为该用户开卡前的必要一步。DCS 作为新加坡 MAS 持牌发卡机构，会安全接收资料、按反洗钱（AML）规则评估风险，并通过 Webhook 回传认证结果。

谁做什么

步骤	谁做	说明
收集用户身份/职业信息	接入机构	Sumsub 路径：在自建 Sumsub 完成认证得到 Share Token；上传路径：准备证件文件与职业信息
上传文件、提交 KYC 申请	接入机构	走上传路径时先换取 S3 预上传 URL、把文件 PUT 上去，再调 `apply-kyc`
证件核验、AML 风控、人工复核	DCS	接收后异步处理
回传状态与结果	DCS	通过查询接口或 `KYC_TICKET` Webhook

前置条件

已持有企业（Enterprise）的 ApiKey / SecretKey，参见鉴权指南。
已创建用户，拿到 customerId，参见创建用户。
使用 Sumsub：已在自建 Sumsub 与 DCS 建立 Sharing Partner 关系（参见 KYC 服务商说明），并已取得该用户的 Share Token。
走上传路径：已备好用户证件文件（身份证、护照或驾照等），如涉及地址证明请一并备好。

两种方式怎么选

场景	推荐方式	关键字段
已自建 Sumsub 集成	方式一：Sumsub Share Token	`sumsubShareToken`
未对接 Sumsub，由接入机构自行收料	方式二：证件文件上传	`identifyProofList` / `addressProofList`

区分逻辑：证件文件字段（identifyProofList / addressProofList）留空时，DCS 跳过相关校验；提交后则按枚举与长度校验。DCS 使用 sumsubShareToken 获取用户已在 Sumsub 完成认证的资料。证件文件与 Share Token 可以同时提交，具体处理方式以接入时确认的 KYC 配置为准。两种方式都需要提交职业信息（kycCareerInfo）。

最小请求

POST /open-api/kyc-ticket/v1/apply-kyc

{
  "kycTicketRef": "kyc-20260617-0001",
  "customerId": "CUST_8f3a...",
  "sumsubShareToken": "_act-xxxxxxxxxxxxxxxxxxxxxx",
  "kycCareerInfo": {
    "employmentStatus": "EMPLOYED",
    "employerName": "Acme Pte Ltd",
    "employmentJobIndustry": "INFORMATION",
    "occupation": "IT_CONSULTANT",
    "jobSeniority": "EXECUTIVE",
    "purposeOfAccount": "DAILY_SPENDING",
    "sourceOfFunds": "EMPLOYMENT",
    "sourceOfFundsCountry": "SG",
    "sourceOfWealth": "EMPLOYMENT"
  }
}

使用 Sumsub 路径时，identifyProofList / addressProofList 可留空；DCS 会使用 sumsubShareToken 获取用户已认证的证件资料。

方式二：证件文件上传

步骤 1：上传证件文件

身份/地址证明文件不是把图片直接塞进申请请求，而是先换取 S3 预上传链接、把文件 PUT 上去，再在申请时引用返回的 objectKey。调用 POST /open-api/intent-ticket/v1/generate-pre-upload-url，businessType 传 CREATE_CARD_KYC：

{
  "fileNames": ["id_front.jpg", "id_back.jpg"],
  "businessType": "CREATE_CARD_KYC"
}

接口返回每个文件对应的临时上传 URL 与 objectKey。把文件 PUT 到该 URL 后，记下 objectKey——下一步的 identityProofUrl / addressProofUrl 字段填的就是这个 objectKey，而不是完整 URL。

步骤 2：提交 KYC 申请

POST /open-api/kyc-ticket/v1/apply-kyc

{
  "kycTicketRef": "kyc-20260617-0001",
  "customerId": "CUST_8f3a...",
  "identifyProofList": [
    {
      "identityProofUrl": "<步骤 1 返回的 objectKey>",
      "identityProofType": "PASSPORT",
      "identityProofSubType": "EMPTY",
      "identityProofIssuedCountry": "SG"
    }
  ],
  "kycCareerInfo": {
    "employmentStatus": "EMPLOYED",
    "employerName": "Acme Pte Ltd",
    "employmentJobIndustry": "INFORMATION",
    "occupation": "IT_CONSULTANT",
    "jobSeniority": "EXECUTIVE",
    "purposeOfAccount": "DAILY_SPENDING",
    "sourceOfFunds": "EMPLOYMENT",
    "sourceOfFundsCountry": "SG",
    "sourceOfWealth": "EMPLOYMENT"
  }
}

请求字段总览

通用字段（两种方式都适用）

字段	类型	必填	说明
`kycTicketRef`	string	是	KYC 幂等号；最大 50。同一引用重复提交不会重复建单
`customerId`	string	是	用户 ID；最大 50
`kycCareerInfo`	object	见说明	职业信息（见下）。与 `kycCareerInfoEncryption` 至少填其一
`kycCareerInfoEncryption`	string	见说明	`kycCareerInfo` JSON 的密文，AES-GCM 模式。与 `kycCareerInfo` 至少填其一；两者都有时优先使用密文
`encryptionIV`	string	条件	AES-GCM 的 IV，用于解密 `kycCareerInfoEncryption`；传密文时必填

方式一专用字段

字段	类型	必填	说明
`sumsubShareToken`	string	方式一必填	Sumsub Share Token；最大 500。用于获取已认证资料，使用此方式时证件文件字段可留空

方式二相关字段

字段	类型	必填	说明
`identifyProofList`	object[]	方式二建议传	身份证明文件列表（见下）
`addressProofList`	object[]	方式二可选	地址证明文件列表（见下）；最多 5 条

字段拼写注意：外层列表字段名为 identifyProofList（identify），其内层字段以 identityProof*（identity）开头，两者前缀不同，请严格按本表拼写传参。

identifyProofList 及其内层的 identityProofType / identityProofIssuedCountry 在接口层面均为非必填——这是为了让 Sumsub 路径可以只传 sumsubShareToken。但走自行上传证件的路径时，这三项业务上必须提供，否则无法完成认证。

identifyProofList[] 身份证明文件

字段	类型	必填	说明
`identityProofUrl`	string	否	文件的 `objectKey`（步骤 1 返回）；最大 512。自行上传证件时必须提供
`identityProofType`	string	否	枚举：`ID_CARD` / `DRIVERS` / `PASSPORT`；最大 32。自行上传证件时必须提供
`identityProofSubType`	string	否	枚举：`FRONT_SIDE` / `BACK_SIDE` / `EMPTY`（单面或无正反面之分时传 `EMPTY`）；最大 32
`identityProofIssuedCountry`	string	否	签发国家，2 位 ISO 国家码。自行上传证件时必须提供

addressProofList[] 地址证明文件

字段	类型	必填	说明
`addressProofUrl`	string	否	文件的 `objectKey`；最大 512。自行上传地址证明时必须提供
`addressProofType`	string	列表非空时必填	枚举：`UTILITY_BILL`；最大 32。列表非空而此字段留空会报 `DAPI_SYS_ILLEGAL_PARAM`
`addressProofIssuedCountry`	string	否	签发国家，2 位 ISO 国家码

`kycCareerInfo` 职业信息（两种方式共同必填）

字段	类型	必填	说明
`employmentStatus`	string	是	就业状态；最大 32
`employerName`	string	条件	雇主名称；当 `employmentStatus=EMPLOYED` 时必填；最大 50
`employmentJobIndustry`	string	是	就业行业；最大 32
`occupation`	string	是	职业；最大 32
`jobSeniority`	string	是	工作资历；最大 32
`purposeOfAccount`	string	是	开户目的；最大 32
`sourceOfFunds`	string	是	资金来源；最大 32
`sourceOfFundsCountry`	string	是	资金来源国家，2 位 ISO 国家码
`sourceOfWealth`	string	是	财富来源；最大 32

职业信息为敏感数据。若需端到端加密，把 kycCareerInfo 序列化为 JSON 后用 AES-GCM 加密，密文放入 kycCareerInfoEncryption、IV 放入 encryptionIV，此时可不传明文 kycCareerInfo。上述字段由服务端枚举校验，并非任意字符串。完整取值见 KYC 申请参数字典。

响应

所有 /open-api/ 接口共用统一响应结构 { code, message, messageDetail, data }。成功时 data 返回新建的 KYC 工单：

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "kycTicketId": "KYC_1a2b...",
    "kycTicketRef": "kyc-20260617-0001",
    "customerId": "CUST_8f3a...",
    "status": "INIT",
    "createTime": "2026-06-17T08:00:00+08:00"
  }
}

响应结构说明：业务成败以 code（如 SYS_SUCCESS）为准，message 为简要文案；messageDetail 是可选的展示对象（含 message / title / type / icon / action / linkTitle / linkUrl），用于前端引导，不应作为判断成败的依据。

请注意：HTTP 200 + code=SYS_SUCCESS 仅代表申请已受理，不代表 KYC 通过。提交成功后 status 通常为 INIT，最终结果需经查询接口或 Webhook 获取。

响应字段	说明
`kycTicketId`	KYC 申请 ID，后续查询/引用以此为准
`kycTicketRef`	回显的幂等号
`customerId`	用户 ID
`status`	KYC 工单状态：`INIT` / `NEED_VERIFY` / `PENDING` / `PASSED` / `REJECTED`
`createTime`	创建时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`（与平台其他接口一致）

跟进认证结果

提交后，KYC 工单会在以下状态间流转（两种方式共用同一状态机）：

状态	含义	终态	接入机构下一步
`INIT`	信息已提交	否	等待系统处理
`NEED_VERIFY`	等待人脸认证	否	获取人脸引导页链接，引导用户完成人脸认证
`PENDING`	审核中	否	等待系统审核
`PASSED`	审核通过	是	可继续后续操作（如申请虚拟卡）
`REJECTED`	审核拒绝	是	可凭新的 `kycTicketRef` 重新提交

当 status=REJECTED 时，查询 KYC 接口与 KYC_TICKET Webhook 会返回 errorCode 与 errorMessage 表示拒绝原因，对应处置见 KYC 拒绝错误码。状态更新建议通过 Webhook 订阅获取，避免轮询；详见 Webhook 数据结构。

下一步

KYC 通过（status=PASSED）后，即可前往开卡流程为该用户开卡。若状态停在 NEED_VERIFY，先到人脸引导页引导用户完成人脸认证。

​📄 正文

​谁做什么

​前置条件

​两种方式怎么选

​方式一：Sumsub Share Token

​最小请求

​方式二：证件文件上传

​步骤 1：上传证件文件

​步骤 2：提交 KYC 申请

​请求字段总览

​通用字段（两种方式都适用）

​方式一专用字段

​方式二相关字段

​kycCareerInfo 职业信息（两种方式共同必填）

​响应

​跟进认证结果

​下一步

📄 正文

谁做什么

前置条件

两种方式怎么选

方式一：Sumsub Share Token

最小请求

方式二：证件文件上传

步骤 1：上传证件文件

步骤 2：提交 KYC 申请

请求字段总览

通用字段（两种方式都适用）

方式一专用字段

方式二相关字段

`kycCareerInfo` 职业信息（两种方式共同必填）

响应

跟进认证结果

下一步