包网回调联调重点清单

本文档是 Hub 调用包网回调接口时的唯一联调标准，适用于：

• POST /api/v1/callback/balance
• POST /api/v1/callback/offline
• POST /api/v1/callback/bet-push

环境地址

环境	Base URL
生产环境	https://hub-panel-api.v7stech.com
测试环境	https://hub-panel-api-dev.v7stech.com

1. 所有回调必须验证 Authorization

Authorization: Bearer {agent_api_key}.{timestamp}.{header_signature}

header_signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret)

• 使用小写 hex。
• agent_api_key 只能使用该 Agent 自己对应的 agent_api_secret 验证；不能轮询或尝试多组 Secret。
• Header 缺失、格式不正确、Key/Secret 不匹配、签名错误或 timestamp 过期，必须直接拒绝。

2. Header 与 Body timestamp 必须相同

Authorization timestamp == JSON Body timestamp

两个 timestamp 均为秒级 Unix 时间戳。不得由两次独立取时生成；不一致必须拒绝请求。

3. Body sign 规则

接口	Body sign 待签名内容
/callback/balance	username + "." + timestamp
/callback/offline（含 launch_failed）	username + "." + timestamp
/callback/bet-push	agent_api_key + "." + timestamp

全部使用：

HMAC-SHA256(raw_string, agent_api_secret) → 小写 hex

4. session_id 和游戏启动

• 游戏启动成功必须同时满足：code == 0、game_url 非空、session_id 已确认。
• session_id 为启动响应的独立字段，不要求拼接进 game_url。
• 包网收到 /balance 时应原样保存 session_id，状态仅为 launch_pending，不能当作 enter_game。
• 余额请求的唯一定位优先使用 session_id + game_id；由已同步游戏目录的 game_id 反查 brand_guid。provider 仅作辅助核对，不可单独定位 Brand。
• 保存 Hub 下发的 brand_guid、brand_code、brand_name 快照；GUID 用于关联，Code/Name 仅显示，不得合并不同 GUID 的 Brand。
• 相同 Agent、玩家、币种、session_id 必须有唯一约束，防止并发重复建立启动记录。

5. 启动失败补偿

如果 /balance 已成功、但游戏商启动失败，Hub 会调用 /callback/offline：

{
  "username": "player001",
  "currency": "MYR",
  "session_id": "vct-session-uuid-001",
  "reclaimed_amount": 100.00,
  "action": "launch_failed",
  "timestamp": 1783324700,
  "sign": "<HMAC-SHA256(username.timestamp, agent_api_secret)>"
}

• 必须使用原始 session_id。
• launch_failed 只释放该启动的临时会话、余额锁或 pending 记录。
• 不得记录 enter_game，不得进入正常退出的 offline 平账流程。
• 同一 launch_failed 重复送达必须幂等：不能重复加款、重复解锁或重复建立记录。

6. 正常 offline 与 bet-push

• exit_game、api_kick_exit、switch_game 走正常 offline 关会话与对账；switch_game 的 reclaimed_amount 是该币种所有 Provider 钱包的汇总；不得据此重复变更主钱包。
• 在 Seamless 模式下，bet-push 是实时资金接口：BET 扣款、SETTLED / BONUS 加款，CANCEL / ROLLBACK / REFUND / VOID 对原交易幂等冲正。

7. 推荐处理顺序

校验 Authorization
→ 校验 Header/Body timestamp 一致
→ 校验 Body sign
→ 按 session_id 查找或建立幂等记录
→ 执行业务逻辑
→ 返回 HTTP 2xx + {"status":"success"}