提交用户 KYC

POST /openapi/v1/users/kyc

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

请求参数

字段	类型	必填	说明
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，仅用于平台定位用户，不会发送给 CPlus。

supportingDocuments 项

字段	类型	必填	说明
documentType	string	是	UTILITY_BILL、TENANCY_AGREEMENT、ADDRESS_PROOF、BANK_STATEMENT、TRAVEL_PERMIT_FRONT、TRAVEL_PERMIT_BACK 或 PROOF_OF_VISIT。
fileUrl	string	是	辅助证明文件上传后返回的 URL。

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

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

两者同时传、两者都不传，或传 documentPermanentlyValid: false，都会被拒绝。

图片必须先通过现有 KYC 图片上传接口取得 URL，再提交 KYC。

请求示例

{
  "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"
}

响应 data

字段	类型	说明
success	boolean	是否处理成功。
code	string	平台响应码。
message	string	平台响应说明。
externalUserId	string	外部用户 ID。
kycRecordId	string	KYC 记录 ID。
status	string/null	FuturePay 统一 KYC 主状态：PENDING、PENDING_APPROVAL、APPROVED 或 REJECTED。
subStatus	string/null	外部渠道原始 KYC 子状态，值域可能扩展；当前已知值为 not_submitted、pending_approval、approved、rejected。
cardAccountId	string/null	外部渠道卡账户 ID；渠道未返回时为 null。