换一条 L2 进阶认证的托管屏链接

POST /v1/kyc/l2/sessions scope: kyc:write

代会员调用 · 必带 x-on-behalf-of 需 x-idempotency-key

与 POST /v1/kyc/sessions 同型，换的是 L2 进阶认证那一屏。

汇款要 level 2。L1 通过之后，会员还要再交一份付款人资料（19 个字段 + 两份必传证明文件）。这条端点给你一条链接，终端用户在我方的页面上填完并上传 —— 资料与证明文件一个字节都不经过你。

前置条件

L2 总开关已开启
该会员的主 L1 档案已 APPROVED
该会员名下没有未被驳回的 L2 申请

字段	类型	必填	说明
`x-on-behalf-of`	string	必填	代哪个会员发起。`external_member_id` 或 `mem_<uuid>` 都认。 ⚠ 它参与幂等指纹：同一把键换一个会员回 `409`。
`x-idempotency-key`	string	必填	UUID v4。逐会员一把。

请求体

无字段。会员完全由 x-on-behalf-of 决定。

响应

201已签发。把 hosted_url 转给终端用户即可。 响应里没有会话 id，这是刻意的 —— 那段字符串就是凭据本身。

{
  "hosted_url": "https://api.zise.com/hosted/kyc/l2/kyc_3c81f0d29a4417d18e0b2f6a1c9d4e77",
  "expires_at": "2026-08-14T05:00:00.000Z"
}

400member_context_required 没带 x-on-behalf-of · state_invalid 三道前置有一道不满足（不下发是哪一道 —— 用 GET /v1/kyc 的 level 与 l2_status 判断）

403insufficient_scope 缺 kyc:write

404member_not_found（含「属于别的商户」与「已停用」）

409idempotency_key_reused 同一把键换了会员或换了请求体 · idempotency_in_progress 首次请求还在处理中

深入说明

为什么不是一个 JSON 提交口

L2 要传地址证明与资金来源证明，与证件影像同级。走你的服务器意味着它们会经过你的日志、你的 CDN、你的错误上报 ——而你并不需要承担那份合规义务。

顺带一个实际好处：industry（229 项）与 job_title（44 项）这两张选项表由我方的页面渲染，你不需要拿到它们，上游改了你也不用跟。

三道前置在这里就判

总开关关着 / 该会员的主 L1 还没通过 / 名下已有一份未被驳回的 L2 ——这三种情况当场回 400 state_invalid，不会给你一条点进去注定失败的链接。

⚠ 对外只有一个 state_invalid，不告诉你是哪一种。要判断该不该发，先看 GET /v1/kyc：level ≥ 1 且 l2_status 是 none 才是「可以发」。

⚠ 前置在用户打开链接那一刻还会再判一次 —— 签票与打开之间可能隔十几个小时，那份 L1 完全可能被回退。那时页面上给的是「请先完成实名认证」，不是「链接已失效」。

有效期 24 小时，一次性

与 L1 那条同一套纪律：过期就再要一条（换一把新幂等键）；校验失败不消耗票据，用户可以在同一条链接上反复重填；提交成功那一刻才消费。

请求

curl -X POST 'https://api.zise.com/v1/kyc/l2/sessions' \
  -H 'x-auth-token: Bearer $TOKEN' \
  -H 'x-on-behalf-of: $MEMBER_ID' \
  -H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
  -H 'content-type: application/json' \
  -d '{}'

const res = await fetch("https://api.zise.com/v1/kyc/l2/sessions", {
  method: "POST",
  headers: {
    "x-auth-token": "Bearer $TOKEN",
    "x-on-behalf-of": "$MEMBER_ID",
    "x-idempotency-key": "$IDEMPOTENCY_KEY",
    "content-type": "application/json",
  },
  body: JSON.stringify({}),
});
// 金额按字符串读，别让它变成 number
const data = await res.json();

import requests

res = requests.post(
    "https://api.zise.com/v1/kyc/l2/sessions",
    headers={
        "x-auth-token": "Bearer $TOKEN",
        "x-on-behalf-of": "$MEMBER_ID",
        "x-idempotency-key": "$IDEMPOTENCY_KEY",
        "content-type": "application/json",
    },
    json={},
)
# 金额用 Decimal(str(...))，不要 float
data = res.json()

req, _ := http.NewRequest("POST", "https://api.zise.com/v1/kyc/l2/sessions",
    strings.NewReader(`{}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// 金额字段用 string 接，不要 float64

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.zise.com/v1/kyc/l2/sessions"))
    .header("x-auth-token", "Bearer $TOKEN")
    .header("x-on-behalf-of", "$MEMBER_ID")
    .header("x-idempotency-key", "$IDEMPOTENCY_KEY")
    .header("content-type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("""
{}
"""))
    .build();
// 金额字段用 String / BigDecimal，不要 double

$ch = curl_init('https://api.zise.com/v1/kyc/l2/sessions');
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-auth-token: Bearer $TOKEN',
    'x-on-behalf-of: $MEMBER_ID',
    'x-idempotency-key: $IDEMPOTENCY_KEY',
    'content-type: application/json',
  ],
  CURLOPT_POSTFIELDS => <<<'JSON'
{}
JSON,
]);
$res = curl_exec($ch);
// 金额用 bcmath / 字符串，不要 floatval

201

{
  "hosted_url": "https://api.zise.com/hosted/kyc/l2/kyc_3c81f0d29a4417d18e0b2f6a1c9d4e77",
  "expires_at": "2026-08-14T05:00:00.000Z"
}