网站如何接入 USDT 收款:三种方案与对接步骤
贴钱包地址、自建扫链还是用托管网关?讲清三种 USDT 收款方案的真实成本,并完整演示从创建订单到正式上线的对接流程。
想在网站上接入 USDT 收款,很多人第一步都是把钱包地址贴到付款页,让客户转完账发截图。订单少的时候没问题,一天几十单之后,对账就成了谁都不想干的活。
这篇文章先把三种常见的 U 收款方案讲清楚,再以托管支付网关为例,从第一个 API 请求讲到正式上线,最后附一份上线前检查清单。
网站接入 USDT 收款的三种方案
方案一:贴钱包地址,人工核对
在付款页放上你的 TRC20 地址和二维码,客户转账后发来截图或交易哈希,你去区块浏览器查一下,再手动把订单改成已付款。
零成本,私钥在自己手里。但量一上来,问题就都来了:
- 两个客户都要付 50 USDT,又在同一个小时里付,链上看起来一模一样,只能挨个要交易哈希。
- 很多人从交易所提币,填金额时没算提币手续费,结果你只收到 49,又多一张工单。
- 有人转错网络,或者转来一个名字也叫「USDT」的山寨币。如果只看代币名称,很容易上当。
- 凌晨三点没人对账,虚拟商品只能等你睡醒再发。
一周几单的小项目够用,再多就吃力了。
方案二:自建扫链程序
自己生成地址、监听链上入账、和数据库里的订单做匹配。在波场上,就是读取你地址相关的 TRC20 Transfer 事件,并核对合约地址是不是真正的 USDT 合约(TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t,以 Tether 官网公布的为准)。
资金完全自己掌控,也不用给第三方分成。但下面这些事都得自己扛:
- 确认逻辑。 交易进了区块不等于最终确认,要等区块固化(solidified)。根据波场开发者文档,这通常需要 1 分钟左右。提前入账,万一遇到分叉回滚(概率很低)就可能白发货。
- 订单匹配。 要么一单一个地址,之后得从几百个地址里归集资金,而每次归集 TRC20 都要消耗 TRX 换能量(详见 TRC20 USDT 转账手续费详解);要么共用地址,靠金额区分订单。
- 私钥安全。 放着私钥的服务器,本身就是攻击目标。
- 节点稳定性。 RPC 服务一限流,到账记录就「消失」了。
有开发资源、又确实需要自己保管资金,可以考虑。大多数商家都会低估后期的维护量。
方案三:用托管的 USDT 支付网关
网关提供 API 和托管收银台。你的服务器创建一笔订单,把客户跳转到收银台,钱到账后网关给你发回调。扫链、匹配金额、处理过期,都由网关负责。如果对这个概念还不熟,可以先看什么是加密货币支付网关。不会写代码也没关系,很多网关支持直接在后台生成收款链接。
实话说,这类网关大多是托管模式:客户付的钱先进网关管理的地址,记到你的余额里,你再随时申请提现。付款到提现之间资金由平台保管,所以建议定期提现,别把网关余额当存款。
| 贴地址人工核对 | 自建扫链 | 托管网关 | |
|---|---|---|---|
| 上手时间 | 几分钟 | 几周 | 一个下午 |
| 资金在谁手里 | 自己 | 自己 | 网关,直到提现 |
| 订单匹配 | 人工 | 自己写代码 | 自动 |
| 迟到、金额不对 | 处理工单 | 自己写代码 | 网关规则 + 人工复核 |
| 日常工作量 | 每单都要管 | 服务器、私钥、节点 | 维护一个回调接口 |
先选好收款网络:TRC20、ERC20 还是 BEP20
写代码之前,先定好收哪条链上的 USDT。做收款一般默认 TRC20,主要原因是几乎所有交易所和钱包都支持,很多客户手里的 U 本来就在波场上。
至于手续费,其实没法简单排个高低。每条链的计费方式不一样:波场按能量和带宽算(不够就烧 TRX),以太坊按 Gas 算,BNB Chain 按 BNB 计的 Gas 算。客户实际花多少,主要看他所用交易所在这条网络上的提币费,而这个数经常变。TRC20 和 ERC20 的区别不只是手续费,建议先看 USDT TRC20、ERC20、BEP20 怎么选。
TillCrypto 目前支持 USDT-TRC20 和 TRX,以太坊和 BNB Chain 上的 USDT 即将上线。
不管选哪个,付款页都要写清楚。只写一句「支持 USDT 付款」,等于在邀请客户转错网络。
USDT 支付网关对接步骤
下面以 TillCrypto 为例,不过大多数网关的流程都差不多:创建订单、跳转收银台、等回调。
第 1 步:创建 API 密钥,配置回调
注册后在后台「开发者」页面创建密钥。测试密钥以 sk_test_ 开头,正式密钥以 sk_live_ 开头。在同一页面填好回调地址,复制回调密钥(whsec_ 开头)。
密钥和回调密钥一并放进服务器环境变量,绝对不能出现在前端 JavaScript 中。
第 2 步:调用收款接口创建订单
客户点击「USDT 付款」时,由你的后端调用 USDT 收款接口:
const res = await fetch('https://api.tillcrypto.com/v1/payments', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TILLCRYPTO_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: '25.00',
currency: 'USDT-TRC20',
order_id: 'ORDER-10042',
description: '专业版 1 个月',
success_url: 'https://example.com/thanks',
cancel_url: 'https://example.com/cart',
}),
});
const payment = await res.json();
// payment.id, payment.status === 'pending', payment.checkout_url把 payment.id 存到你的订单上。order_id 填你自己系统的订单号,回调里会原样带回,查单很方便。
第 3 步:跳转到收银台
把客户重定向到 checkout_url。收银台会显示二维码、收款地址、精确金额和 60 分钟倒计时,链上确认后自动更新状态。客户转完等不及的话,还可以点「我已付款,立即检查」。
第 4 步:以回调为准发货,别看跳转
这是第一次对接最容易出错的地方。客户回到你的 success_url 什么也证明不了,因为谁都可以手动打开这个地址。只有收到签名校验通过的 payment.paid 回调,才能发货。
每个回调都带 X-TillCrypto-Signature 请求头,格式是 t=<时间戳>,v1=<十六进制>,其中 v1 是用回调密钥对 <t>.<原始请求体> 做的 HMAC-SHA256。校验必须用原始字节,并且在解析 JSON 之前完成。用 Express 的话,给这个路由单独挂上 express.raw():
import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
function isValid(rawBody, header, secret) {
if (!header) return false;
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const a = Buffer.from(v1 ?? '', 'hex');
const b = Buffer.from(expected, 'hex');
if (a.length !== b.length) return false;
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && timingSafeEqual(a, b);
}
const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const rawBody = req.body.toString('utf8');
const header = req.get('X-TillCrypto-Signature');
if (!isValid(rawBody, header, process.env.TILLCRYPTO_WEBHOOK_SECRET)) {
return res.status(400).send('invalid signature');
}
const event = JSON.parse(rawBody);
if (event.type === 'payment.paid' && event.livemode) {
// 按 event.data.order_id 找到订单,未处理过才标记为已付款
}
res.sendStatus(200);
});注意那个 livemode 判断。测试事件和正式事件发到同一个地址、用同一个密钥签名,签名完全合法的测试事件看起来和真的一样。正式环境只处理 type 为 payment.paid 且 livemode 为 true 的事件,其他类型(后台测试按钮发的是 webhook.test)直接忽略。
处理逻辑还要做幂等。投递失败会在 1 分钟、5 分钟、15 分钟、1 小时、6 小时、24 小时后重试,同一个事件可能收到两次。用 X-TillCrypto-Event-Id 或订单 ID 去重,并尽快返回 2xx。更多细节和常见的坑,见如何校验加密支付回调签名。
第 5 步:用测试模式走一遍
换成 sk_test_ 密钥,整个流程完全一样,但不会碰链上,也不会动你的余额。打开测试订单的收银台,模拟付款成功,你的成功页和回调接口应该和正式环境表现一致,只是事件里的 livemode 为 false。后台还有发送测试事件的按钮,调签名校验代码时很好用。
第 6 步:正式上线
把 sk_test_ 换成 sk_live_ 密钥即可,回调地址和回调密钥不用改。测试和正式事件都会发到同一个地址,用事件里的 livemode 字段区分。
建一笔小额真实订单,自己从交易所或钱包付一次。看着它从 pending 变成 paid,确认你的订单状态也更新了,再申请一笔小额提现,把出金流程一起验证掉。提现金额要大于 2 USDT 的网络费,而且提现会先经过审核再上链,不是秒到。TillCrypto 不收交易手续费,TRC20 USDT 提现每笔收固定 2 USDT 网络费。
哪些情况还得人来处理
没有哪种方案能消灭所有特殊情况。客户会少付、多付、该转 USDT 却转了 TRX,或者隔天才付。靠谱的网关会把这些记成「未匹配」转账,留给你人工复核,但怎么处理得你自己定:退款、让客户补差价,还是手动入账。最好在第一单出问题之前就写下来。常见情况可以参考加密支付的各种异常情况。
上线前检查清单
- 付款页写明币种和网络,比如「USDT(波场 TRC20)」。
- API 密钥和回调密钥只放在服务器环境变量里,不进前端代码,也不进 Git。
- 已经填好回调地址,并且至少收到过一次事件。
- 只根据校验通过、且
livemode为true的payment.paid回调发货。 - 验签用原始请求体,比较时用常量时间函数。
- 回调处理能忽略重复事件和不认识的事件类型。
- 收到
payment.expired之前不取消订单。 - 已经用测试模式完整跑过一遍,包括回调。
- 已经做过一笔真实收款和一笔真实提现。
- 少付、多付、转错币都有书面处理规则,每天至少有人看一次未匹配转账。