跳转到内容

查询 KYC 补件信息 ​

GET /openapi/v1/users/kyc/supplement/context

读取当前租户已保存的补件资格、资料记录号、补件业务版本及原资料。查询只读取信息,不提交资料、不冻结费用,也不主动刷新服务方状态。请求加签和响应验签沿用加签说明。

查询结果是一份当前快照,不会占用补件资格;正式提交时后台还会重新校验。

请求参数 ​

字段类型必填说明
emailstring是当前租户已创建用户的邮箱;补件不能修改原邮箱。
cardTypeIdstring是实际平台卡产品 ID,沿用 V1 查询契约必填;V1 仍按万事达香港美元卡的既有规则查询。

请求示例 ​

HK_USD 为平台卡产品 ID 占位值,请替换为实际 ID。

http
GET /openapi/v1/users/kyc/supplement/context?email=user%40example.com&cardTypeId=HK_USD

响应 data ​

字段类型说明
allowedboolean当前是否允许补件;只有为 true 时才继续准备提交。
reasonstring/null不允许补件的原因;允许时通常为空。用于展示,不作为固定枚举判断。
originalRecordNostring/null最新的平台资料记录号,补件提交时原样带回;不是服务方的 kycRecordId。
expectedVersioninteger(int64)/null非负补件业务版本,必须与 originalRecordNo 一起原样带回,不自行生成或加一。
applicationNostring/null关联原费用的平台根申请号;多次补件资料可以属于同一申请。不需要提交,不能代替 originalRecordNo。
lockedFieldsstring[]当前产品不允许修改的字段名;提交时保留原值。空数组也不表示可以修改邮箱或绕过资料校验。
submissionobject/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 失效,即使版本数字相同也不能使用旧记录号。
  1. 检查 allowed;不允许时展示 reason,等待状态恢复或按原因进入新申请流程。
  2. 修改允许修改的资料,锁定字段保留原值。
  3. 将完整 KYC 参数、新的 requestNo、查询返回的 originalRecordNo 和 expectedVersion 一起调用提交用户 KYC。
  4. 按提交接口的受理结果、冲突和未知结果规则处理;只查询本接口不会完成补件。