> 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/webhook/kyc.md).

# KYC

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

独立商户 KYC 的最终结果通过商户级共享回调地址发送，HTTP 方法为 `POST`。请在开通时确认该地址已启用；它不是在每次获取链接时传入的 `notify_url`。不要为 KYC 随意覆盖其他业务正在使用的回调地址。

本产品仅发送商户 Webhook，不向终端用户另发邮件、推送或站内信。

## 触发时机

* 审核通过：`kycStatus` 为 `APPROVED`。
* 最终拒绝：`kycStatus` 为 `REJECTED`，`reviewRejectType` 为 `FINAL`。
* 补件或可重试拒绝（`RETRY`）不是最终结果，不发送此最终结果通知。

审核通过和最终拒绝均结算认证费。收费处理与回调投递是异步流程，通知可能延迟或重复；不要将未收到通知理解为订单不存在或没有扣费。收到本通知即表示对应费单已结算；资金明细可用 link 返回的 `fee_order_no` 调用[订单查询](/cn/api-can-kao/api-reference/acquiring-api/query-order.md)核对。

## 安全说明

{% hint style="warning" %}
**KYC\_RESULT 当前不带 RSA 签名，也没有 `sign` 字段。** [Webhook 总览](/cn/ji-cheng/webhook.md)中的 RSA 验签方式不适用于本通知；API 请求仍必须按[身份验证](/cn/ji-cheng/authentication.md)要求签名。
{% endhint %}

使用 HTTPS 接收通知，但 HTTPS 本身不能证明请求由 MusePay 发出。不要仅凭未签名通知放行业务；应校验本地保存的请求与用户关联，并从商户后端调用[查询 KYC 状态](/cn/api-can-kao/api-reference/kyc-api/query.md)核对当前状态。查询结果不证明某次收费订单或 AML 筛查的结果，遇到不一致或需要确认该次申请时请联系 MusePay。

## 报文结构

注意：回调字段使用 camelCase，与 API 响应中的 snake\_case 不同。

| 名称   | 类型     | 说明                |
| ---- | ------ | ----------------- |
| type | String | 固定为 `KYC_RESULT`。 |
| data | Object | 认证结果对象，见下表。       |

### `data`

| 名称                | 类型              | 说明                                                           |
| ----------------- | --------------- | ------------------------------------------------------------ |
| feeOrderNo        | String          | 本次已结算的费单号，对应获取链接响应中的 `fee_order_no`。                         |
| userId            | Number          | MusePay 用户 ID。API 响应中的 `user_id` 是字符串，比较时应统一类型。              |
| requestId         | String          | 原获取链接请求的 `request_id`，不是创建用户或查询请求的标识。                        |
| levelName         | String          | 本次申请的档位：`L1`、`L2`、`L1_AML`、`L2_AML`。                         |
| kycStatus         | String          | `APPROVED` 通过，`REJECTED` 最终拒绝。                               |
| kycLevel          | Number          | 用户通过本产品已获得的最高认证等级：`0`/`1`/`2`。拒绝通知中为拒绝发生前的等级。                |
| userXid           | String          | 可选商户用户标识，可能省略。请通过已保存的 `requestId` 与 `userId` 关联商户用户，不要依赖此字段。 |
| moderationComment | String          | 可选审核说明。                                                      |
| rejectLabels      | Array of String | 可选拒绝标签列表。                                                    |
| reviewRejectType  | String          | 可选拒绝类型；最终拒绝为 `FINAL`。                                        |

可选字段可能省略。`feeOrderNo` 标识本次已结算费单，请同时保存它与获取链接请求、用户的关联。

### 通过示例

```json
{
  "type": "KYC_RESULT",
  "data": {
    "feeOrderNo": "2026101500000000000000000001",
    "userId": 1000001,
    "requestId": "kyc-link-202610150001",
    "levelName": "L1",
    "kycStatus": "APPROVED",
    "kycLevel": 1
  }
}
```

### 最终拒绝示例

```json
{
  "type": "KYC_RESULT",
  "data": {
    "feeOrderNo": "2026101500000000000000000001",
    "userId": 1000001,
    "requestId": "kyc-link-202610150002",
    "levelName": "L1_AML",
    "kycStatus": "REJECTED",
    "kycLevel": 0,
    "moderationComment": "Example final rejection",
    "rejectLabels": ["EXAMPLE_LABEL"],
    "reviewRejectType": "FINAL"
  }
}
```

拒绝标签和说明仅为示例，不是固定枚举。

## 接收与重试

* 按 `type`、`data.requestId` 和 `data.userId` 幂等处理；不要使用签名做防重，也不要只按用户 ID 去重，否则会漏掉后续申请。
* 可靠保存待处理消息后及时返回 HTTP `200`，耗时核验可由商户自己的异步任务处理。
* 投递重试遵循 [Webhook 重试机制](https://docs.musepay.io/cn/ji-cheng/webhook/pages/YKpgfDxnztuLfegMCFyb#重试机制)。商户应能处理重复、延迟通知，并对缺失结果主动查询或联系 MusePay。