跳转到内容

上传 KYC 图片 ​

POST /openapi/v2/users/uploadKycImage
项内容
请求方法POST
请求路径/openapi/v2/users/uploadKycImage
请求类型multipart/form-data

请求参数 ​

字段类型必填说明
filefile是每次上传一个文件,最大 6MB;允许格式由用途和辅助证明类型决定,见下表。
purposestring否文件用途:DOCUMENT_FRONT、DOCUMENT_BACK、SELFIE 或 SUPPORTING_DOCUMENT。不传时按主证件图片规则校验。
supportingDocumentTypestring条件辅助证明材料类型,不是主证件类型。purpose=SUPPORTING_DOCUMENT 时必填,取值见下表;其他用途不传。

签名时 RAW_BODY 使用空字符串,规则见鉴权与签名。

文件用途 purpose ​

值用途允许格式supportingDocumentType
不传沿用主证件图片校验规则JPG、JPEG、PNG不传
DOCUMENT_FRONT主证件正面JPG、JPEG、PNG不传
DOCUMENT_BACK主证件背面JPG、JPEG、PNG不传
SELFIE自拍照片JPG、JPEG、PNG不传
SUPPORTING_DOCUMENT辅助证明材料按下表确定必填

辅助证明类型 supportingDocumentType ​

按实际材料选择,没有默认值;枚举值区分大小写,须使用表中的大写值。

材料值允许格式
有效香港工作签证WORK_VISA仅 PDF
雇佣合同EMPLOYMENT_CONTRACT仅 PDF
工资单SALARY_PAYSLIP仅 PDF
租赁协议TENANCY_AGREEMENT仅 PDF
住址证明ADDRESS_PROOF仅 PDF
银行对账单BANK_STATEMENT仅 PDF
访港证明PROOF_OF_VISIT仅 PDF
香港入境许可IMMIGRATION_ENDORSEMENTJPG、JPEG、PNG、PDF
通行证正面TRAVEL_PERMIT_FRONTJPG、JPEG、PNG、PDF
通行证背面TRAVEL_PERMIT_BACKJPG、JPEG、PNG、PDF

UTILITY_BILL 不在当前上传接口支持范围内。文件扩展名、声明的 MIME 类型与实际内容须一致;未声明 MIME 或声明为 application/octet-stream 时,仍会检查扩展名与文件内容。仅修改扩展名不能将图片转换为 PDF。

请求示例 ​

以下展示 multipart/form-data 表单字段;file 须选择实际文件,不是发送文件路径字符串。请求仍须携带鉴权 Header。

上传主证件正面,不传 supportingDocumentType:

text
file:    front.jpg(文件,image/jpeg)
purpose: DOCUMENT_FRONT

上传银行对账单 PDF:

text
file:                   statement.pdf(文件,application/pdf)
purpose:                SUPPORTING_DOCUMENT
supportingDocumentType: BANK_STATEMENT

上传后,在提交用户 KYC中使用返回的 url,不要使用 previewUrl。辅助证明的 documentType 应与上传时的 supportingDocumentType 保持一致,例如以下 KYC 请求片段:

json
{
  "supportingDocuments": [
    {
      "documentType": "BANK_STATEMENT",
      "fileUrl": "上传接口返回的 url"
    }
  ]
}

通行证正反面分别上传,正式提交 KYC 时须在 supportingDocuments 中成对提供 TRAVEL_PERMIT_FRONT 和 TRAVEL_PERMIT_BACK。上传成功仅代表文件通过上传校验,不代表 KYC 审核通过。

响应 data ​

字段类型说明
successboolean是否处理成功。
codestring平台响应码。
messagestring平台响应说明。
urlstring稳定文件地址,用于保存和提交 KYC。私有文件不能通过此地址匿名预览。
previewUrlstring预览地址;私有桶返回有效期 120 秒的临时 GET 签名地址。仅用于预览,不用于提交 KYC。
previewExpiresAtstring / null预览签名的 UTC 过期时间,ISO 8601 格式,例如 2026-10-12T02:02:00Z;未生成签名时为空。
contentTypestring文件 MIME 类型。
sizeinteger文件大小,单位字节。
originalNamestring原始文件名。

previewUrl 和过期时间来自同一次签名。公开存储配置的预览地址与 url 相同,previewExpiresAt 为空。签名过期后无法继续发起读取;本接口不提供签名刷新功能。

参数校验错误见 V2 公共响应。