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

# 支付结果通知接口

## 功能说明

聚合支付订单支付完成后，平台向下单时传入的 `notify_url` 异步推送支付结果通知。商户接收到通知后需返回 HTTP `200`，否则平台将按照重试计划多次重发通知。

通知请求携带与开放平台一致的 **HmacSHA256 签名**请求头，商户可据此验证通知来源的真实性。

## 请求地址

`POST <下单时传入的 notify_url>`

## 请求头

通知请求携带以下签名头，验签方式与[签名验签说明](/open/spec/signature)一致：

| Header           | 必填 | 说明                      |
| ---------------- | -- | ----------------------- |
| `Content-Type`   | 是  | 固定 `application/json`   |
| `Client-Id`      | 是  | 商户的 `app_key`           |
| `Signature-Type` | 是  | 固定 `HmacSHA256`         |
| `Timestamp`      | 是  | 秒级时间戳                   |
| `Nonce-Str`      | 是  | 32 位随机字符串               |
| `Signature`      | 是  | HMAC-SHA256 签名值（hex 编码） |

**签名原文**按以下格式拼接（每行以 `\n` 结尾）：

```
POST\n
<notify_url 完整地址>\n
<app_key>\n
HmacSHA256\n
<Timestamp>\n
<Nonce-Str>\n
<请求体 JSON 原文>\n
```

签名算法：`Signature = hex( HMAC_SHA256( app_secret, 签名原文 ) )`

## 请求参数

| 字段                  | 类型     | 必填 | 说明                                                                                            |
| ------------------- | ------ | -- | --------------------------------------------------------------------------------------------- |
| `merchant_code`     | string | 是  | 商户编码                                                                                          |
| `out_trade_no`      | string | 是  | 商户订单号                                                                                         |
| `platform_trade_no` | string | 是  | 平台流水号                                                                                         |
| `amount`            | int    | 是  | 订单金额，单位：分                                                                                     |
| `trade_state`       | string | 是  | 交易状态，`00` 表示支付成功，详见 [TradeState 枚举](/open/xianghe/aggregate-payment-v1/get-charge#tradestate) |
| `trade_state_desc`  | string | 是  | 交易状态描述                                                                                        |
| `channel_code`      | string | 是  | 支付渠道编码，如 `WECHAT`、`ALIPAY`、`UNIONPAY`                                                         |
| `institution_code`  | string | 是  | 机构编码，如 `YEEPAY`                                                                               |
| `institution_name`  | string | 是  | 机构名称，如 `易宝`                                                                                   |
| `trade_no`          | string | 是  | 微信、支付宝等三方支付流水号                                                                                |
| `payed_at`          | string | 否  | 支付时间，格式：`yyyyMMddHHmmss`；示例值：`20220912111230`                                                 |

## 请求示例

```json theme={null}
{
  "merchant_code": "226801000000865319122",
  "out_trade_no": "ea51203e1a0146d7954b39ac88aecaf7",
  "platform_trade_no": "20231025152300000001",
  "amount": 100,
  "trade_state": "00",
  "trade_state_desc": "成功",
  "channel_code": "WECHAT",
  "institution_code": "WECHAT",
  "institution_name": "财付通",
  "trade_no": "4200001234202310251234567890",
  "payed_at": "20231025152300"
}
```

## 响应说明

商户接收通知成功后需返回 HTTP 状态码 `200`，平台不再重发该通知。

<Note>
  如果平台未收到 HTTP `200` 响应，将按重试计划重新发送通知。商户应基于 `out_trade_no` 做幂等处理，避免重复记账。
</Note>

## 重试策略

通知失败后，平台将按以下间隔自动重试，最多重试 **15 次**：

| 重试次数   | 间隔    |
| ------ | ----- |
| 第 1 次  | 15 秒  |
| 第 2 次  | 15 秒  |
| 第 3 次  | 30 秒  |
| 第 4 次  | 3 分钟  |
| 第 5 次  | 10 分钟 |
| 第 6 次  | 20 分钟 |
| 第 7 次  | 30 分钟 |
| 第 8 次  | 30 分钟 |
| 第 9 次  | 30 分钟 |
| 第 10 次 | 60 分钟 |
| 第 11 次 | 3 小时  |
| 第 12 次 | 3 小时  |
| 第 13 次 | 3 小时  |
| 第 14 次 | 6 小时  |
| 第 15 次 | 6 小时  |

<Info>
  超过最大重试次数后不再自动发送。如仍未收到成功响应，商户可通过[查询交易接口](/open/xianghe/aggregate-payment-v1/get-charge)主动查询订单状态。
</Info>

## 商户处理建议

1. **验签**：收到通知后，使用 `app_secret` 按上述签名原文格式计算签名，与请求头 `Signature` 比对，确认通知来源可信；
2. **幂等处理**：以 `out_trade_no` 或 `platform_trade_no` 为去重依据，同一通知可能多次送达，仅首次处理即可；
3. **及时应答**：处理完成后返回 HTTP `200`，避免不必要的重试；
4. **主动查询兜底**：若长时间未收到通知或重试全部耗尽，调用查询交易接口确认订单最终状态。