> 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/ji-cheng/kyc-api.md).

# KYC API

集成独立商户 KYC 产品的完整流程与业务规则。

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

## 接入准备

1. 联系 MusePay 开通独立商户 KYC 产品，确认目标环境、可用认证档位、收费币种与价格。测试环境的开通不代表生产环境已开通。
2. 确认账户具备本产品准入资格：本产品的服务对象是不经营发卡业务的 API 型代理商账户。已开通有效发卡产品的账户不具备准入资格，其用户调用获取认证链接接口会被拒绝，请改用 [Card API](/cn/ji-cheng/card-api.md) 的认证流程。不确定自身账户类型时请联系 MusePay 确认，详见下文「与卡 KYC 的关系」。
3. 完成[身份验证](/cn/ji-cheng/authentication.md)和 [IP 白名单](/cn/ji-cheng/ip-whitelisting.md)配置，准备商户 API 凭据与充足的可用余额。
4. 确认商户 Webhook 地址已启用并可接收 `KYC_RESULT`。该地址是商户级共享配置，不通过获取链接接口逐次传入；变更时应检查对其他业务通知的影响。
5. 阅读 [KYC 回调的安全说明](/cn/ji-cheng/webhook/kyc.md)：本产品回调不带 RSA 签名。

## 集成流程

1. 为用户分配在商户账户内稳定且唯一的 `user_xid`，调用[创建认证用户](/cn/api-can-kao/api-reference/kyc-api/create-applicant.md)。保存返回的 `user_id`。
2. 为每次新认证生成新的 `request_id`，调用[获取认证链接](/cn/api-can-kao/api-reference/kyc-api/link.md)。保存 `request_id`、`user_xid`、`user_id` 与 `fee_order_no` 的关联。
3. 将返回的 `link` 展示给对应用户，由用户及时打开并完成资料提交。创建用户、获取链接成功都不表示认证完成；仅获取链接也不会立即创建服务商侧的认证申请人。
4. 接收 [KYC 商户回调](/cn/ji-cheng/webhook/kyc.md)，并使用[查询 KYC 状态](/cn/api-can-kao/api-reference/kyc-api/query.md)核对用户当前状态。查询接口也可用于主动跟踪进度。
5. 商户按自己的合规策略决定后续业务是否放行，不要将获取链接成功当作认证通过。

## 认证档位

`level_name` 必填，使用以下四个规范值之一，不传服务商后台的实际等级名称。仅可使用商户已开通的档位；缺失、空值或未知档位将被拒绝，不提供默认档。每个档位对应一个独立收费产品，一次申请仅产生一笔收费订单。

| 值        | 含义                   |
| -------- | -------------------- |
| `L1`     | 等级 1 身份认证。           |
| `L2`     | 等级 2 身份认证。           |
| `L1_AML` | 等级 1 身份认证及本次 AML 筛查。 |
| `L2_AML` | 等级 2 身份认证及本次 AML 筛查。 |

AML 档位不包含持续监控承诺。具体材料要求、认证范围和费用以开通约定为准。查询响应中的 `kyc_level` 是用户通过本产品已获得的最高认证等级（`0`/`1`/`2`），只在审核通过后提升，不能用来证明某次 AML 筛查已完成。

## 收费与在途限制

* 创建用户和查询状态不收取本产品认证费；获取链接会建立收费订单并冻结对应费用。
* **审核通过和最终拒绝都会结算认证费。** 要求补件或可重试拒绝不是最终结果，不在该阶段结算费用或发送最终结果回调。
* 同一商户、同一用户，无论选择哪个档位，同时只允许一笔在途认证订单。已有在途订单时，不要换档位或换 `request_id` 重复申请。
* 收费订单默认在创建满 24 小时仍未完成时，由定时任务发起超时关闭与冻结资金释放，并非精确到秒。该时限不等于链接有效期或审核时效承诺；超时关闭不发送 `KYC_RESULT`，也不代表服务商侧审核已取消。超过时限仍在审核或收到迟到结果时，请联系 MusePay 确认原申请，不要仅凭用户当前等级判断费单已完成。
* 原订单完成或关闭后，新申请视为一次新的收费请求；升级、降级、同档重新认证以及已经通过认证的用户再次申请，均不代表免费。
* 获取链接失败时，系统会发起对应收费订单的关闭与冻结资金释放；处理不是即时完成。链接过期或失效属正常情况，用相同 `user_xid` 与档位重新调用获取链接接口续链即可；结果不明、资金未恢复或续链异常时，请联系 MusePay 确认，不要反复创建新申请。

## 重试与结果关联

获取链接的成功响应在 1 小时防重窗口内可按同一 `request_id` 重放。重试必须保持业务字段不变，并重新生成通用参数中的 `timestamp`、`nonce` 和 `sign`。返回的仍是原链接，不会延长其有效期。

处理中或已失败的请求可能返回重复请求错误；发生超时不能假定原请求未受理。请先确认原请求及收费订单的处理结果，再决定是否以新 `request_id` 申请。不要依赖超过防重窗口后的重放行为，必须在商户系统中持久保存订单关联。

## 与卡 KYC 的关系

独立商户 KYC 与发卡认证**在同一代理商账户下互斥**。已开通有效发卡产品的账户不具备本产品准入资格，其用户调用 `POST /v1/kyc/link` 会被拒绝且不产生收费订单；既有卡业务应继续使用 [Card API](/cn/ji-cheng/card-api.md) 的认证流程，卡产品的接入、档位和收费规则仍以该文档为准。独立 KYC 不会自动开通发卡权限。

资格校验仅在 `POST /v1/kyc/link` 执行。[创建认证用户](/cn/api-can-kao/api-reference/kyc-api/create-applicant.md)和[查询 KYC 状态](/cn/api-can-kao/api-reference/kyc-api/query.md)不受影响，因此不具备准入资格的账户会表现为「创建用户和查询都正常、仅获取链接失败」，请在此接口定位问题。

除资格校验外，同一用户存在在途发卡认证时，新的独立 KYC 申请会返回 `209003` 并被拒绝。该校验仅在此方向生效，不会因独立 KYC 在途而阻止发卡侧发起申请。请等待在途申请完成或关闭。

不同商户的同名 `user_xid` 不表示同一用户。