账户中心 › 指南
换一条链接给终端用户，他在我方的屏上填十四个字段、传三张照片。
L1 实名：托管屏与资料清单
你要做的只有一步
POST /v1/kyc/sessions
x-on-behalf-of: <external_member_id>
拿回：
{ "hosted_url": "https://…/hosted/kyc/kyc_9f2c…", "expires_at": 1786000000 }
把这条链接交给终端用户（App 内嵌 WebView、短信、邮件都行）。剩下的事在我方的页面上发生。
这张票绑三样
| 绑什么 | 少了会怎样 |
|---|---|
| 会员 | 你能拿 A 的链接给 B 建档 |
| 商户 | 一张票被另一个商户拿去消费 |
| 24 小时 + 一次性 | 链接躺在聊天记录里被转发重用 |
⚠ 有效期是 24 小时，不是 5 分钟。它要经你转交给终端用户、
他再去翻证件、拍照片。但别指望它更久 —— 拿到这条 URL 的人
就能以那个会员的名义提交一份实名档案。过期了补发一次即可。
终端用户在那一屏上填什么
十四个文本 / 选择字段（全部必填）
| 字段 | 类型 | 备注 |
|---|---|---|
first_name / last_name | 文本 ≤60 | |
sex | 选择 | male | female |
birth_date | 日期 | |
nationality | 文本 2 位 | 国家码 |
occupation | 文本 ≤60 | |
phone_zone_number | 文本 ≤6 | 区号 |
phone | 电话 ≤20 | |
identity_type | 选择 | id_card | passport | resident_card | drivers_license |
identity_number | 文本 ≤60 | 我方不校验号码格式 —— 各国规则不一，误拦的代价大于放过 |
cardholder_residence | 选择 | chinese-mainland | chinese-mainland-residents-living-overseas | overseas-countries |
address_province / address_city | 文本 ≤60 | |
address | 文本 ≤160 | |
street_number | 文本 ≤40 |
邮箱是预填的、不可改 —— 审核结果会发到会员建档时那个邮箱。
三张照片
| 项 | 内容 |
|---|---|
front | 证件正面 |
back | 证件背面 |
handheld | 手持证件的自拍 |
单张 ≤ 8 MB。我方按魔数嗅探真实类型，不信客户端声明的Content-Type。影像直传我方私有存储，只有本人与审核员读得回来。
⚠ 按居住地类型，审核时可能追加要求居留许可文件 ——
那走补件，不在首次表单里。
状态机
┌──────────────► APPROVED
UNREVIEWED ───┼──────────────► REJECTED ──► （会员可改后重提 → UNREVIEWED）
└─► SUPPLEMENT_REQUIRED ──► SUPPLEMENT_SUBMITTED ──► ┘
| 状态 | 意思 | 你该做什么 |
|---|---|---|
UNREVIEWED | 已提交，待审 | 等事件 |
APPROVED | 通过 | 放行 |
REJECTED | 驳回 | 把 fail_reason 给用户看，他可以改后重提 |
SUPPLEMENT_REQUIRED | 待补件 | 见补件 |
SUPPLEMENT_SUBMITTED | 补件已交，待审 | 等事件 |
每一次流转都会发kyc.result.updated。
⚠
REJECTED不是终局。 会员改完资料可以重新提交，状态回到
UNREVIEWED。界面上写「认证失败」而不给重试入口，是这条线上最常见的一种把用户堵死的做法。