跳转到内容

提交用户 KYC ​

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

请求参数 ​

字段类型必填说明
requestNostring条件补件必填,新申请可选;1–64 位字母、数字、下划线或短横线,租户内 KYC 请求唯一。相同请求重试复用,新提交使用新号。
originalRecordNostring条件补件必填:查询补件信息返回的最新平台资料记录号;首次申请或失败后新申请不传。
expectedVersioninteger(int64)条件补件必填:查询返回的非负补件业务版本,与 originalRecordNo 一起原样提交;新申请不传,审核依据不变的普通同步不使其过期。
cardTypeIdstring是卡产品 ID,用于确定本次 KYC 的资料要求。
emailstring是用户邮箱,必须与 memberId 对应用户的邮箱一致,比较时不区分大小写。
memberIdstring是FuturePay 平台成员 ID,使用创建用户返回的值;必须属于当前租户且与 email 对应同一用户。
firstNamestring条件本次 KYC 的名,与 lastName 成对提供;优先于兼容字段 name。
lastNamestring条件本次 KYC 的姓,与 firstName 成对提供。
namestring条件逐步废弃的完整姓名兼容字段;未提供分离姓名时必填。新接入请使用 firstName、lastName。
birthdaystring是生日,格式为 yyyy-MM-dd。
documentTypestring是证件类型:passport、id_card、driver_license 或 resident_permit;各产品支持范围见下表。
documentNumberstring是证件号码。
documentCountrystring是证件签发国家/地区,两位代码,例如 HK。
documentExpiryDatestring条件证件有效期,格式为 yyyy-MM-dd;与 documentPermanentlyValid 二选一。
documentPermanentlyValidboolean条件永久有效证件传 true,不要传 documentExpiryDate;false 不表示永久有效,此时仍须提供有效期。
frontImageUrlstring是证件正面图片上传后返回的 URL。
backImageUrlstring条件证件背面图片上传后返回的 URL;是否必填取决于卡产品及证件类型,见下表。
selfieImageUrlstring是身份自拍图片上传后返回的 URL。
phoneCountryCodestring是手机号国家区号,例如 +852。
phoneNumberstring是仅数字,4 到 20 位。
genderstring是性别:male 或 female。
annualIncomestring是年收入区间:<20000、20000-50000、50000-200000、200000-500000 或 >500000。
occupationstring是职业。
positionstring是使用对应卡产品接受的职位值,例如 Company Owner,不要用任意职称代替。
nationalitystring是国籍,两位国家/地区代码。
contactAddressstring是详细居住地址,例如街道、楼栋及门牌;继续使用此字段名,不要自行拼入下方结构化地址字段,映射规则见下文。
residentialCitystring条件居住城市,万事达全球美元卡必填。
residentialCountryCodestring条件居住国家或地区二位码,万事达全球美元卡必填;其他产品如传入,也须满足二位码格式。
residentialPostalCodestring条件居住地邮编,万事达全球美元卡必填。
residentialStatestring条件居住州或省,万事达全球美元卡必填。
supportingDocumentsarray条件万事达香港美元卡的非 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 对应的卡产品为准,不需要额外传入产品类别参数。

材料/字段万事达香港美元卡万事达全球美元卡
documentTypepassport、id_card、driver_licensepassport、id_card、resident_permit
backImageUrl护照可不传;身份证、驾照必填所有支持的证件类型均必填
四个 residential* 字段不要求,可不传全部必填
supportingDocuments非 HK 国籍用户必填;HK 国籍用户可不传不要求
中国国籍(nationality: CN)按上述证件及辅助证明要求提交必须使用 resident_permit 作为本次主证件

其他标为“是”的字段仍为所有产品的共同要求。缺少产品必需资料会在创建 KYC 记录、扣费、上传材料和提交审核前被拒绝。

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;辅助证明格式按材料类型确定。

必须先创建用户,再使用返回的 memberId 提交 KYC。memberId 缺失、为空、在当前租户不存在或与 email 不匹配时,请求都会被拒绝;不会回退为按邮箱查找用户。此要求仅适用于 V2 提交 KYC,不改变其他接口的用户标识规则。

请求示例 ​

万事达全球美元卡 ​

json
{
  "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 国籍、护照) ​

此场景不需要证件背面、结构化居住地址或辅助证明文件。

json
{
  "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 路径。

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

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

完整补件请求示例 ​

下面以万事达香港美元卡为例,数据均为虚构。用户 ID、文件 URL、卡产品 ID 及补件依据需替换为实际值;其他产品仍需满足各自资料要求。

http
POST /openapi/v2/users/kyc
Content-Type: application/json
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 规则见公共响应。

正文 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/null用户总体 KYC 状态,值及含义见下表;不能据此判断所有渠道均已通过。
channelStatusstring/null当前卡产品对应渠道最后确认的统一 KYC 状态;未受理或结果未知的提交不覆盖它,值见下表。
subStatusstring/null服务方原始 KYC 子状态,值域可能扩展。
submissionStatusstring/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 公共响应。