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

## 请求头

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

| 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 枚举](https://opendocs.xft.xin/open/payment/aggregate-payment-v1/get-charge.md#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={"system"}
{
  "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` 做幂等处理，避免重复记账。

## 重试策略

通知失败后，平台将按以下间隔自动重试，最多重试 **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 小时 |

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

## 商户处理建议

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


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