回调通知服务说明

更新说明

20260901

第一版

前提条件

接入方需要准备：

回调地址：在 个人中心 - API 管理 中填写。平台在订单状态变化时向该地址 POST JSON。

app-secret：用于验签，在 API 管理中查看。

IP 白名单（可选）：如果您的服务设置了白名单访问，您需要设置47.107.82.181（回调服务ip）到白名单。

未配置回调地址的账号不会收到推送。

通知机制

请求方式 POST，Content-Type: application/json。

您收到消息并处理完成后，请将 HTTP 响应 Body 原样返回字符串 success（不能带引号、空格或 JSON）。未返回 success 将视为失败。

失败后按以下间隔重试，最多 5 次，之后不再推送：

次数	间隔
第 1 次	1 分钟
第 2 次	2 分钟
第 3 次	5 分钟
第 4 次	10 分钟
第 5 次	30 分钟

请保证回调接口幂等：同一 orderId + status + type 可能重复到达。

当前推送场景

出售订单状态变化时，向卖家回调地址推送（type = 1，typeName = SELLER_ORDER_STATUS）：

有人购买了您的商品，支付成功（待发货）

有人购买了您的商品，订单完成

有人购买了您的商品，订单取消

有人购买了您的商品，订单退款

触发推送的 status：1 待发货、3 已完成、4 已取消、5 已退款。

验签说明

消息体中带 sign 字段，用于确认通知来自平台。规则与接入指南中的请求加签一致：

排除 sign，其余字段都参与。

按参数名 ASCII 从小到大排序，拼成 key=value&key=value。

末尾追加 &sign={app_secret}。

MD5 得到 32 位大写，与消息中的 sign 比较（建议忽略大小写）。

示例报文

{
  "orderId": 10001,
  "status": 1,
  "tradeOfferId": "1232112",
  "sign": "37C1FC112D0AE6A53144EEA6A1334A50",
  "type": 1,
  "typeName": "SELLER_ORDER_STATUS"
}

若 tradeOfferId 为空字符串，按实际值参与签名（空字符串就是空，不是 null）。

假设字段均有值时，待签名字符串形如：

orderId=10001&status=1&tradeOfferId=1232112&type=1&typeName=SELLER_ORDER_STATUS&sign={你的app_secret}

通知字段说明

字段	类型	说明
orderId	int	平台订单 ID
status	int	订单状态：`1` 待发货（购买成功）`2` 结算中 `3` 已完成 `4` 已取消 `5` 已退款
tradeOfferId	string	Steam 报价 ID，未发送报价时可能为空
sign	string	签名，32 位大写 MD5
type	int	`0` 买家订单回调 `1` 卖家订单回调
typeName	string	`BUYER_ORDER_STATUS` / `SELLER_ORDER_STATUS`


## 接收示例

请保证接口对 POST JSON 可访问，成功处理时只返回：

```text
success

更新说明#

20260901#

前提条件#

通知机制#

当前推送场景#

验签说明#

示例报文#

通知字段说明#