查询用户 KYC 信息 - DCS Technical Documentation

📄 正文

除了按工单查询某一次认证的进度，您还可以按用户维度查询该用户当前的 KYC 概要——他的身份证明来自哪个国家、以及他的 KYC 资料是否已到期需要更新。这条接口是您在开卡前做准入判断、以及在日常运营中发现「该用户需要续期」的入口。

两条接口都叫「查 KYC」，但视角不同，容易混：

	查询 KYC 工单	查询用户 KYC 信息（本页）
接口	`GET /open-api/kyc-ticket/v1/detail`	`GET /open-api/kyc/v1/detail`
请求参数	`kycTicketId` 或 `kycTicketRef`	`customerId`
回答的问题	这一次认证进行到哪一步了、被拒的原因是什么	这个用户当前的 KYC 概要，资料是否到期
典型用途	提交 KYC 后轮询结果	开卡前准入判断、发现需要续期

工单维度的查询见查询 KYC。

GET /open-api/kyc/v1/detail

参数	位置	类型	必填	说明
`customerId`	query	string	是	用户 ID（创建用户时返回）

GET /open-api/kyc/v1/detail?customerId=1000000123

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "poiCountryCode": "SG",
    "kycRenewalRequired": false
  }
}

字段	类型	说明
`poiCountryCode`	string	身份证明（POI）签发国家码，2 位 ISO，如 `CN` / `US` / `SG`
`kycRenewalRequired`	boolean	该用户的 KYC 资料是否需要更新。`true` 表示证件 / KYC 资料已到期，需引导用户重新认证

统一响应结构为 { code, message, messageDetail, data }，成败以 code == "SYS_SUCCESS" 判断。字段含义见鉴权指南。

kycRenewalRequired 为 true 表示该用户的证件 / KYC 资料已过期，需要重新完成一次认证。在更新完成前，该用户的部分操作（如消费）可能被限制。 您有两种途径感知这件事，两者取值一致：

主动查：调用本接口，读 kycRenewalRequired。
被动收：DCS 会通过用户级 KYC Webhook 推送 kycRenewalRequired=true，并在 kycRenewalType 中给出需要更新的因子（POI / SELFIE），便于您在前端只提示该补的那一项。

引导用户完成更新的完整两步流程，见更新 KYC 资料。更新通过后，DCS 会再推一条 kycRenewalRequired=false 解除限制。