# 加密货币收银台 · 对接文档 > 托管式加密支付网关。商户只实现**两个 HTTP 接口**（一个**调用**创建订单 + 一个**接收**我们的 webhook），我们负责：生成收款地址、监听链上到账、签名回调、自动归集转账到你的提现地址。商户**不需要部署任何东西**，也不需要自己跑节点。 > > **支持链**：TRON · Ethereum · BSC · Arbitrum · Polygon · Base · Optimism · Solana（共 8 条） > **支持币种**：USDT、USDC > **基础 URL**：`https://cryptocashier.shop` > **文档版本**：v2（2026-04） > **商户中心**： --- ## 目录 1. [接入路线图（5 步）](#1-接入路线图) 2. [项目概览](#2-项目概览) 3. [第 1 步 · 注册拿到 api_key 和 callback_secret](#3-第-1-步--注册拿到-api_key-和-callback_secret) 4. [第 2 步 · 配置回调 URL + 提现地址](#4-第-2-步--配置回调-url--提现地址) 5. [第 3 步 · 创建订单 API](#5-第-3-步--创建订单-api) 6. [支付成功后用户去哪儿（return_url vs webhook）](#6-支付成功后用户去哪儿) 7. [第 4 步 · 接收回调 Webhook](#7-第-4-步--接收回调-webhook) 8. [用户反馈接口（可选）](#8-用户反馈接口可选) 9. [查询订单 API](#9-查询订单-api) 10. [支持的链（chain id）](#10-支持的链chain-id) 11. [第 5 步 · 联调 / 演示模式](#11-第-5-步--联调--演示模式) 12. [上线前检查清单](#12-上线前检查清单) 13. [常见问题 FAQ](#13-常见问题-faq) --- ## 1. 接入路线图 商户侧一共 **4 件必做 + 1 件可选**，按顺序做完即可上线： | # | 做什么 | 一次性 / 每笔订单 | 跳转 | |---|---|---|---| | 1 | 注册账号，拿到 `api_key` 和 `callback_secret` | 一次性 | §3 | | 2 | 配置回调 URL + 各链提现地址 | 一次性 | §4 | | 3 | 下单时调 `POST /api/v1/orders` | 每笔订单 | §5 | | 4 | 实现回调接口，接收 Webhook 发货 | 每笔订单 | §7 | | 5 | 联调演示 + 上线自检 | 可选但强烈建议 | §11–12 | --- ## 2. 项目概览 ### 完整支付路径 1. 用户在你网站点「加密货币支付」 2. 你后端 `POST /api/v1/orders`（带 `uid` / `amount_usd`），我们返回一个 `pay_url` 3. 你把用户 302 到 `pay_url`（我们的收银台页面），用户看到 QR 码和收款地址，用任何钱包扫码付款 4. 我们后台每分钟扫链，检测到用户付款 → 更新订单状态 → **POST 带签名 Webhook** 到你注册的 `callback_url` 5. 你验签成功后给用户加金币 / 发货，返回 `200 OK` 6. 我们把款从一次性收款地址自动归集转发到你在商户中心填的提现地址 7. 收银台页面轮询到订单已 `paid` → 显示「收款成功」，用户点「确定」跳回 `return_url`（未传则停在完成页） ### 核心好处 - **0 基础设施**：你不部署任何东西，只实现两个 HTTP 接口（一个调用 + 一个接收） - **链上到账真相由网关监听**：不依赖用户浏览器；用户关掉页面 / 断网也照样结算 - **每个 uid 一组永久 HD 派生地址**：同用户二次支付回同一地址，便于对账 - **HMAC 签名 Webhook + 8 次指数退避重试**（1m / 5m / 30m / 2h / 8h / 24h / 48h） - **支持 8 条主流链**，USDT + USDC - **自动归集**：到账后自动把款从一次性地址转到你的提现地址，你只需看着提现地址余额上涨 ### 时序图 ``` 用户浏览器 商户后端 加密网关 区块链 | | | | | 选择加密货币支付 | | | |------------------------>| | | | | 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 | | | |-------------------------->| | | | 自动归集转账到你的提现地址| | |------------------------>| | POST webhook (event=forwarded) | | |<--------------------------| | ``` --- ## 3. 第 1 步 · 注册拿到 api_key 和 callback_secret 去 用邮箱密码注册。系统立刻签发两样东西（**仅出现一次，务必复制保存**）： | 名称 | 用途 | |---|---| | `api_key` | 调用我们 API 时用，放在 `Authorization: Bearer ` header | | `callback_secret` | 我们回调你时用它做 HMAC 签名，你用它来**验签**你收到的 webhook | --- ## 4. 第 2 步 · 配置回调 URL + 提现地址 登录商户中心，完成三项配置（**前两项必做**，第三项可选但强烈建议）： | 配置项 | 必填 | 用途 | |---|---|---| | **🔔 回调 URL** (`callback_url`) | 必 | 订单状态变更时我们 POST 到这里（paid / overpaid / partial / expired / forwarded）。例 `https://site.com/api/crypto-webhook`。接收端实现见 §7。 | | **💸 提现地址**（每条启用的链一个） | 必 | 你自己控制的收款地址。我们检测到订单到账后自动把款从一次性收款地址**归集转发**到这些地址。**没填的链，前端会直接禁用**，用户无法在该链支付。 | | **📮 反馈 URL** (`feedback_url`) | 选 | 用户在收银台卡单、点「上传反馈」时，我们把**用户上传的钱包地址 + 截图 + 留言** POST 到这里。例 `https://site.com/api/crypto-feedback`。**不填**则复用回调 URL（按 `event: "feedback"` 分流）。详见 §8。 | > **小提示**：回调接收端可以等你实现完第 4 步再填。提现地址必须在**创建订单前**填好。反馈 URL 强烈建议配——用户卡单时你能第一时间拿到诊断信息，人工跟进发货或退款。 --- ## 5. 第 3 步 · 创建订单 API ``` POST /api/v1/orders ``` ### 请求 ```bash 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 }' ``` ### 请求字段 | 字段 | 必填 | 说明 | |---|---|---| | `merchant_order_id` | 必 | 你系统里订单 ID，唯一。重复调用同一 ID 返回同一订单（幂等） | | `uid` | 必 | 付款用户 ID（你系统里的 user_id）。**同一 uid 永远得到同一组收款地址** | | `amount_usd` | 必 | 订单金额，按 1:1 当作 USDT/USDC 金额。字符串类型避免浮点精度。范围 `(0, 1_000_000]` | | `product` | 选 | 商品名，仅展示 | | `return_url` | 选 | 用户在收银台点「确定」后**浏览器跳转的地址**（通常是你的"订单完成"页）。不传则停在我们的「支付完成」静态页。详见 §6 | | `expires_min` | 选 | 订单有效期（分钟），默认 10，范围 1–180 | ### 响应（HTTP 200） ```json { "id": "f6c8a97b-4569-4e92-a8fb-7f15b1c5a840", "merchant_order_id": "ORD-20260419-001", "uid": "USER_12345", "amount_usd": "9.99", "amount_received": "0", "status": "pending", "currency": null, "chain": null, "product": "100 金币", "return_url": "https://site.com/order/paid?id=ORD-20260419-001", "pay_url": "https://cryptocashier.shop/pay/f6c8...", "addresses": { "evm": "0x9858effd232b4033e47d90003d41ec34ecaeda94", "tron": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH", "sol": "HAgk14JpMQLgt6rVgv7cBQFJWFto5Dqxi472uT3DKpqk", "sol_ata": { "USDT": "6pXYguUixhfdydHDMgsvSy3sAWjStL2eEYh4KeYJAUDk", "USDC": "5N3f1tj9v1vc5TUZ8S7mCAnVmjVKrfnzXWhxLaxyZAgt" } }, "created_at": 1776613832602, "expires_at": 1776614432602, "updated_at": 1776613832602 } ``` - `status` 取值：`pending | partial | paid | overpaid | expired | cancelled` - `evm` 地址 ETH / BSC / Arbitrum / Polygon / Base / Optimism **共用** - `currency` / `chain` 会在用户付款后被填充 - 拿到 `pay_url` 后用户浏览器跳转过去即可（`302` redirect 或 `location.href = pay_url`） ### 错误响应 | HTTP | 说明 | 响应 body | |---|---|---| | `400` | 缺少必填字段 / 金额非法（非数字 / ≤0 / >1,000,000） | `{"error":"missing merchant_order_id"}` 等 | | `401` | `Authorization` header 缺失或 `api_key` 无效 | `{"error":"unauthorized"}` | | `402` | 手续费余额不足（新订单需 `fee_balance ≥ 阈值`） | `{"error":"insufficient fee balance","fee_balance":0.5,"required":2,"hint":"去商户中心充值"}` | | `429` | 触发限流（每商户有速率限制） | `{"error":"rate limited"}` | > **幂等**：用同一个 `merchant_order_id` 重复调用会返回**相同的订单**（不会重复创建，不消耗额外手续费）。网络重试安全。 --- ## 6. 支付成功后用户去哪儿？ 这块有两条**互相独立**的链路，职责分清楚就不会搞混： | 链路 | 干什么 | 你需要做 | |---|---|---| | **后端：Webhook（`callback_url`）** | 我们的服务器 → 你的服务器。通知"这笔订单到账了"，触发你**发货 / 加金币 / 改订单状态**。 | 实现一个 HTTP 端点接收（见 §7）。完全**看不见浏览器**，用户关不关页都照发。 | | **前端：`return_url`（浏览器跳转）** | 用户在收银台看到「收款成功」弹窗 → 点**「确定」** → 浏览器跳到 `return_url`。 | 创建订单时把 `return_url` 传上就行，其余全自动。不传则用户停在我们的「支付完成」静态页。 | ### 收银台是如何"消失"的？ 你什么都不用做——支付成功那一刻收银台自己会显示成功弹窗。用户点「确定」后： - 如果你传了 `return_url` → 浏览器 `location.href = return_url`（你的页面**替换掉我们的收银台**） - 如果没传 → 用户停在我们的「支付完成」页，关闭或返回由用户自己决定 **用户跳去哪由你决定**（就是 `return_url` 这个字段）。我们不替你关闭商户站的 tab，也不替你做任何商户站业务逻辑。 ### 常见疏漏 - 只设 `return_url` 不实现 webhook → 用户若不点"确定"就关页，你就**永远收不到发货通知**。**错的用法**。 - 只实现 webhook 不传 `return_url` → 用户会停在我们的"支付完成"页，略尴尬但不影响发货。可以接受。 - **两条都配才完整。** ### return_url 设计建议 - **带上订单 ID**：`https://site.com/order/paid?id=ORD-20260419-001` - **不要把它当发货触发器**：用户可能直接关浏览器不点确定；也可能复制 URL 分享。**发货逻辑永远以 webhook 为准**。 - **`return_url` 到达 ≠ 订单已发货**：落地页建议再查一次你自己的 DB 显示真实订单状态。 - **iframe 嵌入场景（进阶）**：如果把 `pay_url` 嵌进 iframe，可监听 `postMessage` 代替 `return_url`： ```js window.addEventListener("message", (e) => { if (e.origin !== "https://cryptocashier.shop") return; if (e.data?.type === "crypto-payment-received") { /* 支付到账事件 */ } if (e.data?.type === "crypto-payment-close") { /* 用户点确定，该关 iframe 了 */ } }); ``` --- ## 7. 第 4 步 · 接收回调 Webhook 我们在订单状态变化时 `POST` 到你注册的 `callback_url`。 ### 事件类型 | event | 触发时机 | 布尔标志 | |---|---|---| | `paid` | 累计收到金额**恰好等于**订单金额 | `fully_paid=true, overpaid=false, underpaid=false` | | `overpaid` | 累计收到金额 **>** 订单金额（多付了） | `fully_paid=true, overpaid=true, underpaid=false` | | `partial` | 收到部分款（累计 < 订单金额） | `fully_paid=false, overpaid=false, underpaid=true` | | `expired` | 订单有效期（默认 10 分钟）结束仍未足额——**包括用户完全没付款的情况**。由服务端 cron 每分钟扫描触发，**不依赖用户是否打开过收银台** | `fully_paid=false, underpaid=true` | | `forwarded` | 款已从一次性收款地址**归集转账到你的提现地址**（通常在 `paid` 之后 30 秒–数分钟内到达） | `fully_paid=true`，带 `forward_tx` / `forwarded_to` / `token_contract` / `forward_amount_raw` / `verify` 等链上校验字段 | **使用策略**： - **收到 `paid` 或 `overpaid` 就直接发货**（这时钱已上链确认，归集是我们内部的事） - `forwarded` 作"入账确认"——**强烈建议**用 payload 里的 `verify` 块独立链上校验一次（见 §7.x） - `partial` → 记录后等后续到账或 `expired` - `expired` → 取消订单（但注意下面的"晚到特性"） - **不要等 `forwarded` 才发货**，否则用户体感等得太久 - **30 分钟红线**：`paid` 之后没在 30 分钟内收到 `forwarded`，视为异常，应禁用我方支付通道并联系我们 ### ⚠ 重要：`expired` 之后仍可能收到 `paid`（特性，不是 bug） 即使订单已标 `expired`，如果用户在**过期后 24 小时内**把钱真的转到了链上（常见场景：用户超时后才点确认、钱包网络拥堵延迟确认、用户"我先把钱付了再联系客服"），我们的 monitor 仍会扫到并**补发 `paid` 回调**。 我们这么设计是为了**不让用户的钱石沉大海**——链上的钱我们一定会识别并归集给你。 **你需要做的：收到 `paid` 就发货，不管订单之前是不是 `expired`。** 简单适配一下，彻底避免"用户付了款但我这边已取消订单不发货"的争议。 ```js if (event === "paid" || event === "overpaid") { // 若订单之前被取消/过期，解锁后再发货 if (order.status === "cancelled" || order.status === "expired") { order.status = "paid_late"; // 标记为"迟付"便于审计 } if (!order.fulfilled) { await grantCredits(order.uid, p.amount_received); await markFulfilled(order); } } ``` **24 小时后的付款我们不再识别**（由 `LATE_WINDOW_MS` 控制）。超过 24h 要处理请通过[用户反馈接口](#8-用户反馈接口可选--强烈建议配)走人工流程。 ### 请求 Headers | Header | 值 / 说明 | |---|---| | `Content-Type` | `application/json` | | `X-Signature` | `HMAC-SHA256(callback_secret, raw_body)` — 十六进制小写 | | `X-Signature-Alg` | 固定 `HMAC-SHA256` | | `X-Timestamp` | 毫秒时间戳（等于 payload 里的 `ts`）。建议拒绝 `|now - X-Timestamp| > 5 分钟` 的请求（防重放） | | `X-Nonce` | 16 字节十六进制随机串（等于 payload 里的 `nonce`）。可缓存近期 nonce 几分钟，拒重复 | ### Payload（通用字段，`paid` / `overpaid` / `partial` / `expired` / `forwarded` 都有） ```json { "event": "paid", "order_id": "f6c8a97b-...", "merchant_order_id": "ORD-20260419-001", "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": "0xabc...", "chain": "trc20", "currency": "USDT", "from": "TXxxxxxxxxxx", "amount": "9.99" }, "created_at": 1776613832602, "expires_at": 1776614432602, "ts": 1776613890123, "nonce": "a1b2c3d4e5f6..." } ``` 字段说明： - `amount_requested` / `amount_received` 是**字符串**（避免浮点精度丢失） - `latest_tx` 在 `expired`（用户没付）时为 `null` - `ts` 毫秒时间戳 = `X-Timestamp` header 的值 - `nonce` 16 字节十六进制 = `X-Nonce` header 的值 ### `forwarded` 事件的额外字段 款已归集到你的提现地址时，除通用字段外还会带**完整的链上校验信息**，方便你**不依赖我们的服务**独立去链上核对这笔钱真的到了： ```json { "event": "forwarded", "forward_tx": "0xabc123...", "forward_from": "0x175fa10f95ec430d1ff91eedd3adcd3fafd91081", "forwarded_to": "0xb11272...", "forward_amount": "0.1", "forward_amount_raw": "100000000000000000", "forward_currency": "USDT", "forward_chain": "bsc", "token_contract": "0x55d398326f99059ff775485246999027b3197955", "token_decimals": 18, "explorer_url": "https://bscscan.com/tx/0xabc123...", "forward_delay_ms": 45000, "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 https://bsc-rpc.publicnode.com ...", "expect": { "result.status": "0x1", "result.logs[i].address": "0x55d398326f99059ff775485246999027b3197955", "result.logs[i].topics[0]": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef", "result.logs[i].topics[2]": "0x000000000000000000000000b11272...", "BigInt(result.logs[i].data)": "100000000000000000" } } } ``` 字段解释： - `forward_tx` 我们发给你的归集 tx hash - `forward_from` 派生地址（我们给用户的那个一次性收款地址，钱从这里出去） - `forwarded_to` 你配置的提现地址（钱最终到这里） - `forward_amount_raw` 链上真实数值（字符串形式的 BigInt，不带小数点） - `token_contract` 代币合约地址（用来识别是 USDT 还是 USDC） - `verify` **完全自包含的校验指令**——把它 copy 下来 curl 一下就能独立验证 --- ### 🔒 §7.x 独立链上校验（一行代码，强烈建议高价值商户接入） #### 为什么要自己校验 我们的 webhook 有 HMAC 签名保证**来源可信**，但**最终可信的只有链上数据**。假设极端情况——我们的服务器被攻破、内部人员作恶、bug 误判——攻击者可能伪造 `forwarded` webhook 让你误以为收到钱。链上校验是你的**最后防线**。 #### 一个函数搞定：`verifyForwardOnChain` 我们提供一个**零依赖、Node/浏览器通用、覆盖 8 条链** 的校验函数。下载地址： **👉 https://cryptocashier.shop/verify-forward.cjs** 把它 copy 到你项目里（或 `wget`、`curl -O`），然后一行调用： ```js 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，不带 0x / T 前缀 }; // 在你的 webhook handler 里（已验过 HMAC 签名之后）： if (payload.event === "forwarded") { const result = await verifyForwardOnChain({ payload, // 我们发给你的完整 JSON myPayouts: MY_PAYOUTS, // ← 按链自动匹配（推荐） expectedAmountRaw: order.expected_raw, // ← 你订单上记录的应付金额（选填但推荐） }); if (result.ok) { console.log("归集已链上验证", result.onChain); await markOrderVerified(order.id); } else { console.error("归集校验失败:", result.reason); await disableCryptoGateway(); // ← 立即禁用我方支付通道 await alertOps(payload, result.reason); } } ``` 返回 `{ ok: true/false, reason, onChain? }`。`ok=false` 时 `reason` 会写清楚哪不对（地址被篡改 / tx 不存在 / tx 回滚 / 金额不对 等）。 **ESM 项目** 用 `createRequire` 桥接加载；**浏览器** 用 `