> 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 的接入流程、档位、结果处理与错误码。

独立商户 KYC 用 MusePay 托管的认证链接完成你自有终端用户的实名认证，一共三个接口：建用户、取链接、看结果。

## 接入准备

1. 联系 MusePay 为你的账户开通本产品，确认可用档位、收费币种与价格。
2. 本产品服务不经营发卡业务的 API 型代理商账户。已开通发卡业务的账户请改用 [Card API](https://docs.musepay.io/cn/ji-cheng/card-api.md) 的认证流程；不确定属于哪一类请联系 MusePay 确认。
3. 完成[身份验证](https://docs.musepay.io/cn/ji-cheng/authentication.md)与 [IP 白名单](https://docs.musepay.io/cn/ji-cheng/ip-whitelisting.md)配置，并保持充足余额——生成链接时即冻结对应认证费。
4. 确认商户 Webhook 地址可接收 `KYC_RESULT`。该地址是商户级共享配置，不是逐次请求传入的 `notify_url`，变更时请检查对其他业务通知的影响。本产品回调**不带 RSA 签名**，详见 [KYC 回调说明](https://docs.musepay.io/cn/ji-cheng/webhook/kyc.md)。

## 流程

| 步骤 | 调用                                                                                                                                                | 结果                                               |
| -- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| 1  | [创建认证用户](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/create-applicant.md)                                                        | 用稳定的 `user_xid` 登记用户，返回 `user_id`。不收费。           |
| 2  | [获取认证链接](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/link.md)                                                                    | 发起一次收费认证，返回托管 `link` 与 `fee_order_no`。链接只给该用户本人。 |
| 3  | [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) | 拿最终结果。回调是推送，查询是主动拉取。                             |

用户打开链接不等于认证通过。用户在每个等级能做什么，由你按自身合规要求决定。

## 档位

每次请求链接都必须传 `level_name`，没有默认值，缺失或未知取值直接拒绝；只有已开通的档位可用。

| `level_name` | 覆盖范围               |
| ------------ | ------------------ |
| `L1`         | 身份认证 1 级           |
| `L2`         | 身份认证 2 级           |
| `L1_AML`     | 1 级 + 本次申请的 AML 筛查 |
| `L2_AML`     | 2 级 + 本次申请的 AML 筛查 |

AML 筛查只覆盖本次申请，不是持续监控。所需材料、审查范围和价格以你的接入协议为准。

## 结果

`kyc_status` 来自[查询 KYC 状态](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/query.md)：

| 状态            | 含义                     | 你的下一步                                                  |
| ------------- | ---------------------- | ------------------------------------------------------ |
| `NOT_STARTED` | 尚未发起申请。                | 调用获取链接接口。                                              |
| `PROCESSING`  | 等用户提交、审核中，或等待补件。       | 费用处于冻结状态。等待，或链接过期后续链。                                  |
| `APPROVED`    | 本次申请通过。                | 费用已结算。按等级放开用户权限。                                       |
| `REJECTED`    | 本次申请最终拒绝。              | 费用已结算。让用户重试前先读 `moderation_comment` 与 `reject_labels`。 |
| `EXPIRED`     | 费单约 24 小时后关闭，审核可能仍在进行。 | 未扣费。再查一次或联系 MusePay。                                   |

另有字段 `kyc_level`，表示该用户经本产品**已取得**的最高等级（`0`/`1`/`2`），仅在通过时上升，与发卡业务的等级相互独立。

## 会改变你代码的规则

* **同一用户同时只允许一笔申请**，跨所有档位。在途期间改其他档位会得到 `209002`。
* **链接过期或遗失：续链，不要重新申请。** 用相同 `user_xid` 和相同 `level_name` 再调一次获取链接接口，即可拿到新链接和原 `fee_order_no`，不产生新费单、不重复扣费。换档位不算续链。
* **通过与最终拒绝都收费。** 要求补件不算最终结果：不结算费用，也不发 `KYC_RESULT`。
* **1 小时内用相同 `request_id` 重试。** 业务字段保持不变，每次 HTTP 请求重新生成 `timestamp`、`nonce` 和 `sign`。在这个窗口内，失败或仍在执行的请求不会重跑，复用该 `request_id` 会返回重复请求错误；确认原请求结果之后再换新 `request_id`。
* **回调没有签名。** 不要只凭一条未签名回调就放行业务：保留你自己的请求—用户关联，并用查询接口复核。
* **两个方向的字段命名和类型不同。** API 响应是 `snake_case`，`user_id` 和 `kyc_level` 是字符串；回调是 `camelCase`，同一字段是数字。比较前先归一化，关联键用 `requestId` + `userId`。

## 错误码

| 错误码      | 含义                                                   | 处理                       |
| -------- | ---------------------------------------------------- | ------------------------ |
| `209002` | 该用户已有 KYC 认证在途。                                      | 等待其完成或关闭，或对现有链接续链。       |
| `209003` | 出现在 `POST /v1/kyc/link`：该用户已由发卡业务认证。                 | 该用户改用 Card API 流程。       |
| `209004` | 出现在 `POST /v1/kyc/link`：该用户已取得该等级或更高等级。              | 不出链接、不建费单。跳过本次申请或申请更高等级。 |
| `209005` | 出现在 `POST /v1/kyc/applicant/create`：该邮箱已被你账户下另一用户使用。 | 换一个邮箱注册。                 |

## 与卡 KYC 的关系 <a href="#relationship-to-card-kyc" id="relationship-to-card-kyc"></a>

独立 KYC 与发卡认证服务两类不同账户，二者互斥：本产品面向没有发卡业务的 API 型代理商账户。已由发卡业务认证过的用户，调用获取链接接口会返回 `209003`，且不生成费单。创建用户与状态查询不受影响，因此资格问题只在获取链接时暴露。不同商户下相同的 `user_xid` 是两个不同的用户。
