支付回调

本接口为回调接口，由 Game SVR 实现并在 SUD OP 后台配置回调地址，SUD OP SVR 在支付或退款状态变化时调用此接口，通知 Game SVR 处理发货或退款结果。

接口说明

接口英文名 pay.notify

功能描述 支付回调。SUD OP SVR 主动调用 Game SVR 配置的回调地址，通知 Game SVR 处理道具发货或退款结果。

注意：本接口强制要求服务通信二次加密和签名：回调请求必须验签并解密后才能处理业务，可有效防止数据篡改与泄露。

接口信息

项	值
调用方	SUD OP SVR
提供方	Game SVR
触发时机	支付或退款状态变化时

调用方式

HTTPS 调用

POST <Game 自定义回调地址>

回调地址由 Game 在 SUD OP 后台配置，请使用 HTTPS 地址。

请求参数 - Body

属性	类型	默认值	必填	说明
id	string		是	回调通知 ID。全局唯一，SUD OP 重试时保持不变，Game SVR 应以该字段作为幂等键
create_time	number		是	回调通知创建时间（秒级时间戳）
event	string		是	事件类型，枚举值
payload	object		是	事件数据，不同事件类型对应不同的数据结构，详见下方说明

道具发货通知：pay_goods_deliver_notify

payload 字段说明：

属性	类型	默认值	必填	说明
env	number		是	环境配置 0-正式环境，1-沙箱环境
out_trade_no	string		是	业务订单号
sud_trade_no	string		是	SUD订单号
product_id	string		是	商品id
product_name	string		是	商品名称
quantity	number		是	购买数量
unit_price	number		是	商品单价（分）
attach	string		否	透传数据

请求示例：

{
  "id": "xxx",
  "create_time": 1745136000,
  "event": "pay_goods_deliver_notify",
  "payload": {
    "env": 0,
    "out_trade_no": "BIZ20250420001",
    "sud_trade_no": "SUD20250420001",
    "product_id": "product_001",
    "product_name": "金币礼包",
    "quantity": 1,
    "unit_price": 600,
    "attach": ""
  }
}

退款通知：pay_refund_notify

payload 字段说明：

属性	类型	默认值	必填	说明
env	number		是	环境配置 0-正式环境，1-沙箱环境
sud_refund_no	string		是	SUD退款单号
out_trade_no	string		是	退款对应的支付业务单号
sud_trade_no	string		是	退款对应的支付SUD单号
refund_amount	number		是	退款金额（分）
reason	string		否	退款原因

请求示例：

{
  "id": "xxx",
  "create_time": 1745136000,
  "event": "pay_refund_notify",
  "payload": {
    "env": 0,
    "out_trade_no": "BIZ20250420001",
    "sud_trade_no": "SUD20250420001",
    "sud_refund_no": "REF20250420001",
    "refund_amount": 600,
    "reason": "deliver pay products failed"
  }
}

返回值

返回的 JSON 数据包

属性	类型	说明
errcode	int32	错误码。0 表示 Game SVR 已成功处理本次通知（含已通过幂等判定的重复请求），SUD OP 不再重试；非 0 表示处理失败，SUD OP 将按下方"超时与重试"策略重试
errmsg	string	错误信息

返回数据示例

{
  "errcode": 0,
  "errmsg": "ok"
}

超时与重试

项	要求
Game 响应超时阈值	≤ 5 s
触发重试的条件	Game SVR 未在超时阈值内响应、返回非 200 HTTP 状态码、或返回非 0 errcode
总重试次数	最多 15 次
重试间隔（秒）	15, 15, 30, 180, 600, 1200, 1800, 1800, 1800, 3600, 10800, 10800, 10800, 21600, 21600（累计约 24 小时）

重试请求会保留与首次相同的顶层 id，Game SVR 必须以 id 做幂等判定，命中幂等时直接返回 errcode: 0 即可，不要重复发货或重复退款。

鉴权说明

SUD OP 调用本接口时，强制携带加密和签名信息，不存在明文回调模式。Game SVR 必须对请求进行验签和解密，以确认请求来源合法。验签失败应直接拒绝请求（返回非 200 HTTP 状态码），不要进入业务返回流程。具体的算法、请求头字段与错误码见服务端 API 签名加密。

注意事项

1. Game SVR 必须验签。验签失败应直接拒绝请求（返回非 200 HTTP 状态码），避免伪造请求触发发货或退款处理。
2. 幂等键：以顶层 id 为唯一幂等键。SUD OP 重试时 id 保持不变；同一笔订单的"发货通知"与"退款通知"会使用不同的 id，天然区分。
3. 业务层建议同时基于 out_trade_no / sud_trade_no / sud_refund_no 做订单状态校验，防止乱序到达（如退款先于发货回调到达）。
4. create_time 与服务器当前时间差超过 5 分钟的请求应直接拒绝，防止重放攻击。