衢付通开发者中心控制台 ↗

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_idstring平台登记游戏 ID,与 URL 一致
game_order_idstring游戏方稳定订单号,同游戏内唯一
provider、provider_trade_idstring支付来源及游戏已验单的流水号
task_idstring生成渠道包的打包任务 ID,由平台提供发行映射
channel_code、package_idstring渠道及平台分包 ID,APK 可通过 getChannelCode/getPackageId 读取
player_idstring游戏后端确认的玩家 ID,与事件统计一致
server_id、role_idstring支付对应区服及角色
product_id、product_namestring商品 ID、名称
amount_centsinteger实付金额,以分为单位,1–1,000,000,000,000
currencystring本轮支持 CNY、USD;其他货币不在本轮范围
statusstring固定 paid,本版只接收支付成功记录
paid_atstring实际支付时间,RFC3339,带时区,重试时保持原值
is_testboolean测试充值 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 映射。验收需覆盖有效上报、重试去重、冲突拒绝、伪造包拒绝、跨游戏验签拒绝、重启恢复、日期与分包统计、测试/正式数据隔离。真实游戏充值和实际线上状态以专项验收记录为准。