> ## 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.

# 认证申请

## 功能说明

为商户发起微信/支付宝实名认证申请（JSAPI 支付、当面付等产品的前置条件）。认证按**支付机构维度**发起，路径区分微信与支付宝。

* **前置条件**：商户状态为 `ACTIVE`，且该机构进件已完成（`COMPLETED`）或电话核身完成（`PHONE_VERIFIED`）；不满足时返回 400 `BUSINESS_ERROR`，文案说明当前状态；
* **同一商户 + 同一机构 + 同一渠道只允许一笔认证申请**，重复申请返回 400 `BUSINESS_ERROR`「已申请认证，请勿重复提交」；
* **申请响应不返回二维码**。平台渲染后的认证二维码通过[认证结果查询](https://opendocs.xft.xin/open/payment/auth/apply-query.md)的 `qr_code` 获取；
* **机构差异**：易宝真实发起认证申请并返回申请单号；易生透传渠道申请状态；付临门为机构自动认证，返回 `AUTO_AUTH` 且无申请单号。

**支持商户**：全部已开通进件权限的渠道商（及其旗下品牌），仅可操作本主体录入的商户

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

**请求路径**：

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

## 请求参数

| 字段 | 是否必填 | 字段类型 | 字段说明 |
| - | - | - | - |
| `merchant_code` | 是 | String(≤64) | 平台商户号，进件通知与[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)中下发 |
| `institution_code` | 是 | String(≤64) | 支付机构编码，见[支付机构列表](https://opendocs.xft.xin/open/payment/appendix/institutions.md) |

## 响应参数

| 字段 | 是否必填 | 字段类型 | 字段说明 |
| - | - | - | - |
| `cep_order_no` | 否 | String | 认证申请单号；付临门自动认证时为空 |
| `apply_status` | 是 | String | 认证申请状态，平台统一英文码，取值见下方说明 |
| `channel_code` | 是 | String | 认证渠道：`WECHAT` / `ALIPAY` |
| `sub_merchant_code` | 否 | String | 微信/支付宝子商户号，机构未返回时为空 |
| `third_order_no` | 否 | String | 机构侧申请流水号，机构未返回时为空 |

## 认证申请状态说明

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

| 状态 | 说明 |
| - | - |
| `AUDITING` | 审核中（易宝、易生申请提交后的初始状态） |
| `AUTO_AUTH` | 机构自动认证（付临门），无申请单号，无需扫码 |
| `PASSED` | 审核通过 |
| `REJECTED` | 审核驳回，可通过[撤销认证](https://opendocs.xft.xin/open/payment/auth/cancel.md)作废本次申请 |
| `CANCELED` | 已作废（申请单已被撤销） |
| `FAIL` | 失败，需重新发起认证申请 |
| `EDITTING` | 编辑中 |
| `CONTACT_PROCESSING` | 联系人处理中 |
| `CONTACT_CONFIRM` | 待确认联系信息 |
| `LEGAL_CONFIRM` | 待法人确认 |
| `FREEZED` | 已冻结 |
| `CONFIRM` | 已提交 |
| `INIT` | 初始，需重新发起认证申请 |
| `UNKNOW` | 未申请 |

## 示例

**请求（微信认证，易生支付）**

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

**响应**

```json theme={"system"}
{
  "cep_order_no": "AUTH202610180000001",
  "apply_status": "AUDITING",
  "channel_code": "WECHAT",
  "sub_merchant_code": "1900000101",
  "third_order_no": "20261018085608000001"
}
```

**响应（付临门自动认证）**

```json theme={"system"}
{
  "cep_order_no": "",
  "apply_status": "AUTO_AUTH",
  "channel_code": "WECHAT",
  "sub_merchant_code": "1900000101",
  "third_order_no": ""
}
```

**失败示例（重复申请）**

```json theme={"system"}
{
  "code": 400,
  "reason": "BUSINESS_ERROR",
  "message": "已申请认证，请勿重复提交",
  "metadata": {}
}
```

**失败示例（未进件）**

```json theme={"system"}
{
  "code": 400,
  "reason": "BUSINESS_ERROR",
  "message": "尚未进件，不能申请实名认证",
  "metadata": {}
}
```

> [!NOTE]
>
> 申请成功后请间隔 30 秒以上轮询[认证结果查询](https://opendocs.xft.xin/open/payment/auth/apply-query.md)：`apply_status` 推进至 `PASSED` 后，认证结果查询响应中的 `qr_code` 供商户扫码完成微信/支付宝侧授权。


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