GAME SERVER PAYMENT REPORTING
下载 AAR、完整接入协议、三种引擎说明和服务端签名示例 →
游戏服务端支付结果回传 v1
游戏方负责支付、验单及发货,衢付通记录已核实的成功支付。游戏直接提交自己的订单,无需衢付通预建订单;APK 无需接入另一套收银台。
地址与凭证
POST https://sdk.qufutong.com/api/v1/game-payments/{game_id}
平台为每个游戏独立签发 HMAC 密钥,安全交给游戏后端,不能放进 AAR、APK 或网页。平台管理员调用 POST /api/v1/games/{game_id}/payment-key,或已审核的游戏所属客户调用 POST /api/v1/customer/games/{game_id}/payment-key,使用相应服务端 Bearer 会话认证。返回 game_id、secret、endpoint、algorithm。每次调用都会更换该游戏密钥,旧密钥立即失效,不要在每笔支付前调用。
请求字段
Content-Type:application/json,请求体最多 16 KiB。提交以下字段:
| 字段 | 类型 | 含义 |
|---|---|---|
| game_id | string | 平台登记游戏 ID,与 URL 一致 |
| game_order_id | string | 游戏方稳定订单号,同游戏内唯一 |
| provider、provider_trade_id | string | 支付来源及游戏已验单的流水号 |
| task_id | string | 生成渠道包的打包任务 ID,由平台提供发行映射 |
| channel_code、package_id | string | 渠道及平台分包 ID,APK 可通过 getChannelCode/getPackageId 读取 |
| player_id | string | 游戏后端确认的玩家 ID,与事件统计一致 |
| server_id、role_id | string | 支付对应区服及角色 |
| product_id、product_name | string | 商品 ID、名称 |
| amount_cents | integer | 实付金额,以分为单位,1–1,000,000,000,000 |
| currency | string | 本轮支持 CNY、USD;其他货币不在本轮范围 |
| status | string | 固定 paid,本版只接收支付成功记录 |
| paid_at | string | 实际支付时间,RFC3339,带时区,重试时保持原值 |
| is_test | boolean | 测试充值 true,正式充值 false,分开统计 |
game_id、game_order_id、provider、task_id、channel_code、package_id 为 1–128 个英文字母、数字、下划线或连字符。其余字符串非空、最多 256 个 UTF-8 字节。paid_at 为 2000 年起且不能超过当前服务器时间 5 分钟。不提交 received_at,服务器自动生成接收时间。
平台核对游戏、渠道、所属客户和任务已签名验签的成功产物。游戏后端应从可信发行映射核验客户端提供的渠道/分包,不能直接相信客户端自报。真实支付验单责任在游戏方。
{
"game_id": "your-game",
"game_order_id": "game-order-10001",
"provider": "gamepay",
"provider_trade_id": "trade-10001",
"task_id": "pt-issued-task",
"channel_code": "android-test-a",
"package_id": "pkg-issued-package",
"player_id": "player-1001",
"server_id": "server-1",
"role_id": "role-1001",
"product_id": "gold-990",
"product_name": "金币礼包",
"amount_cents": 990,
"currency": "CNY",
"status": "paid",
"paid_at": "2026-11-16T18:00:00+08:00",
"is_test": true
}
签名和重试
请求头 X-Qufutong-Timestamp 为当前 Unix 秒时间戳,允许前后 300 秒误差。X-Qufutong-Payment-Signature 为 HMAC-SHA256 十六进制小写字符串,可带 sha256= 前缀。
签名内容是以下表达式的 UTF-8 字节,LF 换行,末尾不加换行:
timestamp + "\nPOST\n/api/v1/game-payments/your-game\n" + raw_json_body
密钥用 secret 字符串本身的 UTF-8 字节,不做十六进制解码。签名后原样发送 JSON 字节,不要再次序列化。URL 不带查询参数。重试时使用新时间戳重新签名,订单所有字段及 paid_at 保持原值。
包内 sample/report-payment.cjs 是游戏服务端参考示例,需 Node.js 18+。通过受限环境配置 QUFUTONG_GAME_PAYMENT_SECRET,将上述 JSON 保存到私有 payment.json 后执行 node sample/report-payment.cjs payment.json。该命令会提交记录,请用测试游戏、实际发行映射和 is_test=true;不要在 APK 中运行。
| HTTP | 处理 |
|---|---|
| 201 | 已持久保存,返回 payment、duplicate:false |
| 200 | 相同订单已保存,返回原 payment、duplicate:true |
| 400/413/422 | 格式、字段或发行归属错误,修正后重报 |
| 401 | 签名/时间戳错误,核对密钥和时钟 |
| 409 | 已有订单/流水的字段冲突,人工核对,不能自动覆盖金额或玩家 |
| 503/网络超时 | 保留游戏后端待发记录,指数退避重试,建议 2、4、8 秒起,最长 5 分钟间隔 |
只有 HTTP 200/201 且 JSON 中包含 payment 才算平台确认。响应丢失可安全重试。确认只代表记录,平台不负责发货。不同金额、角色、渠道或测试标记不能覆盖原订单。
查询和统计
管理员使用 GET /api/v1/analytics/payments,所属客户使用 GET /api/v1/customer/analytics/payments,需要相应 Bearer 会话。参数 game_id 必填,date 为 YYYY-MM-DD、默认北京时间今天;channel_code、package_id 可选;is_test 默认 false;limit 为 1–200、默认 50;offset 默认 0。返回 summary、groups、orders、total、limit、offset。客户网页提供相同筛选和分页明细。
日期按 paid_at 转为北京时间,迟到回传计入支付当天。不同币种分别汇总,不换汇。付费人数按同一游戏 player_id 去重,分渠道/分包人数不能相加当作游戏总人数。金额为成功充值总额,未扣退款,不是净收入或结算金额。测试数据仅在 is_test=true 查询中出现。
配置与边界
QUFUTONG_PAYMENTS_FILE 使用受限绝对路径,默认 data/game-payments.json。记录和密钥以 0600 文件保存,临时文件 fsync 后原子替换;保存失败不返回成功,损坏文件不会自动覆盖。只支持单 API 进程、最多 100,000 条;多实例共享文件不支持。备份须限制访问权限。
旧 /api/v1/orders 和 /payment-callbacks/{provider} 保留兼容,仍为旧流程且不合并进本报表;新游戏使用本协议。退款、冲正、失败订单轨迹和结算不在本轮范围。
分包后平台提供 task_id/channel_code/package_id 映射。验收需覆盖有效上报、重试去重、冲突拒绝、伪造包拒绝、跨游戏验签拒绝、重启恢复、日期与分包统计、测试/正式数据隔离。真实游戏充值和实际线上状态以专项验收记录为准。