提交用户 KYC
POST/openapi/v1/users/kyc| 项 | 内容 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /openapi/v1/users/kyc |
| 请求类型 | application/json |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestNo | string | 条件 | 补件必填,新申请可选;1–64 位字母、数字、下划线或短横线,租户内 KYC 请求唯一。相同请求重试复用,新提交使用新号。 |
originalRecordNo | string | 条件 | 补件必填:查询补件信息返回的最新平台资料记录号;首次申请或失败后新申请不传。 |
expectedVersion | integer(int64) | 条件 | 补件必填:查询返回的非负补件业务版本,与 originalRecordNo 一起原样提交;新申请不传,审核依据不变的普通同步不使其过期。 |
email | string | 是 | 用户邮箱,按现有接口契约使用。 |
name | string | 是 | 姓名。 |
birthday | string | 是 | 生日,格式为 yyyy-MM-dd。 |
documentType | string | 是 | 证件类型:passport、id_card 或 driver_license。 |
documentNumber | string | 是 | 证件号码。 |
documentCountry | string | 是 | 证件签发国家/地区,两位代码,例如 HK。 |
documentExpiryDate | string | 条件 | 证件有效期,格式为 yyyy-MM-dd;与 documentPermanentlyValid 二选一。 |
documentPermanentlyValid | boolean | 条件 | 证件永久有效时传 true;与 documentExpiryDate 二选一。传 false 时仍须提供有效期。 |
frontImageUrl | string | 是 | 证件正面图片上传后返回的 URL。 |
backImageUrl | string | 条件 | 证件背面图片上传后返回的 URL;id_card 和 driver_license 必须提供,passport 可不提供。 |
selfieImageUrl | string | 是 | 身份自拍图片上传后返回的 URL。 |
phoneCountryCode | string | 是 | 手机号国家区号,例如 +852。 |
phoneNumber | string | 是 | 仅数字,4 到 20 位。 |
gender | string | 是 | 性别:male 或 female。 |
annualIncome | string | 是 | 年收入区间:<20000、20000-50000、50000-200000、200000-500000 或 >500000。 |
occupation | string | 是 | 职业。 |
position | string | 是 | 职位。 |
nationality | string | 是 | 国籍,两位国家/地区代码。 |
contactAddress | string | 是 | 联系地址。 |
supportingDocuments | array | 条件 | 非 HK 用户必须提供,至少 1 项,最多 10 项;HK 用户可不传。详见下表。 |
memberId | string | 是 | 平台成员 ID,仅用于平台定位用户,不会发送给服务提供方。 |
supportingDocuments 项
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
documentType | string | 是 | 使用上传 KYC 图片中的辅助证明类型,与上传时的 supportingDocumentType 保持一致。按类型提交 PDF 或图片;资料分类不代表所有卡产品均支持受理。 |
fileUrl | string | 是 | 辅助证明上传后返回的稳定 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;辅助证明格式按材料类型确定。
请求示例
{
"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 路径。
- 先使用
email和cardTypeId查询 KYC 补件信息。 - 只有
allowed=true时继续。以原资料为基础准备完整 KYC 参数,锁定字段与原邮箱保持不变。 - 原样携带查询返回的
originalRecordNo、expectedVersion,并为本次提交生成新的requestNo。 - 同时检查外层
code与data.submissionStatus,请求处理成功不等于审核通过。
首次申请、明确失败后的新申请,不传 originalRecordNo 和 expectedVersion;建议传 requestNo,便于安全重试。失败后新申请必须等原费用释放完成,并按当前适用的 KYC 价格重新计费。同一申请补件沿用原费用,不重复收费。
完整补件请求示例
下面以万事达香港美元卡为例,数据均为虚构。用户 ID、文件 URL 及补件依据需替换为实际值。V1 仍使用该产品的既有路由。
POST /openapi/v1/users/kyc
Content-Type: application/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 字段。外层结构沿用公共响应。
正文 code | msg 前缀 | 处理方式 |
|---|---|---|
| 400 | KYC_SUPPLEMENT_INVALID | 补齐补件三项参数;expectedVersion 必须非负,不能脱离 originalRecordNo 单独传入。 |
| 400 | KYC_REQUEST_INVALID | 修正请求号格式。 |
| 400 | KYC_SUPPLEMENT_FIELD_DENIED | 恢复渠道锁定字段,并保持原邮箱不变;修改邮箱的拒绝也可能直接返回说明文字。 |
| 409 | KYC_REQUEST_CONFLICT | 同一请求号使用了不同资料或请求内容;重试保留原请求,确需新提交时使用新号并接受当前资格校验。 |
| 409 | KYC_VERSION_CONFLICT | 原资料记录或补件业务版本已过期,重新查询补件信息。 |
| 409 | KYC_SUPPLEMENT_DENIED | 当前不具备补件资格,按原因处理申请状态或原费用问题。 |
| 409 | KYC_SUPPLEMENT_STATUS_UNKNOWN | 无法确认服务方当前状态,等待平台同步或恢复后再处理。 |
| 409 | KYC_SUPPLEMENT_STATE_CHANGED | 服务方当前状态已不允许补件,处理状态后重新查询补件信息。 |
| 422 | KYC_SUPPLEMENT_DISABLED | 平台已关闭补件,不自动重复提交。 |
补件依据过期的响应示例:
{"code":409,"msg":"KYC_VERSION_CONFLICT: 申请已更新,请刷新补件资格后重试","data":null}受理结果与重试
| 本次结果 | 下一步 |
|---|---|
submissionStatus=ACCEPTED | 资料已受理,查询后续审核状态,不另换请求号重复提交。 |
submissionStatus=REJECTED | 本次明确未受理;平台可能已生成新的资料记录,先重新查询补件信息,修正资料、确认资格后用新请求号提交。 |
超时、网关/服务错误或 submissionStatus=UNKNOWN | 保留原请求与原 requestNo。相同内容使用同一请求号重放:已有保存结果时直接返回,不新增资料或费用,结果仍可能为 UNKNOWN;重放不代表强制再次发送服务方。 |
| 未知结果后确需修改资料 | 变化内容使用新请求号,由后端判断当前申请能否继续;原结果未恢复明确时仍会被拒绝,换号不能绕过保护。 |
| 原记录或版本冲突 | 保留可编辑草稿,重新查询补件信息,恢复锁定字段,确认 allowed=true 后再提交,无需丢弃已填写内容。 |
allowed=false 或平台关闭补件 | 暂停提交,先完成对应条件处理;反复 GET 查询不会强制同步服务方状态。 |
审核依据不变的普通同步不会让 expectedVersion 失效。将它视为后台返回的业务版本,不按同步次数推算。每份新资料使用新的 originalRecordNo,不能只比较版本数字。
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean/null | 提交受理结果:ACCEPTED 为 true,REJECTED 为 false,UNKNOWN 为 null;不代表审核通过。 |
code | string/null | 业务响应码,未取得明确结果时可能为空;与外层响应 code 独立。 |
message | string/null | 业务响应说明,结合 submissionStatus 判断。 |
externalUserId | string/null | 外部用户 ID,服务方尚未返回时可能为空。 |
kycRecordId | string/null | 服务方返回的 KYC 查询标识,可能为空;不是补件使用的平台资料记录号 originalRecordNo。 |
status | string/null | FuturePay 统一 KYC 主状态:NOT_SUBMITTED、PENDING(历史兼容)、PENDING_APPROVAL、APPROVED 或 REJECTED。 |
subStatus | string/null | 外部渠道原始 KYC 子状态,值域可能扩展;当前已知值为 not_submitted、pending_approval、approved、rejected。 |
cardAccountId | string/null | 外部渠道卡账户 ID;渠道未返回时为 null。 |
submissionStatus | string/null | 提交受理结果:ACCEPTED、REJECTED、UNKNOWN;查询时可为空,与审核结果独立。 |
channelStatus | string/null | 当前渠道已确认的认证状态,不被本次未受理的提交覆盖。 |
success 表示请求处理结果,不代表审核通过;submissionStatus 表示提交是否受理,channelStatus 表示当前渠道认证结果。V2 的 status 是用户总体状态,不能据此判断所有渠道均已通过。
可选空值可能返回 null 或省略。submissionStatus=UNKNOWN 时 success 为 null,渠道标识也可能为空,按上文规则处理重试。历史数据可能保留 FAILED,表示平台处理失败,不能单凭此值认定审核拒绝。
