L2 进阶认证

与 L1 同型的一张托管屏。19 个字段、两份必传证明 —— 而那几百项选项表由我方页面渲染，你拿不到也不需要。

汇款要 level 2。L1 通过之后，会员还要再交一份付款人资料 ——这一页是它的完整契约。

怎么用

与 L1 完全同型：你换一条链接，终端用户在我方的页面上填。


POST /v1/kyc/l2/sessions
x-on-behalf-of:    <external_member_id 或 mem_…>
x-idempotency-key: <UUID>

→ 201 { "hosted_url": "https://…/hosted/kyc/l2/kyc_…", "expires_at": "…" }

资料与证明文件一个字节都不经过你 —— 与 L1 同一条设计前提。

⚠ 顺带一个实际好处：下面那两组几百项的选项表（industry 229 项、

job_title 44 项）由我方的页面渲染，你不需要拿到它们，

上游改了你也不用跟。

三道前置在签票这一步就判

不满足	返回
L2 总开关关着	`400 state_invalid`
该会员的主 L1 还没通过	`400 state_invalid`
名下已有一份未被驳回的 L2	`400 state_invalid`

不会给你一条点进去注定失败的链接。

⚠ 对外只有一个 state_invalid，不告诉你是哪一种。

要判断该不该发，先看 GET /v1/kyc：

level ≥ 1 且 l2_status 是 none 才是「可以发」。

⚠ 前置在用户打开链接那一刻还会再判一次 —— 签票与打开之间可能隔十几个

小时，那份 L1 完全可能被回退。那时页面上给的是「请先完成实名认证」，

不是「链接已失效」（说成失效会让他去找你要新链接，而新的一样打不开）。

票据纪律与 L1 一致

24 小时、一次性、绑会员 + 绑商户。校验失败不消耗票据 ——用户可以在同一条链接上反复重填；提交成功那一刻才消费。

⚠ L1 与 L2 的票据不能互换。 一张 L2 的票在 L1 那张屏上打不开，反之亦然。

怎么跟进结果

GET /v1/kyc 的 l2_status：

值	意思
`none`	没提交过，或全部被驳回 —— 可以（再）发一条链接
`pending`	有一份在审
`approved`	已通过（此时 `level` 也已经是 2）

⚠ kyc.result.updated 事件不带 level 也不带结论，只说「变了」。

收到之后回查 GET /v1/kyc，看 level 与 l2_status。

下面这一节是完整资料清单，用于你评估：让用户准备什么、这一步有多重。

前置条件（三道，顺序固定）

L2 总开关开着（我方后台配置）—— 否则 kyc_l2_closed
这个会员的主 L1 已经 APPROVED —— 否则 kyc_l2_requires_l1
名下没有未驳回的 L2 申请 —— 否则 kyc_l2_limit_reached

⚠ 第 3 条的判据是「不等于 REJECTED」。也就是说：

审核中不能再提一份；全部被驳回之后才能重建一份。

19 个字段

基本信息

字段	必填	规则
`nickname`	是	≤ 50。⚠ 它不会发给上游，别当成合规档案上的名字
`postal_code`	是	≤ 20。⚠ 上游子账户真正用的就是它，填错事后改不了
`tax_number`	否	不校验，空着也能过。⚠ 超过 100 字符会在送上游那一步被静默丢弃

职业与公司

字段	必填	规则
`employment_status`	是	7 选 1，见下
`industry`	是	229 选 1
`job_title`	是	44 选 1
`company_name`	是	≤ 100，字符集受限，见下。无业/学生/退休也必填
`annual_income`	是	`^\d{1,12}(\.\d{1,2})?$` 且 > 0。单位 USD

⚠⚠ **employment_status 选 Unemployed / Student / Retired /

Homemaker 时，company_name 照样必填** —— 校验里没有任何按就业状态

豁免的分支。不在界面上说清楚，无业与学生用户会卡在这一格且看不出为什么。

⚠ company_name 只收这些字符：a-z A-Z 0-9、空格，以及

` . , & ( ) - + % # @ * ! $ ^ _ ? ~ \ `。

中文公司名过不了 —— 让用户填英文注册名或音译。

这一条要在界面上提前说，否则他会在提交时才发现。

（这个字符集是上游的要求，我方原文照抄，并每周与上游文档对账一次。）

⚠ annual_income 是字符串定点、单位美元、必须为正。

传 0、传负数、传三位小数都会被拒。

账户用途与银行往来

字段	必填	规则
`account_purpose`	是	字符串数组，至少 1 项，8 选 N
`other_purpose`	条件必填	`account_purpose` 含 `OTHERS` 时必填
`banking_countries`	是	字符串数组，至少 1 项，每项 `^[A-Z]{2}$`（大写两位国家码）
`banking_currencies`	是	字符串数组，至少 1 项，取值见下面币种表
`internationally`	—	有无跨境往来
`turnover_monthly`	是	`TM001`–`TM005`
`turnover_monthly_currency`	是	币种表里的一个

⚠ internationally 认不出的值一律当 0。 只有数字 1 与字符串 "1"

会被当成「是」；传 true、"yes"、"Y" 都会被静默记成「否」，

不报错。这是这一组里唯一一个不会拒你、只会记错的字段。

⚠ 三个数组字段必须是真数组且每一项都是非空字符串。

传 "US,GB" 这种逗号串会被判成整个字段非法。

证明文件（四项，两必传）

字段	必填
`proof_of_address`	是 —— 地址证明
`source_of_funds`	是 —— 资金来源证明
`income_proof`	否 —— 收入证明
`other_proof`	否 —— 其他补充材料

⚠ source_of_funds 必传是上游的硬要求（个人汇款要开子账户），

不是我方加的一道。

这四个字段收的是 URL，不是文件本身。 流程是：先把文件传上去拿到一个URL，再把 URL 放进提交体。

⚠ URL 必须是这个会员自己的：我方按

<base>/kyc/file/<会员id>/ 做整串前缀匹配（不是包含匹配）。

拿别人的 URL 填进来会被判成该字段非法。

选项表

组	项数	取值形态
`employment_status`	7	`Employed` `Self-Employed` `Unemployed` `Student` `Retired` `Homemaker` `Other`
`industry`	229	英文行业名原文，如 `Banking/Financial/Insurance`
`job_title`	44	英文职位名原文，如 `Assemblers`
`account_purpose`	8	`PURCHASE` `BILL_PAYMENT` `EDUCATIONAL_EXPENSES` `PERSONAL_REMITTANCE` `CHARITABLE_DONATION` `LOAN_REPAYMENT` `INVESTMENT` `OTHERS`
`turnover_monthly`	5	`TM001`–`TM005`

turnover_monthly 的档位：

值	月流水
`TM001`	< 50,000
`TM002`	50,000 – 100,000
`TM003`	100,000 – 250,000
`TM004`	250,000 – 500,000
`TM005`	> 500,000

币种（banking_currencies 与 turnover_monthly_currency 共用这一张表）：USD EUR GBP JPY HKD SGD AUD CAD CNY

⚠ 提交的必须是「值」，显示给用户的应该是「译文」。

这五组的值是上游枚举的原文，原样透传。

我方按语言下发译文（6 种语言），但值只有一份。

⚠ industry 与 job_title 不要硬编码。 229 项与 44 项都会随上游变，

我方每周与上游文档对账一次 —— 抄一份进你的代码，上游改了你不会知道。

（而如前所述，开放 API 上目前也没有取它们的端点 —— 这正是这条线

还不能接的一部分。）

状态机

L2 与 L1 是两条独立的审核线，各有各的 review_status：


UNREVIEWED ──┬──► APPROVED   （kyc_level 到 2）
             └──► REJECTED   （可以重建一份新的）

⚠ REJECTED 之后不是「改一改再提交」，是重新建一份。

判据是「名下有没有未驳回的申请」—— 全部驳回之后才放行下一次提交。

⚠ L2 通过而 L1 没通过（数据异常）时，kyc_level 算 0 —— 不是 1，也不是 2。

判据是「L1 没过就直接 0」。

L2 的申请行通过 l1_kyc_id 引用那份已通过的 L1 —— 实名信息与证件影像不重复上传，服务端自取。这也是为什么 L1 的档案在有未驳回的 L2 引用它时删不掉。