Skip to main content

​
📄 正文

KYC 工单（KYC Ticket）把「用户是否通过 KYC」从账户级状态细化到每一次进件：这一次走到了哪一步、为什么没过、什么时候可以开卡。工单与卡申请单是两层——先有 PASSED 的工单，再凭它建卡申请单。状态每次变化都会通过 KYC_TICKET Webhook 通知您，也可以随时用 detail 查询。
KYC 工单状态机KYC 工单状态机
图中画的是最长路径。PENDING 不是必经状态：API 模式的工单在风控回查时可能直接从 INIT 或 NEED_VERIFY 落到 PASSED / REJECTED。请按实际收到的 status 处理，不要假设状态一定逐级推进。

​
两种进件模式

存量接入不受影响：不建单直接调 guidance-link（action=KYC_GUIDE）仍可用，DCS 会在签发链接时为该用户复用或新建 H5 工单。工单号不在该接口返回，但新建时会推一条 KYC_TICKET Webhook 带出 kycTicketId，凭它即可用 detail 查询。KYC_GUIDE 不读 kycTicketId，传了也不会被使用，工单号以 KYC_TICKET Webhook 带出的为准；要凭自己建的工单换链接，请用 KYC_APPLY。

​
工单状态

渠道建单时，该用户只要已有任何在途（非终态）工单即被拒，包括服务端在签发 action=KYC_GUIDE 引导链接时自动建的 H5 工单；而自动建单只看有没有在途的 H5 工单、不看 API 工单，因此一个用户可能同时持有一张渠道建的 API 工单与一张服务端自动建的 H5 工单。自动建的工单会占用「在途工单」名额且不会过期回收——用户取过链接但始终没提交时，该工单停在 INIT，渠道调 apply-kyc 会一直收到 KYC_TICKET_IS_IN_PROCESSING，打算走 API 模式就不要先给该用户签发 KYC_GUIDE 链接。同一 kycTicketRef 重复建单：apply-kyc 一律返回 KYC_TICKET_REF_NOT_UNIQUE（超时需确认结果时按 kycTicketRef 查单）；apply-kyc-h5 在原单仍为 INIT 时幂等返回原单（网络重试场景）；原单已到 PENDING 及以后按状态拒绝（KYC_TICKET_IS_IN_PROCESSING / KYC_TICKET_ALREADY_PASSED / KYC_TICKET_VERIFY_FAIL）；换 kycTicketRef 重建而在途单仍存在时返回 KYC_TICKET_IS_IN_PROCESSING。

​
四种失败去向

​
API 直传：职业信息密文

encryptedKycCareerInfo = Base64( AES-GCM( key = Base64Decode(SecretKey), iv = Base64Decode(iv), plaintext = careerInfo 的 JSON ) )，认证标签 128 位。DCS 用请求头 X-DAPI-API-KEY 反查您的 SecretKey 解密，不落明文日志。明文 careerInfo 与密文至少传一个，都传以密文为准。

​
凭工单申请虚拟卡

工单 PASSED 后，调用 POST /card/v1/virtual-card/apply 传 cardApplyMode=NORMAL + kycTicketId，无需再内联 kycInfo；不传 cardApplyMode 即为 COMPLETE，与改造前完全一致。工单不绑定卡产品：KYC 结果是用户级的，一张 PASSED 工单可为该用户申请任意卡产品的多张卡。申请与详情响应新增 kycTicketId / cardApplyMode。详见 申请卡。

​
引导链接时效与人脸页错误

  • 链接中的 secret 300 秒内一次性有效，页面打开后建立 1 小时会话；过期需重新换链接，工单不受影响。
  • 人脸页可能返回：PERMISSION_DENIED（链接已用过/过期）、SUMSUB_TOKEN_NOT_FOUND（会话不是人脸场景或工单不属于当前用户）、KYC_TICKET_STATUS_NOT_LIVENESS（工单已提交或终态）。前两个码只由人脸页返给前端，不出现在渠道 API 的响应里，列在这里是便于您排查用户反馈；KYC_TICKET_STATUS_NOT_LIVENESS 在您用 action=KYC_LIVENESS 调 guidance-link 而工单已到 PENDING 或终态时，也会直接返回给您。

​
错误码

对外返回时错误码沿用所在模块前缀（如 CARD_KYC_TICKET_NOT_FOUND），请按实际字符串匹配。审核拒绝（REJECTED）的 errorCode：API 模式取风控码表，与卡申请一致，见 申请数据字典；H5 模式为 KYC_REJECTED，具体原因在 errorMessage 里；用户未在 Sumsub 时限内完成时为 TIMEOUT，可引导用户重新发起。

​
相关接口

  • POST /kyc-ticket/v1/apply-kyc-h5 / POST /kyc-ticket/v1/apply-kyc / GET /kyc-ticket/v1/detail：见 API 参考
  • POST /redirect/v2/guidance-link：新增 kycTicketId、categoryId 与 action=KYC_APPLY / KYC_LIVENESS，见 H5 引导页
  • KYC_TICKET Webhook：见 Webhook 与 WebSocket