如何在 Telegram 机器人中接受 USDT 付款
Telegram 机器人是销售数字商品最好的地方之一,也是硬接传统收银台最糟糕的地方之一。没有银行卡表单,没有感觉像原生的托管支付页面,用户也讨厌被踢到浏览器里。一个提供普通 REST API 的加密货币支付网关要合适得多:机器人创建账单,把付款详情作为消息发出,等 Webhook 通知钱到账后再做出反应。
开始之前需要准备什么
- 从 @BotFather 获取的机器人令牌。
- 一台能接收 HTTPS 请求的服务器。机器人的后端和 Webhook 接收端可以是同一个应用。
- 一个已开启两步验证的 VisualPay 账户,已创建商户,并已从面板复制商户 API 密钥。注册和首个商户免费,也不需要先通过身份验证。
- 为您计划接受的每个币种和网络准备一个由您掌控的钱包地址,并登记在商户上。
流程的基本形态
写代码之前,先把谁做什么说清楚很有帮助,因为机器人收款漏钱往往就是这里出了错:
- 用户在机器人里选择商品。
- 您的后端(绝不是客户端)调用网关创建交易。
- 机器人把收款地址、精确的 USDT 金额和截止时间作为消息发出。
- 用户从自己的钱包付款。
- 网关检测到付款并调用您的 Webhook。
- 您的后端核实状态,把订单标记为已付,并让机器人交付商品。
请注意,第 6 步是由第 5 步触发的,而不是由用户的任何操作触发的。聊天里放一个“我已付款”按钮,作为重新检查状态的提示没有问题,但它绝不能成为放行商品的依据。
第 1 步:询问使用哪个网络
USDT 存在于多条链上,而且彼此不能互通。把 TRC20 的 USDT 发到 ERC20 地址,钱就没了。所以要让用户明确选择网络,用内联键盘,而不是自由输入文本:
{
"inline_keyboard": [
[{ "text": "USDT · TRC20 (Tron)", "callback_data": "pay:USDT:trc20" }],
[{ "text": "USDT · BEP20 (BSC)", "callback_data": "pay:USDT:bep20" }],
[{ "text": "USDT · ERC20 (Ethereum)", "callback_data": "pay:USDT:erc20" }]
]
}
一个实用的建议:把 TRC20 放在第一位。Tron 上的网络费足够低,对小额购买通常最友好,而机器人卖的大多就是小额商品。
第 2 步:在服务端创建交易
收到回调查询后,由您的后端创建账单。API 密钥放在请求头里,永远不离开您的服务器:
const res = await fetch(
'https://visualpay.net/api/v1/merchant/transaction/create',
{
method: 'POST',
headers: {
'x-api-key': process.env.VISUALPAY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
currency_symbol: 'USDT',
network_code: 'trc20',
amount_usd: 25.5,
ttl: 20,
order_id: order.id,
comment: `Telegram user ${ctx.from.id}`,
}),
}
);
const tx = await res.json();
有几个字段的取值值得想一想,而不是照抄:
ttl是付款窗口,单位为分钟,同时也是汇率保持锁定的时长。对机器人来说,二十分钟是合理的默认值:足够用户打开钱包应用,又足够短,可以限制价格波动带来的风险。order_id是您自己的标识。把它与 Telegram 用户和聊天关联保存,Webhook 才能找回对应的会话。comment是会显示在面板里的自由文本。当用户说“我付了钱但什么都没收到”时,它对客服很有用。
拿到返回的跟踪码后立即保存,并与订单关联。以后查询这笔付款就靠它。
第 3 步:把账单呈现为一条消息
因为网关返回的是付款数据而不是跳转,您可以用原生的方式呈现它。把金额和地址放在等宽格式里,这样在 Telegram 中点一下就能复制,并且不要让地址换行:
请精确发送:
1580.70 USDT
网络:TRC20 (Tron)
收款地址:
TXk...c72E
⏱ 20 分钟后过期。
有两处补充很划算。附上二维码,方便手机用户用另一台设备扫码。再加一个“检查付款”按钮,由它调用状态接口。这个按钮不是用来放行商品的,而是让着急的用户有东西可点,不用去找客服。
第 4 步:处理 Webhook
订单是在这里真正完成的。您的接口必须是 HTTPS,并且应该写得朴素而谨慎:
app.post('/webhooks/visualpay', async (req, res) => {
// 1. 尽快应答,不要让网关一直等待。
res.sendStatus(200);
const { tracking_code } = req.body;
// 2. 在服务端重新核实,而不是相信请求内容。
const status = await verifyWithGateway(tracking_code);
if (status !== 'confirmed') return;
// 3. 幂等:同一个 Webhook 可能到达不止一次。
const order = await orders.findByTrackingCode(tracking_code);
if (!order || order.fulfilled) return;
await orders.markFulfilled(order.id);
await bot.telegram.sendMessage(order.chat_id, '已收到付款。这是您的商品:…');
});
那三条带编号的注释就是全部要点。要快速响应,因为处理缓慢的 Webhook 会引发重试。要用状态接口重新核实,而不是相信请求体,这只多花一次 API 调用,却能消除一整类伪造攻击。要保证幂等,因为重试的 Webhook 把商品交付两次是真实存在的 bug,在生产环境里一定会发生。
第 5 步:处理不顺利的情况
机器人的成败,取决于事情进行得不顺利时会发生什么:
- 已过期。窗口关闭时仍未付款,没有产生任何扣费。把消息编辑为相应提示,并提供一个“重试”按钮,按当前汇率创建一笔新交易。
- 少付。如果差额在您为商户配置的少付容差之内,付款会通过,您的入账金额按实际到账数额重新计算。超出这个范围时,要明确告诉用户到账了多少、应付多少。
- 多付。付款被接受并记录为超额支付。请事先确定您的政策(把差额计入用户的账户余额,或者手动退款),并在用户付款前在机器人里说明。
- 迟付。有人在过期一分钟后才付款。重新核验接口可以对已过期或已取消的交易重新核实链上付款,所以这种情况可以挽回,不必变成一次客服事件。
收到结算款
因为 VisualPay 是非托管的,已确认的付款不会停留在服务商的余额里等您提现。某个网络的余额超过结算阈值后,资金会自动转到您登记的钱包地址,通常不到一分钟,只扣除链上本身的网络费。
值得认真对待的安全事项
- API 密钥应该放在服务器的环境变量里。绝不能放在机器人的客户端代码里,绝不能放进代码仓库,也绝不能出现在消息里。
- Webhook 接口必须是 HTTPS,路径也应当不易被猜到。
- 对创建交易的命令做频率限制。否则一个用户就能刷出几百张未付账单。
- 定期对账。每晚跑一个任务,列出交易并与您自己的订单比对,可以抓到少数完全漏掉 Webhook 的情况。
为什么这种做法适合机器人
不用安装插件,不用维护 SDK 版本,也没有打断对话的跳转。机器人始终是机器人:一条消息线程,账单出现在里面,被付清,然后变成交付的商品。网关所做的一切(汇率锁定、地址发放、链上监控、结算)都发生在两次 HTTP 调用和一个 Webhook 的背后。