> ## Documentation Index
> Fetch the complete documentation index at: https://opendocs.xft.xin/llms.txt
> Use this file to discover all available pages before exploring further.

# 认证结果查询

## 功能说明

查询商户在指定支付机构的微信/支付宝认证结果，一次返回三类信息：

1. **认证（授权）状态**：`auth_status`，商户在微信/支付宝侧的授权是否生效；
2. **认证申请状态**：`apply_status`，平台认证申请单的处理进度（平台统一英文码）；
3. **认证二维码**：`qr_code`，申请后由平台渲染，供商户扫码完成授权。

* 请求必须同时指定 `merchant_code` 与 `institution_code`，按机构维度查询；
* 仅可查询本主体录入的商户（渠道商可查询旗下品牌录入的商户），否则返回 403 `PERMISSION_DENIED`；
* 认证状态为实时查询机构侧结果，平台不做结果缓存，轮询间隔建议不低于 30 秒。

**支持商户**：全部已开通进件权限的渠道商（及其旗下品牌）

**请求方式**：`POST`

**请求路径**：

| 渠道 | 请求路径 |
| - | - |
| 微信 | `POST /openapi/v1/merchant/auth/wechat/query` |
| 支付宝 | `POST /openapi/v1/merchant/auth/alipay/query` |

## 请求参数

| 字段 | 是否必填 | 字段类型 | 字段说明 |
| - | - | - | - |
| `merchant_code` | 是 | String(≤64) | 平台商户号 |
| `institution_code` | 是 | String(≤64) | 支付机构编码，见[支付机构列表](https://opendocs.xft.xin/open/payment/appendix/institutions.md) |

## 响应参数

| 字段 | 是否必填 | 字段类型 | 字段说明 |
| - | - | - | - |
| `sub_merchant_code` | 否 | String | 微信/支付宝子商户号，未就绪时为空 |
| `auth_status` | 是 | String | 认证（授权）状态：`AUTHORIZED` / `UNAUTHORIZED` / `CLOSED` / `NOTEXIST`；机构未返回或无法识别时为空串 |
| `auth_msg` | 否 | String | 认证授权描述，机构返回的说明文案 |
| `apply_status` | 是 | String | 认证申请状态，平台统一英文码，取值见下方说明 |
| `qr_code` | 否 | String | 认证二维码链接，申请后由平台渲染；无申请记录或未生成时为空 |
| `apply_status_msg` | 否 | String | 认证申请状态描述 |
| `reject_reason` | 否 | String | 认证申请驳回原因 |

## 认证（授权）状态

| 状态 | 说明 |
| - | - |
| `AUTHORIZED` | 已授权，对应渠道可正常交易 |
| `UNAUTHORIZED` | 未授权（可发起认证申请） |
| `CLOSED` | 已销户 |
| `NOTEXIST` | 机构侧商户号不存在 |
| 空串 | 机构未返回或状态值无法识别（平台不透传机构原始码） |

## 认证申请状态

`apply_status` 为平台统一码（各机构原始码已由平台映射，不会返回数字码）：

| 状态 | 说明 |
| - | - |
| `PENDING_SUBMIT` | 待提交（尚无认证申请记录） |
| `AUDITING` | 审核中 |
| `EDITTING` | 编辑中 |
| `CONTACT_PROCESSING` | 联系人处理中 |
| `CONTACT_CONFIRM` | 待确认联系信息 |
| `LEGAL_CONFIRM` | 待法人确认 |
| `PASSED` | 审核通过 |
| `REJECTED` | 审核驳回 |
| `FAIL` | 失败，需重新发起认证申请 |
| `CANCELED` | 已作废（申请单已被撤销） |
| `FREEZED` | 已冻结 |
| `INIT` | 初始，需重新发起认证申请 |
| `CONFIRM` | 已提交 |
| `UNKNOW` | 未申请 |
| 空串 | 机构未返回或状态值无法识别 |

## 示例

**请求（微信认证）**

```json theme={"system"}
{
  "merchant_code": "801292371559190",
  "institution_code": "EASYPAY"
}
```

**响应（已授权）**

```json theme={"system"}
{
  "sub_merchant_code": "1900000101",
  "auth_status": "AUTHORIZED",
  "auth_msg": "已授权",
  "apply_status": "PASSED",
  "qr_code": "",
  "apply_status_msg": "审核通过",
  "reject_reason": ""
}
```

**响应（待扫码授权）**

```json theme={"system"}
{
  "sub_merchant_code": "1900000101",
  "auth_status": "UNAUTHORIZED",
  "auth_msg": "未授权",
  "apply_status": "AUDITING",
  "qr_code": "https://pay.xft.xin/openapi/auth/qrcode?token=xxxx",
  "apply_status_msg": "审核中",
  "reject_reason": ""
}
```

**失败示例（参数错误）**

```json theme={"system"}
{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "institution_code 不能为空",
  "metadata": {}
}
```

> [!NOTE]
>
> 认证状态以本接口为准。认证申请被驳回（`apply_status=REJECTED`）后，可通过[撤销认证](https://opendocs.xft.xin/open/payment/auth/cancel.md)作废本次申请；认证失败（`auth_status=UNAUTHORIZED` 且 `apply_status=FAIL`）需联系平台重新发起。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.