查询 KYC 补件信息
GET/openapi/v1/users/kyc/supplement/context读取当前租户已保存的补件资格、资料记录号、补件业务版本及原资料。查询只读取信息,不提交资料、不冻结费用,也不主动刷新服务方状态。请求加签和响应验签沿用加签说明。
查询结果是一份当前快照,不会占用补件资格;正式提交时后台还会重新校验。
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
email | string | 是 | 当前租户已创建用户的邮箱;补件不能修改原邮箱。 |
cardTypeId | string | 是 | 实际平台卡产品 ID,沿用 V1 查询契约必填;V1 仍按万事达香港美元卡的既有规则查询。 |
请求示例
HK_USD 为平台卡产品 ID 占位值,请替换为实际 ID。
http
GET /openapi/v1/users/kyc/supplement/context?email=user%40example.com&cardTypeId=HK_USD响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
allowed | boolean | 当前是否允许补件;只有为 true 时才继续准备提交。 |
reason | string/null | 不允许补件的原因;允许时通常为空。用于展示,不作为固定枚举判断。 |
originalRecordNo | string/null | 最新的平台资料记录号,补件提交时原样带回;不是服务方的 kycRecordId。 |
expectedVersion | integer(int64)/null | 非负补件业务版本,必须与 originalRecordNo 一起原样带回,不自行生成或加一。 |
applicationNo | string/null | 关联原费用的平台根申请号;多次补件资料可以属于同一申请。不需要提交,不能代替 originalRecordNo。 |
lockedFields | string[] | 当前产品不允许修改的字段名;提交时保留原值。空数组也不表示可以修改邮箱或绕过资料校验。 |
submission | object/null | 允许补件时返回的原 KYC 资料,用于回填和修改;不允许时为空或省略。首次尚未申请时没有原资料记录。 |
资料字段沿用提交用户 KYC。副本还可能包含用于回显的 firstName、lastName。提交时按该接口接收的字段组装,并补上用户 memberId;不要将整个查询响应直接作为提交请求。可选空字段可能返回 null 或省略。
允许补件的响应示例
示例数据均为虚构,下面以万事达香港美元卡为例。
json
{
"code": 200,
"msg": "操作成功",
"data": {
"allowed": true,
"reason": null,
"originalRecordNo": "KYC_RECORD_002",
"expectedVersion": 3,
"applicationNo": "KYC_RECORD_001",
"lockedFields": [],
"submission": {
"email": "user@example.com",
"name": "Test User",
"birthday": "1990-01-01",
"documentType": "passport",
"documentNumber": "SYNTHETIC_ONLY",
"frontImageUrl": "https://files.example.com/kyc/front.jpg",
"backImageUrl": null,
"documentCountry": "HK",
"documentExpiryDate": "2030-12-31",
"documentPermanentlyValid": false,
"selfieImageUrl": "https://files.example.com/kyc/selfie.jpg",
"phoneCountryCode": "+852",
"phoneNumber": "00000000",
"gender": "male",
"annualIncome": "50000-200000",
"occupation": "Engineer",
"position": "Company Owner",
"nationality": "HK",
"contactAddress": "Original contact address",
"supportingDocuments": [],
"firstName": "Test",
"lastName": "User",
"residentialCity": null,
"residentialCountryCode": null,
"residentialPostalCode": null,
"residentialState": null
}
}
}不允许补件的响应示例
code=200 只代表查询成功,不代表允许补件。以下为认证已经成功的场景;实际拒绝原因以 reason 为准。
json
{
"code": 200,
"msg": "操作成功",
"data": {
"allowed": false,
"reason": "认证已成功,不能补件",
"originalRecordNo": "KYC_RECORD_003",
"expectedVersion": 4,
"applicationNo": "KYC_RECORD_001",
"lockedFields": [],
"submission": null
}
}补件资格与锁定字段
V1 沿用万事达香港美元卡的既有路由。认证尚未成功,且原申请仍具备补件资格时可以补件;已经明确失败的申请,需在原费用释放完成后按新申请重新提交。
还需同时满足:平台已开放补件、原申请状态明确、原费用仍可沿用。提交处理中或结果未知时,需由平台完成状态同步或恢复后再查询。
该产品当前返回的 lockedFields 为空数组,实际仍以接口返回值为准,且始终不能通过补件修改原邮箱。万事达全球美元卡请使用 V2 查询 KYC 补件信息。
业务版本与后续提交
| 发生的变化 | 对补件依据的影响 |
|---|---|
| 普通同步且审核依据不变,仅更新时间、提示或查询失败 | 不因此增加补件业务版本;状态未知仍可能导致不允许补件。 |
| 审核进入通过/失败、补件资格变化,或关联身份/申请变化 | 补件业务版本可能推进,需要重新查询补件信息。 |
| 另一笔提交产生新资料记录 | 旧 originalRecordNo 失效,即使版本数字相同也不能使用旧记录号。 |
- 检查
allowed;不允许时展示reason,等待状态恢复或按原因进入新申请流程。 - 修改允许修改的资料,锁定字段保留原值。
- 将完整 KYC 参数、新的
requestNo、查询返回的originalRecordNo和expectedVersion一起调用提交用户 KYC。 - 按提交接口的受理结果、冲突和未知结果规则处理;只查询本接口不会完成补件。
