服务端发奖

玩家在 App Store / Google Play 完成** 一次性内购 **后，Zeus 会主动调用你的发货接口。游戏后端需要验签、发货逻辑

对接前准备

向 我方运营索取 / 确认：

项	说明
发货回调 URL	游戏提供一个公网 HTTP地址，运营配进控制台
event_secret	签名密钥，创建应用时由我方提供，用于验签

同时确认该应用已开启 SDK，且发奖方式为 S2S（由我方运营在控制台完成）。

对接步骤

第 1 步：提供发货地址

部署一个 POST 接口，例如：

https://your-game.com/api/zeus/iap-reward

把该 URL 交给我方运营配置。之后所有成功的一次性内购都会打到这个地址。

第 2 步：接收请求

项	约定
Method	POST
Content-Type	application/json; charset=utf-8
成功响应	HTTP 200（仅认 200，其它状态码都会重试）
响应 Body	可空

示例请求：

{
  "order": {
    "order_id": "ord_xxx",
    "order_type": "purchase",
    "app_id": 20001,
    "package_name": "com.example.game",
    "os": "ios",
    "cash": "appstore",
    "cp_user_id": "player_1",
    "sku_id": "gems_100",
    "is_subscription": false,
    "status": "paid",
    "is_sandbox": false,
    "transaction_id": "1000000123456789",
    "original_transaction_id": "1000000123456789",
    "price": 19900,
    "currency": "USD",
    "metadata": "",
    "paid_at": "2026-09-21T01:00:00Z",
    "user_id": 0,
    "created_at": "2026-09-21T00:59:00Z",
    "updated_at": "2026-09-21T01:00:00Z"
  },
  "timestamp": 1725537600,
  "sign": "2f64171366cba1a6485decbdf2d5068d",
  "sent_at": "2026-09-21T01:00:00Z"
}

第 3 步：验签

按下面规则拼接待签名字符串（字段顺序固定，值原文拼接，不做 URL encode）：

app_id={order.app_id}&cash={order.cash}&sku_id={order.sku_id}&transaction_id={order.transaction_id}&original_transaction_id={order.original_transaction_id}&price={order.price}&currency={order.currency}&timestamp={timestamp}&event_secret={event_secret}

计算：

sign = MD5(待签名字符串)   // 小写十六进制

与请求体中的 sign 比对，不一致则返回非 200。

注意：

• 用请求体里的 timestamp，不要用 sent_at
• event_secret 只参与计算，不会出现在 JSON 里

验签示例

待签名串：

app_id=20001&cash=v5pay&sku_id=sku_paid_week&transaction_id=v5pay_tx_xxx&original_transaction_id=v5pay_tx_orig&price=19900&currency=BRL&timestamp=1725537600&event_secret=aabbccddeeff00112233445566778899

结果：

sign = 2f64171366cba1a6485decbdf2d5068d

第 4 步：幂等发货

用 transaction_id（推荐）或 order_id 判断是否已发过：

1. **已发过 ** 直接返回 200（不要当失败）

2. 未发过→ 按 sku_id 给 user_id 对应玩家发货，成功后返回 200

3. 业务失败 → 返回 4xx / 5xx，我方后端会重试

同一笔订单可能因网络重试或运营补发被推送多次，必须幂等。

第 5 步：联调验收

1. 配置好回调 URL 与密钥
2. 用沙箱账号完成一笔一次性内购
3. 确认你的接口收到请求、验签通过、道具到账
4. 故意返回非 200，确认会重试；再返回 200，确认补发成功

字段说明

顶层

字段	类型	说明
order	object	订单信息
timestamp	int64	Unix 秒（UTC），参与签名
sign	string	签名
sent_at	string	发送时间（RFC3339），不参与签名

订单

字段	类型	说明
order_id	string	Zeus 订单号
app_id	int64	应用 ID
sku_id	string	商品 ID，发什么
transaction_id	string	商店交易号，幂等键
original_transaction_id	string	原始交易号
price	int64	金额，单位厘（1 元 = 1000）
currency	string	币种，如 USD
os	string	ios / android
cash	string	appstore / googleplay
package_name	string	包名
is_sandbox	bool	是否沙箱单
is_subscription	bool	是否订阅（一次性内购一般为 false）
status	string	推送时订单状态，多为 paid
metadata	string	创单时透传的业务数据
paid_at	string | null	支付时间（RFC3339）
order_type	string	purchase
user_id	int64	Zeus 用户 ID
created_at	string	创建时间（RFC3339）
updated_at	string	更新时间（RFC3339

发货请以 transaction_id / order_id 为准，不要只依赖 status。

重试与超时

项	说明
单次超时	15 秒
失败重试	间隔 1s → 5s → 10s，最多共 4 次请求
成功条件	仅 HTTP 200

接口请尽快返回；发货逻辑尽量在返回前完成，或先落库再异步处理，但必须保证幂等。

对接检查清单

• [ ] 已提供 HTTPS 发货 URL，运营已配置
• [ ] 已拿到 event_secret
• [ ] 验签通过
• [ ] 按 transaction_id 幂等
• [ ] 发货成功返回 200
• [ ] 沙箱购买联调通过