提交用户 KYC
POST/openapi/v2/users/kyc| 项 | 内容 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /openapi/v2/users/kyc |
| 请求类型 | application/json |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
requestNo | string | 条件 | 补件必填,新申请可选;1–64 位字母、数字、下划线或短横线,租户内 KYC 请求唯一。相同请求重试复用,新提交使用新号。 |
originalRecordNo | string | 条件 | 补件必填:查询补件信息返回的最新平台资料记录号;首次申请或失败后新申请不传。 |
expectedVersion | integer(int64) | 条件 | 补件必填:查询返回的非负补件业务版本,与 originalRecordNo 一起原样提交;新申请不传,审核依据不变的普通同步不使其过期。 |
cardTypeId | string | 是 | 卡产品 ID,用于确定本次 KYC 的资料要求。 |
email | string | 是 | 用户邮箱,必须与 memberId 对应用户的邮箱一致,比较时不区分大小写。 |
memberId | string | 是 | FuturePay 平台成员 ID,使用创建用户返回的值;必须属于当前租户且与 email 对应同一用户。 |
firstName | string | 条件 | 本次 KYC 的名,与 lastName 成对提供;优先于兼容字段 name。 |
lastName | string | 条件 | 本次 KYC 的姓,与 firstName 成对提供。 |
name | string | 条件 | 逐步废弃的完整姓名兼容字段;未提供分离姓名时必填。新接入请使用 firstName、lastName。 |
birthday | string | 是 | 生日,格式为 yyyy-MM-dd。 |
documentType | string | 是 | 证件类型:passport、id_card、driver_license 或 resident_permit;各产品支持范围见下表。 |
documentNumber | string | 是 | 证件号码。 |
documentCountry | string | 是 | 证件签发国家/地区,两位代码,例如 HK。 |
documentExpiryDate | string | 条件 | 证件有效期,格式为 yyyy-MM-dd;与 documentPermanentlyValid 二选一。 |
documentPermanentlyValid | boolean | 条件 | 永久有效证件传 true,不要传 documentExpiryDate;false 不表示永久有效,此时仍须提供有效期。 |
frontImageUrl | string | 是 | 证件正面图片上传后返回的 URL。 |
backImageUrl | string | 条件 | 证件背面图片上传后返回的 URL;是否必填取决于卡产品及证件类型,见下表。 |
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 | 是 | 使用对应卡产品接受的职位值,例如 Company Owner,不要用任意职称代替。 |
nationality | string | 是 | 国籍,两位国家/地区代码。 |
contactAddress | string | 是 | 详细居住地址,例如街道、楼栋及门牌;继续使用此字段名,不要自行拼入下方结构化地址字段,映射规则见下文。 |
residentialCity | string | 条件 | 居住城市,万事达全球美元卡必填。 |
residentialCountryCode | string | 条件 | 居住国家或地区二位码,万事达全球美元卡必填;其他产品如传入,也须满足二位码格式。 |
residentialPostalCode | string | 条件 | 居住地邮编,万事达全球美元卡必填。 |
residentialState | string | 条件 | 居住州或省,万事达全球美元卡必填。 |
supportingDocuments | array | 条件 | 万事达香港美元卡的非 HK 国籍用户必填,至少 1 项;其他情况不要求。提供时最多 10 项,格式见下表。 |
姓名与居住地址
firstName、lastName 必须成对且非空。平台去除首尾空白后优先使用这组姓名:万事达全球美元卡分别接收名和姓;万事达香港美元卡接收 firstName + " " + lastName。仅提供一个非空的新姓名字段时,即使同时提供 name 也会被拒绝。
旧请求仅提供 name 仍可使用。万事达全球美元卡缺少分离姓名时,继续从用户注册资料补充,不会猜测拆分 name。
contactAddress 表示详细地址。万事达全球美元卡分别接收它和四个 residential* 字段;万事达香港美元卡由平台依次合并非空的 residentialCountryCode、residentialState、residentialCity、contactAddress、residentialPostalCode,以 , 分隔。四个结构化字段均未提供时,原样使用 contactAddress。例如 HK、Hong Kong、Kowloon、12 Test Road, Unit 3、999077 合并为 HK, Hong Kong, Kowloon, 12 Test Road, Unit 3, 999077。
平台保留原地址分项供补件回显;补件时继续提交详细地址和各分项,不要把合并后的完整地址填回 contactAddress。
按卡产品区分资料要求
以 cardTypeId 对应的卡产品为准,不需要额外传入产品类别参数。
| 材料/字段 | 万事达香港美元卡 | 万事达全球美元卡 |
|---|---|---|
documentType | passport、id_card、driver_license | passport、id_card、resident_permit |
backImageUrl | 护照可不传;身份证、驾照必填 | 所有支持的证件类型均必填 |
四个 residential* 字段 | 不要求,可不传 | 全部必填 |
supportingDocuments | 非 HK 国籍用户必填;HK 国籍用户可不传 | 不要求 |
中国国籍(nationality: CN) | 按上述证件及辅助证明要求提交 | 必须使用 resident_permit 作为本次主证件 |
其他标为“是”的字段仍为所有产品的共同要求。缺少产品必需资料会在创建 KYC 记录、扣费、上传材料和提交审核前被拒绝。
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;辅助证明格式按材料类型确定。
必须先创建用户,再使用返回的 memberId 提交 KYC。memberId 缺失、为空、在当前租户不存在或与 email 不匹配时,请求都会被拒绝;不会回退为按邮箱查找用户。此要求仅适用于 V2 提交 KYC,不改变其他接口的用户标识规则。
请求示例
万事达全球美元卡
{
"cardTypeId": "VIRTUAL_USD",
"email": "user@example.com",
"memberId": "MEMBER_001",
"firstName": "Test",
"lastName": "User",
"birthday": "1990-01-01",
"documentType": "passport",
"documentNumber": "P1234567",
"documentCountry": "HK",
"documentExpiryDate": "2030-12-31",
"frontImageUrl": "https://example.com/front.jpg",
"backImageUrl": "https://example.com/back.jpg",
"selfieImageUrl": "https://example.com/selfie.jpg",
"phoneCountryCode": "+852",
"phoneNumber": "91234567",
"gender": "male",
"annualIncome": "50000-200000",
"occupation": "Engineer",
"position": "Company Owner",
"nationality": "HK",
"contactAddress": "12 Test Road, Unit 3",
"residentialCity": "Hong Kong",
"residentialCountryCode": "HK",
"residentialPostalCode": "999077",
"residentialState": "Hong Kong"
}万事达香港美元卡(HK 国籍、护照)
此场景不需要证件背面、结构化居住地址或辅助证明文件。
{
"cardTypeId": "HK_USD",
"email": "user@example.com",
"memberId": "MEMBER_001",
"firstName": "Test",
"lastName": "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": "Company Owner",
"nationality": "HK",
"contactAddress": "Hong Kong"
}两个示例中的 cardTypeId 均为占位值,需替换为对应产品的实际 ID;MEMBER_001 需替换为实际创建用户返回的 memberId。
补件提交
补件继续调用本页 POST 接口,没有单独的补件 POST 路径。
- 先使用
email和cardTypeId查询 KYC 补件信息。 - 只有
allowed=true时继续。以原资料为基础准备完整 KYC 参数,锁定字段与原邮箱保持不变。 - 原样携带查询返回的
originalRecordNo、expectedVersion,并为本次提交生成新的requestNo。 - 同时检查外层
code与data.submissionStatus,请求处理成功不等于审核通过。
首次申请、明确失败后的新申请,不传 originalRecordNo 和 expectedVersion;建议传 requestNo,便于安全重试。失败后新申请必须等原费用释放完成,并按当前适用的 KYC 价格重新计费。同一申请补件沿用原费用,不重复收费。
完整补件请求示例
下面以万事达香港美元卡为例,数据均为虚构。用户 ID、文件 URL、卡产品 ID 及补件依据需替换为实际值;其他产品仍需满足各自资料要求。
POST /openapi/v2/users/kyc
Content-Type: application/json{
"cardTypeId": "HK_USD",
"email": "user@example.com",
"memberId": "member-123",
"requestNo": "KYC_SUPPLEMENT_20261104_001",
"originalRecordNo": "KYC_RECORD_002",
"expectedVersion": 3,
"firstName": "Test",
"lastName": "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 字段。V2 参数绑定和 Bean Validation 的 HTTP 400 规则见公共响应。
正文 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 | 用户总体 KYC 状态,值及含义见下表;不能据此判断所有渠道均已通过。 |
channelStatus | string/null | 当前卡产品对应渠道最后确认的统一 KYC 状态;未受理或结果未知的提交不覆盖它,值见下表。 |
subStatus | string/null | 服务方原始 KYC 子状态,值域可能扩展。 |
submissionStatus | string/null | 提交受理结果:ACCEPTED、REJECTED、UNKNOWN;查询时可为空,与审核结果独立。 |
success 表示请求处理结果,不代表审核通过;submissionStatus 表示提交是否受理,channelStatus 表示当前渠道认证结果。V2 的 status 是用户总体状态,不能据此判断所有渠道均已通过。
统一 KYC 状态值
| 值 | 含义 |
|---|---|
NOT_SUBMITTED | 未提交 |
PENDING | 历史待处理兼容值 |
PENDING_APPROVAL | 审核中 |
APPROVED | 审核通过 |
REJECTED | 审核拒绝 |
MODIFY | 需要补充或修改资料 |
CERT_REQUIRED | 尚需完成认证 |
FAILED | 平台处理失败或历史失败值,不能单凭此值认定审核拒绝 |
可选空值可能返回 null 或省略。submissionStatus=UNKNOWN 时 success 为 null,渠道标识也可能为空;保留原请求并按上文规则重试,不能把外层 code=200 当作审核通过。
参数校验错误见 V2 公共响应。
