GaaPay 接入文档

GaaPay 是面向站群的虚拟币收款基础设施。你创建一个订单，用户在我们的收银台完成链上转账，我们负责监听、确认、入账、分账与对账，并通过签名 Webhook 通知你发货。

5 分钟接入

1. 控制台 → 应用与密钥 → 创建应用，拿到 AppID 与 sk_test_… 密钥（仅显示一次）。
2. 服务端调用 POST /api/v1/orders 创建订单，拿到 checkout_url。
3. 把用户重定向到 checkout_url，或把链接直接发给用户。
4. 接收 Webhook payment.succeeded，验签通过后再发货。

# 1) 下单（签名见下一节）
curl -X POST https://api.gaapay.com/api/v1/orders \
  -H "content-type: application/json" \
  -H "x-gaapay-app: app_xxx" \
  -H "x-gaapay-timestamp: 1792596770" \
  -H "x-gaapay-nonce: 3f1c9a2e" \
  -H "x-gaapay-signature: 9d1f…" \
  -d '{"amount":"19.90","merchant_order_ref":"order_20261021_001","description":"至尊月卡 · 30 天"}'

# 2) 响应
{
  "object": "order",
  "id": "ord_01m5f…",
  "short_code": "GP-20261021-8F3A2C",
  "status": "QUOTED",
  "amount": 19.9,
  "checkout_url": "https://checkout.gaapay.com/pay/VCCC…",
  "expires_at": "2026-10-21T14:46:56.632Z"
}

核心概念

理解三个模型，你就能理解整套系统为什么这样设计。

• Order（订单）：商户视角的一笔交易，只有金额、商品、回调，不含任何链与币。
• PaymentIntent（支付意图）：「这笔钱要收 19.90 USD」。用户可能先选 Base 失败再换 Tron，这是同一个意图的两次尝试。
• PaymentAttempt（支付尝试）：一次具体的渠道执行，持有链、资产、收款地址、报价快照与确认要求。换一种支付方式 = 新建一个 Attempt，旧 Attempt 的地址继续监听 72 小时。

这样设计的好处：新增链或渠道不会改动订单与账本；用户切换支付方式不会产生两笔订单，对账不会混乱。

鉴权与签名

所有商户 API 请求都必须携带四个头。签名原文按行拼接，顺序不可变：

payload = timestamp + "\n" + nonce + "\n" + METHOD + "\n" + path + "\n" + raw_body
signature = hex( HMAC_SHA256(app_secret, payload) )

• timestamp：Unix 秒。偏差超过 5 分钟拒绝。
• nonce：每次请求唯一。服务端滑动窗口去重，重复即拒绝（防重放）。
• path：包含查询串的路径，例如 /api/v1/orders?limit=20。
• raw_body：原始请求体字符串（GET 为空串）。不要重新序列化后再签名。

// Node.js
import { createHmac, randomUUID } from 'node:crypto';

function signedFetch(path, body) {
  const ts = Math.floor(Date.now() / 1000);
  const nonce = randomUUID();
  const raw = body ? JSON.stringify(body) : '';
  const sig = createHmac('sha256', process.env.GAAPAY_SECRET)
    .update([ts, nonce, body ? 'POST' : 'GET', path, raw].join('\n'))
    .digest('hex');
  return fetch(`https://api.gaapay.com${path}`, {
    method: body ? 'POST' : 'GET',
    headers: {
      'content-type': 'application/json',
      'x-gaapay-app': process.env.GAAPAY_APP,
      'x-gaapay-timestamp': String(ts),
      'x-gaapay-nonce': nonce,
      'x-gaapay-signature': sig,
    },
    body: raw || undefined,
  });
}

# Python
import hmac, hashlib, time, uuid, json

def sign(method, path, body: str, secret: str):
    ts, nonce = str(int(time.time())), str(uuid.uuid4())
    payload = f"{ts}\n{nonce}\n{method}\n{path}\n{body}"
    sig = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    return {"x-gaapay-timestamp": ts, "x-gaapay-nonce": nonce, "x-gaapay-signature": sig}

<?php
$ts = time(); $nonce = bin2hex(random_bytes(8)); $raw = json_encode($body);
$payload = $ts."\n".$nonce."\nPOST\n".$path."\n".$raw;
$sig = hash_hmac('sha256', $payload, $secret);
// headers: x-gaapay-app / x-gaapay-timestamp / x-gaapay-nonce / x-gaapay-signature

零代码接入（L0 / L1）

没有后端也能收款：控制台生成收款链接，打开即进入收银台。适合静态站、活动页、社群直发、客服手动开单。

创建订单

POST /api/v1/orders

查询 / 取消 / 退款

错误码

所有错误响应都带 request_id。提工单时提供它即可精确定位到那一次调用。

事件目录

验签实现（必须做）

签名串为 timestamp + "." + body，算法 HMAC-SHA256，头信息：

x-gaapay-event: payment.succeeded
x-gaapay-event-id: evt_01m5f…
x-gaapay-timestamp: 1792596770
x-gaapay-signature: v1=9d1f…
x-gaapay-delivery: 1

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyGaaPayWebhook({ secret, timestamp, body, signature }) {
  // 防重放：时间戳偏差超过 5 分钟直接拒绝
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || '');
  return a.length === b.length && timingSafeEqual(a, b);
}

重试与死信

非 2xx 或 10 秒超时即视为失败，按指数退避重试：10s → 30s → 2m → 10m → 1h → 6h → 24h（共 7 次，跨度约 32 小时）。全部失败进入死信队列，控制台可手动重投。

不保证顺序。请以事件中的状态与版本为准，而不是到达顺序；重复投递携带相同 event_id。

对账 · 结算 · 分账

对账

每天 UTC 00:00 日切。两条独立口径：链上事实重新累加 vs 账本分录直接求和。差异分级：漏单/多记/金额差为 P0（自动冻结出款），悬账为 P1，状态差 P2，跨日时间差 P3 自动消解。

结算

站群内部划转全部在账本内完成，不产生任何链上交易：T+0/T+1/T+3 可配，pending → available 只是一条分录，零 Gas、即时、不会失败。只有当资金需要离开 GaaPay 体系时才上链。

分账

求值顺序：固定金额 → 固定比例 → 阶梯比例 → 剩余分配（residual）。每条规则必须且只能有一个 residual 方承接尾差；各方之和必须严格等于净额，否则拒绝执行并告警。

安全实践清单

• 密钥只存服务端，绝不进前端代码、不进 Git、不进日志；使用环境变量或 KMS。
• 生产密钥与测试密钥前缀不同（sk_live_ / sk_test_），肉眼可辨。
• 开启 IP 白名单；商户 API 只接受你的服务器调用，浏览器永不直连。
• 发货逻辑必须在验签之后；金额与订单号必须与本地订单交叉校验。
• 建议同时轮询查单接口作为 Webhook 的兜底。
• 退款只退原地址；不要接受用户指定的新地址（超额支付诈骗的标准手法）。

服务条款（摘要）

GaaPay 提供的是软件与监控服务：地址派生、链上监听、确认、记账、通知、对账与报表。GaaPay 不保管、不代付、不划转商户资金；自托管模式下资金直达商户登记的收款地址，私钥由商户自行持有并承担其业务的合规责任。

商户对其业务的合法性、商品交付、税务与用户协议独立负责。加密资产转账不可撤销，商户应在发货前完成自身风控判断。

本段为摘要。具有约束力的完整文本见 《服务条款》，两者不一致时以完整文本为准。

隐私政策（摘要）

我们只采集完成支付所必需的数据：商户标识、订单号、金额、币种、链、地址、交易哈希、时间戳与状态。我们不采集玩家姓名、邮箱、手机号、证件或支付卡信息，也不做设备指纹画像。数据库中不含可识别个人身份的信息集合。

完整的数据类别、处理基础、保存期限与跨境传输说明见 《隐私政策》。

退款政策（摘要）

加密支付无拒付（chargeback），退款需由商户主动发起并承担链上 Gas。退款只退回原付款地址；若原地址不可用，资金退回商户待结算余额，由商户自行与其用户协商。退款审批遵循发起人 ≠ 审批人的四眼原则。

少付/多付/错链的自动化分流规则与争议举证流程见 《退款与争议处理政策》。