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

# 查询 KYC 状态

{% hint style="warning" %}
每个请求都必须包含[通用参数](/cn/api-can-kao/api-reference/common-parameters.md)。下面的示例仅展示业务字段。
{% endhint %}

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

读取该用户最近一次认证申请的状态，以及已取得的认证等级。不收费。用户尚不存在时请先调用[创建认证用户](/cn/api-can-kao/api-reference/kyc-api/create-applicant.md)。

## 请求 Body

| 名称          | 类型     | 必填 | 说明                             |
| ----------- | ------ | -- | ------------------------------ |
| request\_id | String | 是  | 本次查询的标识，每次取新值即可，不必与申请链接时的标识一致。 |
| user\_xid   | String | 是  | 商户名下的用户标识。                     |

## 请求示例

```json
{
  "request_id": "kyc-query-202610150001",
  "user_xid": "customer-0001"
}
```

## 响应 Body

以下字段位于 `data` 中。等级和状态都是字符串，不是 JSON 数字。

| 名称                       | 类型              | 说明                                                                  |
| ------------------------ | --------------- | ------------------------------------------------------------------- |
| request\_id              | String          | 本次查询的标识。                                                            |
| user\_xid                | String          | 商户侧用户标识。                                                            |
| user\_id                 | String          | MusePay 用户 ID。                                                      |
| level\_name              | String          | 最近一次申请的档位（`L1`、`L2`、`L1_AML`、`L2_AML`）；从未申请过为 `null`。               |
| kyc\_status              | String          | 最近一次申请的状态，见下表。                                                      |
| kyc\_level               | String          | 本产品已取得的最高等级：`0` 无、`1` 一级、`2` 二级。                                    |
| application\_request\_id | String          | 最近一次申请对应的链接 `request_id`；从未申请过为 `null`。用于和回调里的 `data.requestId` 对账。 |
| moderation\_comment      | String          | 审核意见，仅在 `kyc_status` 为 `REJECTED` 时返回。                              |
| reject\_labels           | Array of String | 拒绝标签，仅在 `kyc_status` 为 `REJECTED` 时返回。                              |
| review\_reject\_type     | String          | 拒绝类型，最终拒绝为 `FINAL`，仅在 `kyc_status` 为 `REJECTED` 时返回。                |

### `kyc_status` 取值

| 取值            | 含义                     | 费用   |
| ------------- | ---------------------- | ---- |
| `NOT_STARTED` | 尚未发起申请。                | 无。   |
| `PROCESSING`  | 等用户提交、审核中，或等待补件。       | 冻结中。 |
| `APPROVED`    | 最近一次申请通过。              | 已结算。 |
| `REJECTED`    | 最近一次申请被最终拒绝。           | 已结算。 |
| `EXPIRED`     | 费单约 24 小时后关闭，审核可能仍在进行。 | 已释放。 |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "request_id": "kyc-query-202610150001",
    "user_xid": "customer-0001",
    "user_id": "1000001",
    "level_name": "L1",
    "kyc_status": "APPROVED",
    "kyc_level": "1",
    "application_request_id": "kyc-link-202610150001"
  }
}
```

## 如何解读

* `level_name` 和 `kyc_status` 描述**最近一次**申请，`kyc_level` 描述用户**当前持有**的等级。例如已有 1 级的用户正在跑 `L2_AML` 申请时，返回 `level_name=L2_AML`、`kyc_status=PROCESSING`、`kyc_level=1`。
* `kyc_level` 仅在通过时上升。申请、被拒或过期都不会改变它，它与其他 MusePay 产品（如发卡业务）的等级相互独立。
* 本接口只返回每个用户的最近一次申请。要对账某一笔，请把 [KYC 回调](/cn/ji-cheng/webhook/kyc.md)里的 `data.requestId` 与 `application_request_id` 匹配。费用明细用链接响应里的 `fee_order_no` 调用[订单查询](/cn/api-can-kao/api-reference/acquiring-api/query-order.md)（`POST /v1/order/query`）核对。