加密货币收银台 · 对接文档

用户浏览器                  商户后端                    加密网关                  区块链
    |                         |                           |                         |
    | 选择加密货币支付        |                           |                         |
    |------------------------>|                           |                         |
    |                         | POST /api/v1/orders      |                         |
    |                         |  (api_key, uid, amount)  |                         |
    |                         |------------------------->|                         |
    |                         |                           | 派生 HD 地址           |
    |                         |                           | 写入订单表              |
    |                         |   { pay_url, addresses } |                         |
    |                         |<-------------------------|                         |
    |   302 redirect to pay_url                           |                         |
    |<----------------------  |                          |                         |
    |                                                     |                         |
    |   GET /pay/:id                                      |                         |
    |---------------------------------------------------->|                         |
    |                                                     | 302 to /cashier.html    |
    |<----------------------------------------------------|                         |
    |                                                     |                         |
    |   用户用钱包转 USDT                                 |                         |
    |---------------------------------------------------------------------------->|
    |                                                     |                         |
    |                                                     | 后台每分钟轮询链上      |
    |                                                     |<------------------------|
    |                                                     | 检测到到账              |
    |                                                     | 更新订单状态            |
    |                                       POST webhook (带签名)                   |
    |                         |<-------------------------|                         |
    |                         | 验签 + 加金币            |                         |
    |                         |------>200 OK            |                         |
    |                         |------------------------->|                         |

curl -X POST https://cryptocashier.shop/api/v1/orders \
  -H "Authorization: Bearer pk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "ORD-20260419-001",
    "uid": "USER_12345",
    "amount_usd": "9.99",
    "product": "100 金币",
    "return_url": "https://site.com/order/paid?id=ORD-20260419-001",
    "expires_min": 10
  }'

{
  "id":                "f6c8a97b-4569-4e92-a8fb-7f15b1c5a840",  // 我们的 UUID
  "merchant_order_id": "ORD-20260419-001",
  "uid":               "USER_12345",
  "amount_usd":        "9.99",
  "amount_received":   "0",                              // 当前已到账累计
  "status":            "pending",                        // pending|partial|paid|overpaid|expired|cancelled
  "currency":          null,                              // 到账后填充（USDT|USDC）
  "chain":             null,                              // 到账后填充（trc20|erc20|…）
  "product":           "100 金币",
  "return_url":        "https://site.com/order/paid?id=ORD-20260419-001",
  "pay_url":           "https://cryptocashier.shop/pay/f6c8...",   // 让用户浏览器打开这个
  "addresses": {
    "evm":  "0x9858effd232b4033e47d90003d41ec34ecaeda94",  // ETH / BSC / Arb / Polygon / Base / OP 共用
    "tron": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
    "sol":  "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk",
    "sol_ata": {                                              // Solana 每个代币的 ATA
      "USDT": "6pXYguUixhfdydHDMgsvSy3sAWjStL2eEYh4KeYJAUDk",
      "USDC": "5N3f1tj9v1vc5TUZ8S7mCAnVmjVKrfnzXWhxLaxyZAgt"
    }
  },
  "created_at":        1776613832602,                   // 毫秒时间戳
  "expires_at":        1776614432602,
  "updated_at":        1776613832602
}

curl https://cryptocashier.shop/api/v1/orders/f6c8a97b-4569-4e92-a8fb-7f15b1c5a840 \
  -H "Authorization: Bearer pk_YOUR_API_KEY"

{
  "event":             "paid",                    // paid|overpaid|partial|expired|forwarded
  "order_id":          "f6c8a97b-...",           // 我们的 UUID
  "merchant_order_id": "ORD-20260419-001",        // 你的订单 ID
  "uid":               "USER_12345",
  "amount_requested":  "9.99",                   // 订单请求金额（字符串）
  "amount_received":   "9.99",                   // 累计到账（字符串）
  "currency":          "USDT",                   // 最后一笔币种，USDT|USDC
  "chain":             "trc20",                  // 最后一笔所在链，见「支持的链」
  "fully_paid":        true,                    // 累计 ≥ 订单金额
  "overpaid":          false,                   // 累计 > 订单金额
  "underpaid":         false,                   // 累计 < 订单金额
  "latest_tx": {                                     // 触发本次回调的那笔 tx（expired 时为 null）
    "tx":       "0xabc...",
    "chain":    "trc20",
    "currency": "USDT",
    "from":     "TXxxxxxxxxxx",
    "amount":   "9.99"
  },
  "created_at":        1776613832602,            // 订单创建时间（毫秒）
  "expires_at":        1776614432602,            // 订单过期时间（毫秒）
  "ts":                1776613890123,            // 本次回调发送时间（毫秒），= X-Timestamp
  "nonce":             "a1b2c3d4e5f6..."          // 16 字节十六进制，= X-Nonce
}

{
  "event":              "forwarded",
  "forward_tx":         "0xabc123...",              // 归集 tx hash，用它去链上查
  "forward_from":       "0x175fa1...",              // 派生地址（钱的来源）
  "forwarded_to":       "0xb11272...",              // 你的提现地址（钱的去向）
  "forward_amount":     "0.1",                       // 人类可读金额
  "forward_amount_raw": "100000000000000000",        // 链上真实整数（BigInt 字符串）
  "forward_currency":   "USDT",
  "forward_chain":      "bsc",
  "token_contract":     "0x55d398326f99059ff775485246999027b3197955", // BSC USDT
  "token_decimals":     18,
  "explorer_url":       "https://bscscan.com/tx/0xabc123...",
  "forward_delay_ms":   45000,                      // paid → forwarded 的间隔
  "paid_ts":            1776850000000,
  "forwarded_ts":       1776850045000,
  "verify": {                                         // ← 自包含校验块
    "chain_type": "evm",
    "rpc":    "https://bsc-rpc.publicnode.com",
    "method": "eth_getTransactionReceipt",
    "params": ["0xabc123..."],
    "curl":   "curl -s -X POST ... -d '{...}'",
    "expect": {                                       // 所有字段必须全部匹配
      "result.status":                "0x1",
      "result.logs[i].address":       "0x55d398...",
      "result.logs[i].topics[0]":     "0xddf252ad...",
      "result.logs[i].topics[2]":     "0x00...b11272...",
      "BigInt(result.logs[i].data)": "100000000000000000"
    }
  }
}

const { verifyForwardOnChain } = require("./verify-forward.cjs");

// ═══════════════════════════════════════════════
// ← 改成你自己的提现地址。没用到的链可以删掉或留空字符串。
// ═══════════════════════════════════════════════
const MY_PAYOUTS = {
  bsc:     "0xYourEVMWallet",                 // 0x 开头 42 字符（大小写无关）
  erc20:   "0xYourEVMWallet",                 // Ethereum 主网
  arb:     "0xYourEVMWallet",                 // Arbitrum
  polygon: "0xYourEVMWallet",                 // Polygon
  base:    "0xYourEVMWallet",                 // Base
  op:      "0xYourEVMWallet",                 // Optimism
  trc20:   "TYourTRONWallet",                 // T 开头 34 字符 Base58
  sol:     "YourSolanaWalletBase58Address",   // 32-44 Base58，无前缀
};

// 在你的 webhook handler 里（已验过 HMAC 签名之后）：
if (payload.event === "forwarded") {
  const result = await verifyForwardOnChain({
    payload,                                  // 我们发给你的完整 JSON
    myPayouts: MY_PAYOUTS,                    // ← 按链自动匹配（推荐）
    expectedAmountRaw: order.expected_raw,    // ← 你订单上的应付金额（选填但推荐）
  });

  if (result.ok) {
    await markOrderVerified(order.id);        // 链上已确认 ✓
  } else {
    console.error("归集校验失败:", result.reason);
    await disableCryptoGateway();              // ← 立即禁用我方支付通道
    await alertOps(payload, result.reason);
  }
}

import express from "express";
import crypto  from "crypto";

const CALLBACK_SECRET = process.env.CALLBACK_SECRET; // 存在 env 里
const app = express();

// 必须用 raw body，否则 HMAC 算出的签名会因字节差异不一致
app.post("/api/crypto-webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const rawBody = req.body;                                      // Buffer
  const sig = req.headers["x-signature"];
  const ts  = Number(req.headers["x-timestamp"] || 0);

  // 1. 防重放：拒绝时间戳偏差 > 5 分钟的请求
  if (Math.abs(Date.now() - ts) > 5 * 60_000) return res.sendStatus(401);

  // 2. 验签：用 timingSafeEqual 防时序攻击
  const expected = crypto.createHmac("sha256", CALLBACK_SECRET)
    .update(rawBody).digest("hex");
  if (!sig || sig.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const p = JSON.parse(rawBody.toString());

  // 3. 幂等：按 merchant_order_id + nonce 去重（同一事件可能重复到达）
  const order = await findOrder(p.merchant_order_id);
  if (!order) return res.sendStatus(404);
  if (order.fulfilled) return res.json({ ok: true, dup: true });

  // 4. 分发：收到 paid/overpaid 就直接发货，不用等 forwarded
  if (p.event === "paid" || p.event === "overpaid") {
    // 注意：订单可能之前被标为 expired/cancelled（用户超时后才付款），
    // 此时仍应发货——链上的钱已真实到账，24h 内的迟付我们照常识别。
    if (order.status === "expired" || order.status === "cancelled") {
      await unCancelOrder(order);      // 解锁，标记为迟付
    }
    await grantCredits(p.uid, p.amount_received);
    await markFulfilled(order);
  } else if (p.event === "partial") {
    // 按比例发货（或仅记录，等后续到账）：收到 5/9.99 ≈ 50% → 50% 金币
    const ratio = Number(p.amount_received) / Number(p.amount_requested);
    await grantCredits(p.uid, ratio * order.credits);
  } else if (p.event === "expired") {
    await cancelOrder(order);
  } else if (p.event === "forwarded") {
    // 审计/对账用：款已归集到你的提现地址。业务发货应在 paid 时已完成。
    await recordForwarded(order, p.forward_tx, p.forwarded_to);
  }

  res.json({ ok: true });
});

{
  "event":             "feedback",
  "order_id":          "f6c8a97b-...",            // 我们的 UUID
  "merchant_order_id": "ORD-20260419-001",         // 你的订单 ID
  "uid":               "USER_12345",
  "topic":             "no-response",              // no-response | wrong-network | suggest
  "user_address":      "0xe13428d7...",             // 用户自述支付的钱包地址（suggest 时可能为 null）
  "chain":             "bsc",                      // 用户声称付到的链（wrong-network 下可能 ≠ 订单链）
  "currency":          "USDT",
  "amount_requested":  "0.16",                     // 订单原始金额，方便你定位
  "suggestion":        "我的钱包显示已扣款...",        // 用户输入的文字（topic=suggest 时必填）
  "screenshots":       ["data:image/png;base64,..."],  // 用户上传的截图（base64 data URI，最多 6 张，每张一般 < 1MB）
  "ts":                1745000000000,
  "nonce":             "a1b2c3d4e5f6..."
}

// 若单独配了 feedback_url 就直接挂这个路由；
// 若复用 callback_url，就在原 webhook handler 里按 p.event === "feedback" 分流。
app.post("/api/crypto-feedback", express.raw({ type: "application/json" }), async (req, res) => {
  // 验签流程同支付回调（略），略过后：
  const p = JSON.parse(req.body.toString());
  if (p.event !== "feedback") return res.sendStatus(400);

  // 1. 持久化（base64 截图建议落到对象存储后存 URL，别直接塞 DB）
  const screenshotUrls = [];
  for (const dataUri of (p.screenshots || [])) {
    screenshotUrls.push(await uploadToS3(dataUri));
  }
  await db.insertTicket({
    order_id:     p.merchant_order_id,
    uid:          p.uid,
    topic:        p.topic,
    user_addr:    p.user_address,
    chain:        p.chain,
    note:         p.suggestion,
    screenshots:  screenshotUrls,
    created_at:   p.ts,
  });

  // 2. 通知客服 / 运营（Slack / 邮件 / 站内消息）
  await notifySupport(`用户 ${p.uid} 订单 ${p.merchant_order_id} 反馈：${p.topic}`);

  res.json({ ok: true });
});