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

# 审核异步通知

## 功能说明

商户审核（通过/驳回）与机构进件进入**终态**时，平台主动以 HTTP POST 方式通知商户录入时上送的 `back_url`。**中间态不下发通知**，请通过[进件状态查询](https://opendocs.xft.xin/open/payment/merchant/apply-query.md)获取。

## 通知时机

| 触发条件 | `event_type` | `apply_status` | 说明 |
| - | - | - | - |
| 商户审核通过 | `MERCHANT_PASSED` | `PASSED` | 平台审核通过后下发，无机构维度 |
| 商户审核驳回 | `MERCHANT_REJECTED` | `REJECTED` | 平台审核驳回后下发，无机构维度，`reject_reason` 非空 |
| 机构进件完成 | `INSTITUTION_COMPLETED` | `COMPLETED` | 单机构进件完成、子商户号/终端号就绪后下发，带机构维度 |
| 机构进件驳回 | `INSTITUTION_REJECTED` | `REJECTED` | 单机构进件被渠道驳回后下发，带机构维度，`reject_reason` 非空 |
| 机构进件失败 | `INSTITUTION_FAILED` | `FAILED` | 单机构进件失败或签约失败后下发，带机构维度 |

客户端按 `event_type` 分支处理即可：`MERCHANT_*` 为商户审核事件（无机构维度），`INSTITUTION_*` 为单机构进件事件（带 `institution_code`）。`apply_status` 同步保留状态值，可直接用于状态更新。

## 通知报文

**请求头**（平台 → 渠道商，与请求签名同一机制）：

| Header | 说明 |
| - | - |
| `Content-Type` | `application/json` |
| `Client-Id` | 渠道商/品牌侧 app\_key（平台签发，与调用开放接口所用凭据相同） |
| `Signature-Type` | 固定 `HmacSHA256` |
| `Timestamp` | 通知时间，秒级时间戳 |
| `Nonce-Str` | 随机串 |
| `Signature` | 通知签名，验签方式见[签名验签说明](https://opendocs.xft.xin/open/payment/spec/signature.md) |

**请求体**：

| 字段 | 是否必填 | 字段类型 | 字段说明 |
| - | - | - | - |
| `event_type` | 是 | String | 事件类型：`MERCHANT_PASSED` / `MERCHANT_REJECTED` / `INSTITUTION_COMPLETED` / `INSTITUTION_REJECTED` / `INSTITUTION_FAILED` |
| `out_apply_no` | 是 | String | 申请单号 |
| `merchant_code` | 是 | String | 平台商户号 |
| `apply_status` | 是 | String | 终态：`PASSED` / `COMPLETED` / `REJECTED` / `FAILED` |
| `reject_reason` | 否 | String | 驳回/失败原因，`REJECTED`/`FAILED` 时非空 |
| `timestamp` | 是 | String | 通知时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `institution_code` | 机构维度必带 | String | 支付机构编码；商户审核通过/驳回事件不带 |
| `institution_name` | 否 | String | 支付机构名称 |
| `institution_merchant_code` | 否 | String | 机构侧商户号 |
| `channel_return_code` | 否 | String | 渠道返回码 |
| `unionpay_merchant_no` | 否 | String | 银联商户号 |
| `wechat_sub_merchant_code` | 否 | String | 微信子商户号 |
| `alipay_sub_merchant_code` | 否 | String | 支付宝子商户号 |
| `terminal_code` | 否 | String | 终端号 |

## 应答要求

| 项 | 约定 |
| - | - |
| 成功 | 返回 HTTP **200**，且 body 为 `{"code":"SUCCESS","message":"成功"}`（`code` 必须为 `SUCCESS`）才视为通知送达 |
| 失败 | 其他状态码、应答 body 未返回 `code=SUCCESS`，或超时（单次超时 10 秒），平台按**指数退避**重试：1s → 5s → 30s → 2min → 6min，最多 5 次 |
| 最终失败 | 通知落库，渠道商可联系平台人工补发 |

**幂等**：平台可能重发通知（网络原因），渠道商按 `out_apply_no + institution_code + event_type`（商户审核事件无 `institution_code`）去重，重复通知不重复处理。

## 示例

**通知请求（机构进件完成）**

```json theme={"system"}
{
  "event_type": "INSTITUTION_COMPLETED",
  "out_apply_no": "TST-20261018-CH-0012",
  "merchant_code": "801292371559190",
  "apply_status": "COMPLETED",
  "reject_reason": "",
  "timestamp": "2026-10-18 09:10:00",
  "institution_code": "EASYPAY",
  "institution_name": "易生支付",
  "institution_merchant_code": "890000000000001",
  "channel_return_code": "000000",
  "unionpay_merchant_no": "898110000000001",
  "wechat_sub_merchant_code": "1900000101",
  "alipay_sub_merchant_code": "2088000000000001",
  "terminal_code": "T000001"
}
```

**通知请求（商户审核通过，无机构维度）**

```json theme={"system"}
{
  "event_type": "MERCHANT_PASSED",
  "out_apply_no": "TST-20261018-CH-0012",
  "merchant_code": "801292371559190",
  "apply_status": "PASSED",
  "reject_reason": "",
  "timestamp": "2026-10-18 09:00:00"
}
```

**通知请求（商户审核驳回，无机构维度）**

```json theme={"system"}
{
  "event_type": "MERCHANT_REJECTED",
  "out_apply_no": "TST-20261018-CH-0012",
  "merchant_code": "801292371559190",
  "apply_status": "REJECTED",
  "reject_reason": "营业执照信息与工商登记不一致",
  "timestamp": "2026-10-18 08:50:00"
}
```

**渠道商应答**

```http theme={"system"}
HTTP/1.1 200 OK
Content-Type: application/json

{"code":"SUCCESS","message":"成功"}
```

> [!NOTE]
>
> 通知地址 `back_url` 必须为 HTTPS 且长期可达；收到通知后建议先落库，再返回成功应答（HTTP 200 且 body 含 `code=SUCCESS`），避免处理失败导致平台重试产生重复业务。


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