跳转到内容

提交用户 KYC ​

POST /openapi/v1/users/kyc
项内容
请求方法POST
请求路径/openapi/v1/users/kyc
请求类型application/json

请求参数 ​

字段类型必填说明
requestNostring条件补件必填,新申请可选;1–64 位字母、数字、下划线或短横线,租户内 KYC 请求唯一。相同请求重试复用,新提交使用新号。
originalRecordNostring条件补件必填:查询补件信息返回的最新平台资料记录号;首次申请或失败后新申请不传。
expectedVersioninteger(int64)条件补件必填:查询返回的非负补件业务版本,与 originalRecordNo 一起原样提交;新申请不传,审核依据不变的普通同步不使其过期。
emailstring是用户邮箱,按现有接口契约使用。
namestring是姓名。
birthdaystring是生日,格式为 yyyy-MM-dd。
documentTypestring是证件类型:passport、id_card 或 driver_license。
documentNumberstring是证件号码。
documentCountrystring是证件签发国家/地区,两位代码,例如 HK。
documentExpiryDatestring条件证件有效期,格式为 yyyy-MM-dd;与 documentPermanentlyValid 二选一。
documentPermanentlyValidboolean条件证件永久有效时传 true;与 documentExpiryDate 二选一。传 false 时仍须提供有效期。
frontImageUrlstring是证件正面图片上传后返回的 URL。
backImageUrlstring条件证件背面图片上传后返回的 URL;id_card 和 driver_license 必须提供,passport 可不提供。
selfieImageUrlstring是身份自拍图片上传后返回的 URL。
phoneCountryCodestring是手机号国家区号,例如 +852。
phoneNumberstring是仅数字,4 到 20 位。
genderstring是性别:male 或 female。
annualIncomestring是年收入区间:<20000、20000-50000、50000-200000、200000-500000 或 >500000。
occupationstring是职业。
positionstring是职位。
nationalitystring是国籍,两位国家/地区代码。
contactAddressstring是联系地址。
supportingDocumentsarray条件非 HK 用户必须提供,至少 1 项,最多 10 项;HK 用户可不传。详见下表。
memberIdstring是平台成员 ID,仅用于平台定位用户,不会发送给服务提供方。

supportingDocuments 项 ​

字段类型必填说明
documentTypestring是使用上传 KYC 图片中的辅助证明类型,与上传时的 supportingDocumentType 保持一致。按类型提交 PDF 或图片;资料分类不代表所有卡产品均支持受理。
fileUrlstring是辅助证明上传后返回的稳定 url,不要使用临时 previewUrl。

辅助证明上传时须传 purpose=SUPPORTING_DOCUMENT 和对应的 supportingDocumentType。通行证正反面须分别上传,并在本数组中成对提供 TRAVEL_PERMIT_FRONT 和 TRAVEL_PERMIT_BACK;两面均支持图片或 PDF。

有效期字段必须且只能选择一种:

  • 有有效期的证件:传 documentExpiryDate,不要传 documentPermanentlyValid。
  • 永久有效的证件:传 documentPermanentlyValid: true,不要传 documentExpiryDate。

有效期与 documentPermanentlyValid: true 同时提供,或二者都未提供时拒绝。false 与有效期一起提供可以通过该二选一校验。

主证件、自拍及辅助证明文件须先通过上传 KYC 图片取得 url,再提交 KYC。主证件与自拍仅支持 JPG/JPEG/PNG;辅助证明格式按材料类型确定。

请求示例 ​

json
{
  "email": "user@example.com",
  "name": "Test User",
  "birthday": "1990-01-01",
  "documentType": "passport",
  "documentNumber": "P1234567",
  "documentCountry": "HK",
  "documentExpiryDate": "2030-12-31",
  "frontImageUrl": "https://example.com/front.jpg",
  "selfieImageUrl": "https://example.com/selfie.jpg",
  "phoneCountryCode": "+852",
  "phoneNumber": "91234567",
  "gender": "male",
  "annualIncome": "50000-200000",
  "occupation": "Engineer",
  "position": "Senior Engineer",
  "nationality": "HK",
  "contactAddress": "Hong Kong",
  "memberId": "member-123"
}

补件提交 ​

补件继续调用本页 POST 接口,没有单独的补件 POST 路径。

  1. 先使用 email 和 cardTypeId 查询 KYC 补件信息。
  2. 只有 allowed=true 时继续。以原资料为基础准备完整 KYC 参数,锁定字段与原邮箱保持不变。
  3. 原样携带查询返回的 originalRecordNo、expectedVersion,并为本次提交生成新的 requestNo。
  4. 同时检查外层 code 与 data.submissionStatus,请求处理成功不等于审核通过。

首次申请、明确失败后的新申请,不传 originalRecordNo 和 expectedVersion;建议传 requestNo,便于安全重试。失败后新申请必须等原费用释放完成,并按当前适用的 KYC 价格重新计费。同一申请补件沿用原费用,不重复收费。

完整补件请求示例 ​

下面以万事达香港美元卡为例,数据均为虚构。用户 ID、文件 URL 及补件依据需替换为实际值。V1 仍使用该产品的既有路由。

http
POST /openapi/v1/users/kyc
Content-Type: application/json
json
{
  "email": "user@example.com",
  "memberId": "member-123",
  "requestNo": "KYC_SUPPLEMENT_20261104_001",
  "originalRecordNo": "KYC_RECORD_002",
  "expectedVersion": 3,
  "name": "Test User",
  "birthday": "1990-01-01",
  "documentType": "passport",
  "documentNumber": "SYNTHETIC_ONLY",
  "documentCountry": "HK",
  "documentExpiryDate": "2030-12-31",
  "frontImageUrl": "https://files.example.com/kyc/front.jpg",
  "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": "Updated contact address",
  "supportingDocuments": []
}

业务错误 ​

下表数字为响应正文的 code,不能直接等同于 HTTP 状态码。错误标识位于 msg 前缀中,没有单独的 errorCode 字段。外层结构沿用公共响应。

正文 codemsg 前缀处理方式
400KYC_SUPPLEMENT_INVALID补齐补件三项参数;expectedVersion 必须非负,不能脱离 originalRecordNo 单独传入。
400KYC_REQUEST_INVALID修正请求号格式。
400KYC_SUPPLEMENT_FIELD_DENIED恢复渠道锁定字段,并保持原邮箱不变;修改邮箱的拒绝也可能直接返回说明文字。
409KYC_REQUEST_CONFLICT同一请求号使用了不同资料或请求内容;重试保留原请求,确需新提交时使用新号并接受当前资格校验。
409KYC_VERSION_CONFLICT原资料记录或补件业务版本已过期,重新查询补件信息。
409KYC_SUPPLEMENT_DENIED当前不具备补件资格,按原因处理申请状态或原费用问题。
409KYC_SUPPLEMENT_STATUS_UNKNOWN无法确认服务方当前状态,等待平台同步或恢复后再处理。
409KYC_SUPPLEMENT_STATE_CHANGED服务方当前状态已不允许补件,处理状态后重新查询补件信息。
422KYC_SUPPLEMENT_DISABLED平台已关闭补件,不自动重复提交。

补件依据过期的响应示例:

json
{"code":409,"msg":"KYC_VERSION_CONFLICT: 申请已更新,请刷新补件资格后重试","data":null}

受理结果与重试 ​

本次结果下一步
submissionStatus=ACCEPTED资料已受理,查询后续审核状态,不另换请求号重复提交。
submissionStatus=REJECTED本次明确未受理;平台可能已生成新的资料记录,先重新查询补件信息,修正资料、确认资格后用新请求号提交。
超时、网关/服务错误或 submissionStatus=UNKNOWN保留原请求与原 requestNo。相同内容使用同一请求号重放:已有保存结果时直接返回,不新增资料或费用,结果仍可能为 UNKNOWN;重放不代表强制再次发送服务方。
未知结果后确需修改资料变化内容使用新请求号,由后端判断当前申请能否继续;原结果未恢复明确时仍会被拒绝,换号不能绕过保护。
原记录或版本冲突保留可编辑草稿,重新查询补件信息,恢复锁定字段,确认 allowed=true 后再提交,无需丢弃已填写内容。
allowed=false 或平台关闭补件暂停提交,先完成对应条件处理;反复 GET 查询不会强制同步服务方状态。

审核依据不变的普通同步不会让 expectedVersion 失效。将它视为后台返回的业务版本,不按同步次数推算。每份新资料使用新的 originalRecordNo,不能只比较版本数字。

响应 data ​

字段类型说明
successboolean/null提交受理结果:ACCEPTED 为 true,REJECTED 为 false,UNKNOWN 为 null;不代表审核通过。
codestring/null业务响应码,未取得明确结果时可能为空;与外层响应 code 独立。
messagestring/null业务响应说明,结合 submissionStatus 判断。
externalUserIdstring/null外部用户 ID,服务方尚未返回时可能为空。
kycRecordIdstring/null服务方返回的 KYC 查询标识,可能为空;不是补件使用的平台资料记录号 originalRecordNo。
statusstring/nullFuturePay 统一 KYC 主状态:NOT_SUBMITTED、PENDING(历史兼容)、PENDING_APPROVAL、APPROVED 或 REJECTED。
subStatusstring/null外部渠道原始 KYC 子状态,值域可能扩展;当前已知值为 not_submitted、pending_approval、approved、rejected。
cardAccountIdstring/null外部渠道卡账户 ID;渠道未返回时为 null。
submissionStatusstring/null提交受理结果:ACCEPTED、REJECTED、UNKNOWN;查询时可为空,与审核结果独立。
channelStatusstring/null当前渠道已确认的认证状态,不被本次未受理的提交覆盖。

success 表示请求处理结果,不代表审核通过;submissionStatus 表示提交是否受理,channelStatus 表示当前渠道认证结果。V2 的 status 是用户总体状态,不能据此判断所有渠道均已通过。

可选空值可能返回 null 或省略。submissionStatus=UNKNOWN 时 success 为 null,渠道标识也可能为空,按上文规则处理重试。历史数据可能保留 FAILED,表示平台处理失败,不能单凭此值认定审核拒绝。