下游商户 L2 进阶认证 OpenAPI 接入说明

商户上传文件并直接提交 L2 参数，查询审核与补件，全流程无需托管页面。

下游商户 L2 进阶认证 OpenAPI 接入说明

适用于商户 App / 自有客户端：由商户采集资料，商户服务端调用 OpenAPI 上传文件、提交 JSON、查询审核结果与补件。全流程不要求打开托管页面。

1. 会员与认证等级

先通过 POST /v1/members 建立会员，再完成本人 L1 实名审核；只有主 L1 已通过才可以申请 L2。快捷 KYC 是独立的开卡资料绑定，不会提升会员真实认证等级；L0 绑定快捷 KYC 后仍是 L0，可按卡产品规则开卡，但不能直接申请 L2。

L2 提交成功表示进入审核，不能立即发起要求 L2 的业务。L2 审核通过后再查询会员状态并使用全球速汇接口，汇款仍受商户业务开关、产品及交易校验约束。

2. 调用顺序

步骤	接口	权限
查询申请条件、枚举选项	`GET /v1/kyc/l2/config`	`kyc:read`
逐份上传证明文件	`POST /v1/kyc/files`	`kyc:write`
提交 L2 资料	`POST /v1/kyc/l2/applications`	`kyc:write`
查询最近一份 L2 申请	`GET /v1/kyc/l2/applications`	`kyc:read`
查询会员认证等级	`GET /v1/kyc`	`kyc:read`
查询待补件及字段模板	`GET /v1/kyc/supplements`	`kyc:read`
提交补件参数	`POST /v1/kyc/supplements/{id}`	`kyc:write`

环境域名以交付的接入配置为准。以下接口路径均接在该域名后；不要在 App 中保存商户 API Key 或签名密钥。

所有上述接口带 x-auth-token: Bearer <auth_token> 和 x-on-behalf-of: <external_member_id 或 mem_会员ID>。令牌通过 POST /v1/connect/token 使用 x-client-id、x-api-key 获取。

POST 另带 x-idempotency-key（每次业务提交一把 UUID）、x-timestamp（Unix 秒）、x-nonce（每次请求新 UUID）、x-signature。建议使用 v2 签名：原文为以下六行以换行连接，无尾部换行，使用商户 signing key 做 HMAC-SHA256 后 Base64：


POST
/v1/kyc/l2/applications
<timestamp>
<nonce>
<请求体原始字节的 SHA-256 小写十六进制>
<SHA-256(x-on-behalf-of + 换行 + x-idempotency-key) 小写十六进制>

第六行使用实际发送的两个请求头原文计算。兼容中的 v1 签名只包含前五行；新接入建议使用覆盖会员和幂等键的 v2。

网络重试保留同一幂等键、会员与原始请求体，重新生成时间戳、nonce、签名；修改资料后用新幂等键。查询参数存在时也包含在签名第二行中。

3. 选项与申请条件

GET /v1/kyc/l2/config 返回 enabled、l1_approved、can_apply、options、currencies、files。can_apply 表示查询时是否可提交，提交时会重新校验。

options 包含 employment_status、industry、job_title、account_purpose、turnover_monthly，每项格式为 { "value": "代码", "label": "显示文案" }。提交 value，不要提交 label，也不要写死选项总数。通过 Accept-Language 获取对应语言文案。

currencies 是当前允许的币种数组；files 返回 max_bytes 和 formats。

4. 上传文件

调用 POST /v1/kyc/files，请求体为单份文件的原始二进制，Content-Type: application/octet-stream。不是 multipart、Base64 或外部图片链接；签名计算原始文件字节。

支持 JPEG、PNG、WebP、PDF，单文件最大 8 MiB（8,388,608 字节），以内容检测结果为准。返回 HTTP 201：


{ "file_url": "https://<接入域名>/kyc/file/<会员ID>/<文件ID>.pdf" }

按原样保存 file_url 并用于 L2 或补件提交。文件必须是为当前会员上传、且仍存在的文件；不能使用其他会员文件、外部 URL 或自己拼接的不存在地址。

5. L2 JSON 参数

POST /v1/kyc/l2/applications，Content-Type: application/json，请求体最大 128 KiB。

以下示例中行业和职位需替换成配置接口返回的真实 value；文件地址需替换成上传返回值，授权时间与设备信息需取自实际授权行为。


{
  "profile": {
    "nickname": "Alex",
    "postal_code": "018956",
    "tax_number": "",
    "employment_status": "Employed",
    "industry": "<options.industry 中所选 value>",
    "job_title": "<options.job_title 中所选 value>",
    "company_name": "Example Ltd",
    "annual_income": "60000.00",
    "account_purpose": ["PURCHASE"],
    "other_purpose": "",
    "banking_countries": ["SG"],
    "banking_currencies": ["USD", "SGD"],
    "internationally": 1,
    "turnover_monthly": "TM001",
    "turnover_monthly_currency": "USD",
    "proof_of_address": "<地址证明 file_url>",
    "source_of_funds": "<资金来源证明 file_url>"
  },
  "tos_acceptance": {
    "accepted": true,
    "ip": "203.0.113.10",
    "user_agent": "<会员实际设备 User-Agent>",
    "accepted_at": "2026-09-24T12:00:00.000Z"
  }
}

profile 字段	必填	规则
nickname	是	字符串，1–50 字符
postal_code	是	字符串，1–20 字符
tax_number	否	字符串，最多 100 字符
employment_status	是	配置接口对应 value
industry	是	配置接口对应 value
job_title	是	配置接口对应 value
company_name	是	1–100 字符，英文、数字、空格及允许符号；无业、学生、退休同样必填，请填写真实且符合规则的资料
annual_income	是	美元年收入，正数字符串，整数部分最多 12 位、小数最多 2 位；不能传 JSON 数字
account_purpose	是	非空字符串数组，值取自配置
other_purpose	条件	含 OTHERS 时必填，最多 500 字符
banking_countries	是	非空数组，每项为两位大写国家/地区代码
banking_currencies	是	非空数组，每项取自 currencies
internationally	否	数字 0 或 1，默认 0；不接受布尔值或字符串
turnover_monthly	是	配置接口中的月流水档位 value
turnover_monthly_currency	是	取自 currencies
proof_of_address	是	当前会员地址证明 file_url
source_of_funds	是	当前会员资金来源证明 file_url
income_proof	否	当前会员收入证明 file_url，可省略或空字符串
other_proof	否	当前会员其他证明 file_url，可省略或空字符串

公司名称允许符号：. , & ( ) - + % # @ * ! $ ^ _ ? ~ 及反斜杠。

tos_acceptance 必填：会员真实确认后传 accepted: true；ip 当前仅支持会员 IPv4；user_agent 为非空字符串、最多 1000 字符；accepted_at 为实际确认时间，UTC ISO 8601 格式（以 Z 结尾，最多三位毫秒），最多允许领先服务端时间 5 分钟。不能以商户服务器 IP、虚构设备或虚构同意记录代替会员信息。

成功返回 HTTP 201：


{ "id": "kl2_123", "status": "pending" }

同一会员已有审核中、待补件、补件复审或已通过的申请时，不能新建另一份；被驳回后可使用新幂等键重新申请。

6. 查询审核与补件

GET /v1/kyc/l2/applications 返回最新申请；从未申请时 application 为 null。


{
  "application": {
    "id": "kl2_123",
    "status": "pending",
    "reject_reason": "",
    "created_at": "2026-09-24T12:01:00.000Z",
    "updated_at": "2026-09-24T12:01:00.000Z"
  }
}

status	处理方式
pending	等待审核
supplement_required	查询待补件、按模板提交
supplement_submitted	等待补件复审
rejected	根据 reject_reason 修正后重新申请
approved	再查 GET /v1/kyc 确认 level=2

GET /v1/kyc 是等级总览，其 l2_status 的 pending 合并了审核和补件流程；none 也可能表示既往申请全部被驳回，详细状态看上述申请接口。收到 kyc.result.updated 事件后回查，不要把事件通知直接当作审核通过。

待补件使用 GET /v1/kyc/supplements，示例条目：


{
  "id": "ksup_456",
  "level": "L2",
  "message": "请补充证明材料",
  "fields": [
    { "index": 0, "label": "资金来源说明", "type": "text", "required": true },
    { "index": 1, "label": "补充证明", "type": "photo", "required": true }
  ],
  "created_at": "2026-09-24T12:05:00.000Z",
  "expires_in_days": 14
}

实际响应为 {data: [条目], next_cursor: null, has_more: false}，并保留兼容字段 hosted_url，纯 API 客户端可忽略它。列表包含 L1 和 L2，通过 level 区分。有效期是创建时间加 14 天，expires_in_days 为固定政策，不是剩余天数。

先上传补充证明，再调用 POST /v1/kyc/supplements/{id}（本例 id 为 ksup_456）：


{
  "answers": [
    { "index": 0, "value": "工资收入及储蓄，详见附件" },
    { "index": 1, "value": "<补充证明 file_url>" }
  ]
}

按服务端模板 index 提交，不要用翻译后的 label 作字段标识。text 最多 500 字符，photo 使用当前会员上传文件 URL；required=true 必须填写，选填项可省略。index 不得重复或超出模板范围。

成功 HTTP 200：{"id":"ksup_456","level":"L2","status":"submitted"}。工单和审核状态原子更新，进入补件复审。相同幂等键原样重试返回原结果；新幂等键重复提交已完成工单返回 state_invalid。

7. 错误处理

code	处理
kyc_required	先完成本人主 L1 审核；快捷 KYC 不满足此条件
invalid_fields	读取 fields 中 key/reason，修正对应参数后新幂等键提交
state_invalid	重新查询配置、申请或补件状态；可能已提交、已通过、补件失效或业务关闭
member_not_found / not_found	检查会员上下文、商户归属、补件 ID
insufficient_scope	为服务端凭据配置所需权限
invalid_request	检查 JSON 结构或 128 KiB 请求大小限制
kyc_upload_invalid / kyc_upload_too_large	检查实际文件格式和 8 MiB 上限
idempotency_key_reused	同一幂等键不得更换会员或请求体
idempotency_in_progress	首次提交仍在处理中，稍后按相同幂等键重试

8. 旧接入兼容

POST /v1/kyc/l2/sessions 继续提供可选托管认证。新接入的商户 App 可以直接使用本文件的参数提交流程，不需要先创建 session，也不需要使用 WebView。JSON 接口新增上线后方可调用，请以目标环境发布通知和接口可用性为准。