> 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

独立商户 KYC 的最终结果通过商户级共享回调地址发送，HTTP 方法为 `POST`。请在开通时确认该地址已启用；它不是每次请求传入的 `notify_url`，不要为 KYC 随意覆盖其他业务正在使用的回调地址。本产品只发商户回调，不向终端用户另发邮件、推送或站内信。

## 触发时机

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

两种结果都会结算认证费。投递是异步的，可能延迟或重复，因此没收到回调既不代表没有订单也不代表没有扣费。收到回调即表示对应费单已结算；金额可用 `feeOrderNo` 调用[订单查询](https://docs.musepay.io/cn/api-can-kao/api-reference/acquiring-api/query-order.md)核对。

## 安全说明

{% hint style="warning" %}
**`KYC_RESULT` 没有 RSA 签名，也没有 `sign` 字段。** [Webhook 概览](https://docs.musepay.io/cn/ji-cheng/webhook.md)里的验签流程不适用于本通知。你发出的 API 请求仍按[身份验证](https://docs.musepay.io/cn/ji-cheng/authentication.md)签名。
{% endhint %}

用 HTTPS 接收，但 HTTPS 不等于对方就是 MusePay。不要只凭一条未签名回调就放行业务：先按你自己保存的请求—用户关联核对，再用[查询 KYC 状态](https://docs.musepay.io/cn/api-can-kao/api-reference/kyc-api/query.md)复核。两边结论不一致时联系 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`。                                |

### 通过示例

```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.md#retry-attempts)。请自行处理重复与延迟，结果缺失时用查询接口核实或联系 MusePay。
