> For the complete documentation index, see [llms.txt](https://docs.musepay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/link.md).

# 获取认证链接

{% hint style="warning" %}
每个请求都必须包含[通用参数](https://docs.musepay.io/cn/api-can-kao/api-reference/common-parameters.md)。下面的示例仅展示业务字段。
{% endhint %}

<mark style="color:green;">`POST`</mark> `/v1/kyc/link`

发起一次收费认证并返回托管链接。新用户请先调用[创建认证用户](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/create-applicant.md)。

## 请求 Body

| 名称          | 类型     | 必填 | 说明                                           |
| ----------- | ------ | -- | -------------------------------------------- |
| request\_id | String | 是  | 商户账户内唯一的申请标识。仅在重试同一次申请时复用，且业务字段不得改变。         |
| user\_xid   | String | 是  | 当前商户名下已存在的用户标识。                              |
| level\_name | String | 是  | `L1`、`L2`、`L1_AML`、`L2_AML`。仅接受已开通档位，不提供默认值。 |

## 请求示例

```json
{
  "request_id": "kyc-link-202610150001",
  "user_xid": "customer-0001",
  "level_name": "L1"
}
```

## 响应 Body

以下字段位于 `data` 中。

| 名称             | 类型     | 说明                                                                                                                                           |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| request\_id    | String | 申请标识，与最终回调里的 `data.requestId` 一致。                                                                                                            |
| fee\_order\_no | String | 本次认证的费单号，请在你的系统持久化保存；用 [`POST /v1/order/query`](https://docs.musepay.io/cn/api-can-kao/api-reference/acquiring-api/query-order.md) 核对其状态和金额。 |
| user\_xid      | String | 商户侧用户标识。                                                                                                                                     |
| user\_id       | String | MusePay 用户 ID。                                                                                                                               |
| level\_name    | String | 本次申请的档位，与请求一致。                                                                                                                               |
| kyc\_status    | String | 创建后为 `PROCESSING`，后续状态见[查询 KYC 状态](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/query.md)。                                   |
| kyc\_level     | String | 该用户经本产品已取得的最高等级：`0`/`1`/`2`。申请更高等级不会提前提升它。                                                                                                   |
| link           | String | 含短时有效凭据的托管链接。只交给该用户本人，不要公开或写入公开日志。                                                                                                           |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyc-link-202610150001",
    "fee_order_no": "2026101500000000000000000001",
    "user_xid": "customer-0001",
    "user_id": "1000001",
    "level_name": "L1",
    "kyc_status": "PROCESSING",
    "kyc_level": "0",
    "link": "https://in.sumsub.com/websdk/p/EXAMPLE_TOKEN"
  }
}
```

示例链接为占位符，无法使用。

## 处理规则

* 返回成功只代表拿到了链接，不代表用户已提交材料或已通过审核，请尽快打开。
* 同一用户跨所有档位同时只允许一笔申请。续链指用相同 `user_xid` 和相同 `level_name` 再调一次本接口：返回新链接和原 `fee_order_no`，不产生新费单、不重复扣费。在途期间改档位会返回 `209002`。
* 用户已取得该等级或更高等级时，普通 `L1`/`L2` 申请返回 `209004`，不出链接、不建费单。`L1` → `L2` 升级和 `L1` → `L1_AML` 增加筛查允许。
* 已由发卡业务认证的用户返回 `209003`。经营发卡业务的账户不具备本产品准入资格，详见[与卡 KYC 的关系](https://docs.musepay.io/cn/ji-cheng/kyc-api.md#relationship-to-card-kyc)。
* 1 小时内用相同 `request_id` 重试已成功的请求，会返回原响应，不新增费单、也不延长链接有效期；每次 HTTP 请求仍需重新生成 `timestamp`、`nonce` 和签名。
* 同一小时内，失败或仍在执行的请求不会重跑：复用该 `request_id` 会返回重复请求错误。请先确认原请求结果，确认没有在途订单后再换新 `request_id`。

最终结果见 [KYC 回调](https://docs.musepay.io/cn/ji-cheng/webhook/kyc.md)，也可随时用[查询 KYC 状态](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/query.md)读取。
