查询订单状态
本接口为回调接口,由 APP 服务端实现并提供给 SUD 调用,SUD 将通过此接口查询 APP 服务端的订单状态。
接口说明
接口英文名 pay.orderQuery
功能描述 查询订单状态。SUD OP SVR 通过此回调接口向 APP 服务端查询指定订单的支付状态及详情。
注意:本接口强制要求服务通信二次加密和签名:回调请求必须验签通过后才能处理业务,可有效防止数据篡改与泄露。
调用方式
HTTPS 调用
http
POST <APP 自定义回调地址>请求参数 - Body
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| sud_trade_no | string | 是 | SUD 业务订单号 |
返回值
返回的 JSON 数据包
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 错误码 |
| errmsg | string | 错误信息 |
| env | number | 环境配置 0-正式环境, 1-测试环境 |
| game_id | string | 游戏id |
| user_id | string | 下单用户id |
| sud_trade_no | string | SUD 业务订单号 |
| product_id | string | 商品id |
| product_name | string | 商品名称 |
| quantity | number | 购买数量 |
| unit_price | number | 商品单价(分) |
| currency | string | 币种: CNY |
| status | string | 状态,枚举类: PAYING-支付中,PAID-支付成功,CLOSED-已关闭,REFUND-转入退款。返回订单当前整体状态,可能落在支付或退款任一阶段 |
| pay_type | number | 支付方式:1-微信支付,2-支付宝,3-apple支付 |
| transaction_id | string | 第三方支付交易号(微信/支付宝等流水号) |
| attach | string | 透传数据 |
调用示例
说明:以下请求示例为解密后的业务数据,实际收到的是密文并携带签名请求头,须先验签、解密后再按此结构解析;返回示例为加密前的业务数据,实际返回须先加密、再对密文签名。完整规范见回调签名加密。
请求数据示例
json
{
"sud_trade_no": "sud_20231024123456"
}返回数据示例
json
{
"errcode": 0,
"errmsg": "ok",
"env": 0,
"game_id": "game_1001",
"user_id": "user_293847",
"sud_trade_no": "sud_20231024123456",
"product_id": "item_001",
"product_name": "100金币",
"quantity": 1,
"unit_price": 600,
"currency": "CNY",
"status": "PAID",
"pay_type": 1,
"transaction_id": "420000123420231024567890",
"attach": "custom_passthrough_data"
}轮询策略
SUD OP SVR 在订单创建后按以下间隔依次轮询本接口,作为兜底手段获取支付结果:
| 项 | 要求 |
|---|---|
| 轮询间隔(秒) | 5, 30, 60, 180, 300, 600, 1800 |
| 终止条件 | 返回 PAID、CLOSED 或 REFUND(订单已转入退款)后停止轮询 |
| 查询方式 | POST 请求,仅携带 sud_trade_no,只读、无副作用,可重复调用 |
APP SVR 需注意:
- 本接口为只读查询,同一
sud_trade_no的重复调用应返回一致结果,不得因轮询触发发货、扣款等业务动作。 - 已返回终态(
PAID、CLOSED、REFUND)后,后续查询应稳定返回同一终态,不得回退到PAYING,否则会拖长 SUD OP 的轮询与关单判定。 - 若用户已拉起收银台但尚未完成支付,返回
PAYING,不要返回空响应或错误码。
