> 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" %}
**未上线（文档预览）**：KYC OpenAPI 尚未在生产环境上线。本文档仅供接入方案预研，接口定义与业务规则在正式发布前可能调整。请勿用于生产业务；测试接入请联系 MusePay 确认可用性与开通安排，正式可用时间以发布通知为准。
{% endhint %}

{% hint style="warning" %}
每个请求都必须包含[通用参数](/cn/api-can-kao/api-reference/common-parameters.md)。下面的请求示例仅展示业务字段。本接口会发起收费认证申请，请先阅读[收费与在途规则](/cn/ji-cheng/kyc-api.md)。
{% endhint %}

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

为已存在的商户用户申请托管认证链接。新用户应先调用[创建认证用户](/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 | 本次认证的收费订单号，请持久保存。资金对账可用它调用[订单查询](/cn/api-can-kao/api-reference/acquiring-api/query-order.md)（`POST /v1/order/query`）查看费单状态与金额。 |
| user\_xid      | String | 商户用户标识。                                                                                                                        |
| user\_id       | String | MusePay 用户 ID。                                                                                                                 |
| level\_name    | String | 本次申请的档位，与请求一致。                                                                                                                 |
| kyc\_status    | String | 申请状态，创建成功即为 `PROCESSING`；后续状态见[查询 KYC 状态](/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"
  }
}
```

示例链接为占位值，不可用于认证。

## 处理规则

* 新建普通 `L1`/`L2` 申请时，如用户通过本产品已获得同等级或更高身份等级，请求会被拒绝，不生成链接或收费订单；请查询当前认证状态。`L1` → `L2` 允许升级，`L1` → `L1_AML` 允许增加 AML 筛查。AML 档位不单凭身份等级判为重复，具体可用档位仍受开通配置限制。同档在途续链及相同请求号的防重规则保持不变。
* 成功响应仅表示获取链接成功，不代表用户已提交资料或认证通过。链接短时有效，请及时打开；仅生成链接不会立即创建服务商侧申请人。
* 同一商户、同一用户跨所有档位仅允许一笔在途认证申请。链接过期或遗失时，用相同 `user_xid` 和相同 `level_name` 重新调用本接口即可**续链**：返回新链接和原 `fee_order_no`，不产生新收费订单、不重复扣费，原申请审核进度不受影响。在途期间申请不同档位仍被拒绝并返回 `209002`，请先等待原申请完成或关闭。
* 同一用户存在在途发卡认证时，本请求返回 `209003` 并被拒绝，请等待其完成或关闭。该校验仅在此方向生效，不会因独立 KYC 在途而阻止发卡侧发起申请。
* 经营发卡业务的账户不具备本产品准入资格，本请求会被拒绝且不产生收费订单；创建用户与状态查询不受影响，因此问题只会在此接口暴露。详见[与卡 KYC 的关系](/cn/ji-cheng/kyc-api.md)。
* 成功响应在 1 小时防重窗口内用相同 `request_id` 重试会返回原响应，不新建收费单，也不刷新链接有效期。每次 HTTP 请求仍须使用新的 `timestamp`、`nonce` 和签名。
* 处理中或已失败请求的相同 `request_id` 会被拒绝。超时或失败后先确认原请求与费单结果；如需重新申请，确认无在途单后使用新的请求标识。防重窗口外不保证重放。
* 审核通过和最终拒绝均结算费用；补件重试不是最终结果。链接生成失败会发起关单与解冻，处理可能有延迟。
* 链接过期或失效时按上一条直接续链即可，无需联系 MusePay，也不要换档位或新用户标识重新申请；仅当续链后仍无法打开或查询结果异常时，再联系 MusePay。

结果接收与查询：[KYC 商户回调](/cn/ji-cheng/webhook/kyc.md)、[查询 KYC 状态](/cn/api-can-kao/api-reference/kyc-api/query.md)。