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

用户浏览器                  商户后端                    加密网关                  区块链
    |                         |                           |                         |
    | 选择加密货币支付        |                           |                         |
    |------------------------>|                           |                         |
    |                         | 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://pay.yoursite.com/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
  "pay_url": "https://pay.yoursite.com/pay/f6c8...",      // 让用户浏览器打开这个
  "addresses": {
    "evm":  "0x9858effd232b4033e47d90003d41ec34ecaeda94",
    "tron": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
    "sol":  "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk",
    "sol_ata": {
      "USDT": "6pXYguUixhfdydHDMgsvSy3sAWjStL2eEYh4KeYJAUDk",
      "USDC": "5N3f1tj9v1vc5TUZ8S7mCAnVmjVKrfnzXWhxLaxyZAgt"
    }
  },
  "created_at": 1776613832602,
  "expires_at": 1776614432602
}

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

{
  "event":             "paid",                    // paid|overpaid|partial|expired
  "order_id":          "f6c8a97b-...",           // 我们的 UUID
  "merchant_order_id": "ORD-20260419-001",        // 你的订单 ID
  "uid":               "USER_12345",
  "amount_requested":  "9.99",
  "amount_received":   "9.99",                   // 累计收到
  "currency":          "USDT",
  "chain":             "trc20",                  // 最后一笔所在链
  "fully_paid":        true,
  "overpaid":          false,
  "underpaid":         false,
  "latest_tx": {                                     // 触发本次回调的那笔 tx
    "tx":       "0xabc...",
    "chain":    "trc20",
    "currency": "USDT",
    "from":     "TXxxxxxxxxxx",
    "amount":   "9.99"
  },
  "created_at":        1776613832602,
  "expires_at":        1776614432602,
  "ts":                1776613890123
}

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

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

// 必须用 raw body 解析，否则算出的签名不一致
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 expected = crypto.createHmac("sha256", CALLBACK_SECRET)
    .update(rawBody).digest("hex");
  if (sig !== expected) return res.sendStatus(401);     // 验签失败

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

  // 幂等：检查订单状态，避免重复加金币
  const order = await findOrder(p.merchant_order_id);
  if (order.fulfilled) return res.json({ ok: true, dup: true });

  if (p.event === "paid" || p.event === "overpaid") {
    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);
  }

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

https://site.com/cashier/index.html
  ?order_id=ORD20260419001
  &amount=9.99
  &product=100%20金币
  &return_url=https%3A%2F%2Fsite.com%2Fpaid%3Fid%3DORD20260419001
  &callback_url=https%3A%2F%2Fsite.com%2Fapi%2Fcrypto-callback
  &callback_token=eyJhbGciOiJI...

{
  "order_id":              "ORD20260419001",
  "product":               "100 金币",
  "currency":              "USDT",               // "USDT" | "USDC"
  "chain":                 "trc20",              // 见"支持的链"章节
  "chain_name":            "TRC-20",             // 人类可读的链名
  "amount_requested":      "9.99",               // 订单原始金额（来自 URL param）
  "amount_received_this":  "5.00",               // 本次到账金额（单笔）
  "amount_received_total": "5.00",               // 累计到账（同一会话内多笔会累加）
  "tx":                    "0xabc...def",         // 交易哈希（TRON/EVM 带 0x，Sol 不带）
  "from":                  "0x1234...",          // 付款方地址（Sol 可能为空）
  "to":                    "0x1eef...",          // 本次链上的收款地址
  "fully_paid":            false,                // 累计 ≥ 订单金额
  "overpaid":              false,                // 累计 > 订单金额
  "underpaid":             true,                 // 累计 < 订单金额
  "addr_slot":             0,                    // 本订单使用的收款地址槽位 (0..N-1)
  "callback_token":        "eyJhbGciOiJI...",    // 原样回传 URL 传入的 token
  "ts":                    1712345678000         // 本次回调时间戳（毫秒）
}

{
  "type":               "feedback",         // 标识为反馈，支付回调没有此字段
  "topic":              "no-response",      // "no-response"|"wrong-network"|"suggest"
  "order_id":           "ORD20260419001",
  "product":            "100 金币",
  "user_address":       "0xabc...",         // 用户填入的支付地址（suggest 为 null）
  "chain":              "trc20",             // 相关链 id（可能为 null）
  "chain_name":         "TRC-20",
  "currency":           "USDT",
  "amount_requested":   "9.99",
  "suggestion":         "...",                // 建议内容（仅 suggest 主题有）
  "screenshots_base64": ["data:image/png;base64,..."], // 最多 6 张
  "addr_slot":         0,
  "callback_token":     "eyJhbGciOiJI...",
  "ts":                 1712345678000
}

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

const app = express();
app.use(express.json({ limit: "10mb" })); // 反馈可能带 base64 截图

// CORS — 允许收银台所在域
app.use("/api/crypto-callback", (req, res, next) => {
  res.set("Access-Control-Allow-Origin", "https://site.com");
  res.set("Access-Control-Allow-Methods", "POST, OPTIONS");
  res.set("Access-Control-Allow-Headers", "Content-Type");
  if (req.method === "OPTIONS") return res.sendStatus(204);
  next();
});

app.post("/api/crypto-callback", async (req, res) => {
  const p = req.body;

  // 1. 鉴权：校验 callback_token（假设是 HMAC 签名）
  const expected = crypto
    .createHmac("sha256", process.env.SIGN_SECRET)
    .update(p.order_id)
    .digest("hex");
  if (p.callback_token !== expected) return res.sendStatus(401);

  // 2. 分流：反馈 vs 支付
  if (p.type === "feedback") {
    await saveFeedback(p);
    return res.json({ ok: true });
  }

  // 3. 支付 — 幂等处理（同一 tx 只处理一次）
  const existing = await findPayment({ tx: p.tx });
  if (existing) return res.json({ ok: true, dup: true });

  await recordPayment({
    order_id: p.order_id,
    tx: p.tx, from: p.from,
    chain: p.chain, currency: p.currency,
    amount: p.amount_received_this,
    ts: p.ts,
  });

  // 4. 根据累计状态决定发货
  if (p.fully_paid) {
    await deliverOrder(p.order_id);        // 加金币
  } else if (p.underpaid) {
    // 部分到账 — 记录，等待继续支付或超时后按比例处理
    await markPartial(p.order_id, p.amount_received_total);
  }

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

async function goCryptoCashier(orderId, amount, productName) {
  // 向服务端获取带签名的 token（防伪造）
  const r = await fetch("/api/sign-order", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ orderId, amount }),
  });
  const { token } = await r.json();

  const q = new URLSearchParams({
    order_id:       orderId,
    amount:         amount.toString(),
    product:        productName,
    return_url:     `${location.origin}/order/success?id=${orderId}`,
    callback_url:   `${location.origin}/api/crypto-callback`,
    callback_token: token,
  });
  location.href = `/cashier/index.html?${q}`;
}

window.addEventListener("message", (e) => {
  if (e.origin !== "https://site.com") return;

  if (e.data?.type === "crypto-payment-received") {
    const { payload } = e.data;
    // payload 结构同 HTTP 回调
    updateOrderUI(payload);
  }
  if (e.data?.type === "crypto-payment-close") {
    // 用户点"确定"且未设置 return_url 时发出
    closeCashierModal();
  }
});

const ADDRESS_SLOTS = [
  // ... 已有的 slot 0..3 ...
  {  // slot 4 (新增)
    evm:    "0x...",                               // 新 EVM 地址
    tron:   "T...",                                // 新 TRON 地址
    sol:    "...",                                 // 新 Solana 地址
    solAta: {                                       // ⚠ 必须预先用 Python 脚本计算
      USDT: "<SOL 地址 + USDT mint 的 ATA>",
      USDC: "<SOL 地址 + USDC mint 的 ATA>",
    },
  },
];

# pip install solders
from solders.pubkey import Pubkey

sol_addrs = [
    "<你的新 SOL 地址>",
    # 可一次算多个
]

token = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
atap  = Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")

for s in sol_addrs:
    owner = Pubkey.from_string(s)
    print(f"\nSOL: {s}")
    for name, mint in [
        ("USDT", "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"),
        ("USDC", "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"),
    ]:
        m = Pubkey.from_string(mint)
        ata, _ = Pubkey.find_program_address(
            [bytes(owner), bytes(token), bytes(m)], atap
        )
        print(f"  {name} ATA: {ata}")

import redis, time

r = redis.Redis()
POOL_SIZE = 4            # 与前端 ADDRESS_SLOTS 长度一致
LOCK_TTL_SEC = 15 * 60

def allocate_slot(order_id: str) -> int | None:
    # 1. 粘性：同一订单返回原 slot
    prev = r.get(f"cashier:sticky:{order_id}")
    if prev:
        slot = int(prev)
        # 续租该 slot
        r.set(f"cashier:slot:{slot}", order_id, ex=LOCK_TTL_SEC)
        return slot
    # 2. 找首个空闲 slot，原子抢占
    for i in range(POOL_SIZE):
        if r.set(f"cashier:slot:{i}", order_id, ex=LOCK_TTL_SEC, nx=True):
            r.set(f"cashier:sticky:{order_id}", i, ex=LOCK_TTL_SEC * 2)
            return i
    return None        # 全部占用

def release_slot(slot: int, order_id: str):
    owner = r.get(f"cashier:slot:{slot}")
    if owner and owner.decode() == order_id:
        r.delete(f"cashier:slot:{slot}")

# 在生成收银台 URL 前调用
slot = allocate_slot(order_id)
if slot is None:
    raise TooBusyError("pool saturated — ask admin to add more addresses")
cashier_url = f"/cashier/index.html?order_id={order_id}&amount={amt}&addr_slot={slot}&..."

# 收到支付回调时，在 deliverOrder 内释放
if payload["fully_paid"]:
    deliver_order(payload["order_id"])
    release_slot(payload["addr_slot"], payload["order_id"])