简介这款USDT-TRC20收款插件专门为原版彩虹易支付系统开发面向需要接入加密货币收款、希望资金绕过第三方托管直接进自己钱包的站长或开发者。插件新增一种支付方式调用值设为usdt支持PC与移动端展示符合当前主流收款场景。资源压缩包仅7KB共5个文件核心为3个PHP文件分别承担支付调度、订单检查与插件初始化功能另有1个Markdown说明文件用于部署指导1个License授权文件明确使用范围。部署时只需将文件夹重命名为usdt并上传至易支付网站的plugins目录流程十分简洁。目前已有758人学习下载适合有一定PHP基础、正在使用彩虹易支付并希望快速扩展TRC20收款能力的用户参考源码完整保留既能直接运行使用也可作为二次开发样例用于理解易支付插件机制与USDT链上交易交互方式。1. 彩虹易支付接 USDT-TRC20最耗时的是“确认收款”这件事接入 USDT-TRC20 收款和接支付宝、微信最大的区别是没人替你确认收款到账。彩虹易支付的支付通道只负责把订单转成支付入口之后的“钱到没到”必须自己上链查。这个插件要做的就是把查链、确认、回调这一段补上让彩虹易支付的订单状态机完整跑通生成支付页 → usdt 钱包扫码转账 → 链上确认 → 订单自动完成。适合自己维护彩虹易支付、想给发卡站或独立站点加一条收款通道的开发者也适合想看清这类型支付插件怎么二开的老手。插件很小但链上确认、金额精度、防重这几件事一样躲不开。2. 彩虹易支付支付通道与 TRC20 链上确认先把链路画清楚2.1 彩虹易支付的下单流程里插件只碰两个入口彩虹易支付把所有支付方式抽象成一套插件接口用户下单后系统生成支付单并把订单号、金额、商品名传给插件实例插件负责渲染支付页面、展示二维码钱到账后再由插件触发异步通知把订单置为已完成。所以一份可用的支付插件至少要实现两个入口生成支付单和接收异步回调。普通支付通道的异步通知来自商户平台微信、支付宝都有现成的推送。USDT-TRC20 没有这类商户后台常见做法是在插件内部加一个轻量的链上监听任务自己完成“查链 → 确认 → 回调”的闭环。我一般会把目录组织成下面这样把监听和业务回调拆开plugin/usdt_trc20/ ├── pay.php # 渲染支付页生成收款二维码 ├── notify.php # 接收链上确认结果回调彩虹易支付订单 ├── monitor.php # 轮询 TronGrid把链上交易转成异步通知 ├── config.php # 收款地址、API Key、确认数 └── tron.php # 封装 TRC20 交易查询、金额格式化monitor.php 是这类插件的核心。pay.php 只负责把订单号、金额、收款地址放上页面真正的“货到”判定在 monitor 里完成它查到链上交易后调 notify.php再由 notify.php 更新订单数据库。把监听和确认逻辑分开能避免用户扫完码、浏览器同步跳回来时误把订单置为已完成。2.2 TRC20 的“支付成功”在链上如何判定我把“支付成功”拆成三个条件转账的接收地址等于配置中的 TRC20 收款地址转账代币合约等于 USDT 在 Tron 主网上的合约地址转账金额落在订单金额允许的误差范围。三个条件都满足后再看交易确认数是否达到阈值达到才允许回调进入订单系统。判定项检查方式常见误判点收款地址比对转账记录里的 to 字段漏了地址大小写TRON 地址按 Base58Check 编码最好做精确字符串比对代币合约比对 token_info 里的合约地址把 TRC20 的 USDT 和波场原生 TRX 转账混在一起金额按 6 位小数精度转成整数比较直接用浮点数相加丢精度误差累积到小数点后两位确认数当前最新区块与交易所在区块的差值用拉取时刻的区块数去判断而不是确认后重新取数TRC20 适合高频小额收款转账手续费以 TRX 计几乎可以忽略确认速度快小额等一个块就够二维码兼容市面上大多数支持 TRC20 的 usdt 钱包。这也是为什么同样接 USDT大多数人选 TRC20 而不是 ERC20后者转账费波动大、到账慢适合大额转账但不适合廉价小商品场景。确认数的计算我用一个公式confirmations current_block - tx_block 1。Tron 出块大约三秒一个19 个确认大概一分钟左右见第 5 章的分档建议。2.3 监听姿势轮询 TronGrid 的 TRC20 交易接口监听有两条路自建波场节点全量解析成本高适合每天几千单的规模轮询 TronGrid 的地址交易接口单地址收款足够接入也快。我一般用后者接口是/v1/accounts/{address}/transactions/trc20返回该地址最近的 TRC20 转账记录curl -G https://api.trongrid.io/v1/accounts/TYourAddress/transactions/trc20 \ -d contract_addressTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t \ -d limit20 \ -H TRON-PRO-API-KEY: your_key参数说明contract_address是 USDT 在 Tron 主网上的 TRC20 合约地址用于过滤掉 TRX 和其他代币的转账limit控制单次返回条数同一时间到账笔数多时调小 limit 并记录游标避免漏单TRON-PRO-API-KEY是 TronGrid 的接口 key只用于查询不需要暴露任何私钥。返回体里有timestamp、blockNumber、from、to、value字段value是按代币精度换算后的整数TRC20 的 USDT 精度是 6 位。你要做的是把这些字段映射到订单查询条件而不是在本地解析一个哈希字符串碰运气。轮询间隔我一般设 20 到 30 秒配合彩虹易支付默认的订单轮询足够设置太快反而容易撞上 TronGrid 的限流。3. 在彩虹易支付里写一个 USDT-TRC20 收款插件支付类骨架与五个必调参数3.1 支付类骨架pay 入口和 notify 入口以常见的二开结构为例彩虹易支付通过一个 PHP 类来实例化支付方式核心是pay和notify两个方法。下面这个骨架去掉了页面模板和日志细节保留了完整的调用顺序?php class Payment { protected $config; public function __construct($config []) { $this-config $config; } public function pay($order) { // 彩虹易支付传入 order_no、money_fen、notify_url // money_fen 单位是分转成 USDT 使用的 6 位小数金额 $amount bcdiv((string)$order[money_fen], 100, 6); $this-renderPayPage($order, $amount); } public function notify($data) { // $data 来自 monitor.phptx_id、to、value、confirmed if (!$this-checkTxOnChain($data[tx_id])) { return [code 0, msg tx not confirmed]; } $order $this-findOrderByTx($data[tx_id]); if (!$order || $order[status] ! pending) { return [code 0, msg order not found or done]; } $this-markOrderPaid($order[order_no], $data[tx_id]); return [code 1]; } protected function checkTxOnChain($txId) { // 调 tron.php 里的 queryTransaction返回确认数和转账详情 } }逻辑说明pay()被彩虹易支付按下单流程调用生成支付页面notify()被 monitor.php 调用先查链再做订单状态更新。checkTxOnChain这一步必须做不能轻信监听脚本自报的内容二次查链能拦截掉测试环境和主网环境串数据的问题。参数说明money_fen是彩虹易支付传入的订单金额单位是分bcdiv(..., 100, 6)把它转成保留 6 位小数的字符串findOrderByTx按交易哈希查订单确保同一笔链上交易不会被回调两次。pay()里的二维码生成直接用现成库把 TRC20 地址和金额拼接成字符串用户用 usdt 钱包扫码后会自动带出金额不需要额外处理。3.2 五个必调的配置参数缺一个都不好排查这类插件的配置项不建议做多五个足够。参数越少联调时越容易定位是配置问题还是代码问题。参数示例值说明trc20_addressTYourAddress收款地址支付页和链上校验都用它usdt_contractTR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6tUSDT-TRC20 合约地址主网只有这一个api_key你申请的 TronGrid key轮询查询限额按交易量调整confirmations1 或 19小额建议 1大额建议 19callback_secret随机字符串本地 notify 入口校验防止监听接口被伪造请求confirmations是整份配置里最影响体验的参数。设高了用户付款后干等设低了碰上链上重组小额还好大额订单可能被回滚。我的建议是按订单金额分档把金额段和确认数映射关系放进config.php而不是全局一个固定值。比如 200 元以下走 1 确认2000 元以上走 19 确认超过两万的订单直接转人工复核。3.3 金额精度与订单防重两个老坑一起填链上返回的金额是带 6 位小数的字符串彩虹易支付订单金额是“分”两边换算很容易出浮点误差。PHP 侧一律用 bcmath 扩展Python 侧用 Decimal不要用 float 做大小比较。订单表也要补三个字段ALTER TABLE pay_order ADD COLUMN usdt_amount VARCHAR(32) DEFAULT COMMENT 实际支付USDT数量, ADD COLUMN tx_hash VARCHAR(80) DEFAULT COMMENT TRC20交易哈希, ADD COLUMN confirmations INT(11) DEFAULT 0;字段说明usdt_amount用字符串存储避免数据库把0.000001转成浮点后丢失精度tx_hash加唯一索引可以作为幂等键同一笔交易重复进入 notify 时直接命中索引返回。防重逻辑放在 SQL 层最简单——先按tx_hash查一次订单表存在就直接返回成功不存在再执行更新。金额比较时用bccomp允许正负 0.01 的误差覆盖用户多付或少付几个字符的边界情况$expected 10.25; $paid 10.250100; $diff bcsub($paid, $expected, 6); if (bccomp($diff, 0.01, 6) 0 bccomp($diff, -0.01, 6) 0) { $this-markPaid($order[order_no], $txId); }逻辑说明bcsub得到实际到账与应到账的差值bccomp把差值限制在正负 0.01 以内避免链上手续费拆分或用户多转小额导致订单卡住。这里特意保留 6 位精度是为了和 TRC20 的 token 精度对齐换成 float 会在边界单上翻车。4. 部署与联调把彩虹易支付 USDT-TRC20 插件的回调链路跑起来4.1 在彩虹易支付后台添加一条自定义支付通道后台路径一般是管理后台 → 支付方式 → 添加通道类型选“自定义支付接口”。接口标识要和插件目录名一致方便后续追踪日志。以下是一份常见的配置对应关系后台字段填写值接口标识usdt_trc20支付名称USDT-TRC20展示给用户看的名字接口语言PHP异步回调地址https://你的域名/plugin/usdt_trc20/notify.php支付完成跳转保持默认注意这里有两层回调彩虹易支付后台配置的那层回调负责支付完成后跳回站内页面插件里的notify.php才是真正入账的入口。两者不要混用否则订单状态会乱。如果站点开了伪静态回调地址一定用真实文件路径避免 rewrite 规则把对notify.php的请求引导到前端控制器上。4.2 监听脚本轮询链上交易并触发订单回调monitor 用 Python 写比在 PHP 里跑 cron 更直观也方便单独查看日志。下面这段每分钟执行一次拉最近 TRC20 交易过滤后请求本地 notifyimport requests from decimal import Decimal API_URL https://api.trongrid.io/v1/accounts/{}/transactions/trc20 ADDRESS TYourAddress CONTRACT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t CONFIRMS 1 def poll(): data requests.get( API_URL.format(ADDRESS), params{contract_address: CONTRACT, limit: 20}, ).json() for tx in data.get(data, []): if tx[to] ! ADDRESS: continue if tx.get(token_info, {}).get(address) ! CONTRACT: continue value Decimal(tx[value]) / Decimal(10**6) requests.post( http://127.0.0.1/plugin/usdt_trc20/notify.php, json{tx_id: tx[transaction_id], value: str(value)}, )逻辑说明先按收款地址和合约地址做两层过滤再换算金额最后把结果转发给本地 notify 入口。tx[to]在 TRC20 转账记录里代表接收地址和原生 TRX 转账的字段结构不同不要直接用索引取值完事。参数说明limit20是单次返回上限地址交易密集时需要分页游标Decimal(10**6)用于把链上整数换算成人类可读金额全程无浮点误差monitor 脚本挂到系统计划任务里运行* * * * * cd /www/plugin/usdt_trc20 /usr/bin/python3 monitor.py logs/monitor.log 21cron 每分钟执行和脚本内while True sleep(30)效果类似但 cron 更稳进程被意外杀掉后下一分钟会自动恢复。日志里若出现重复的交易哈希说明防重生效不需要额外处理。4.3 联调失败自查地址对、合约对、金额对为何不到账最常见的问题集中在下面五处按顺序排查能省很多时间用户从交易所直接提现时转账的 to 地址是交易所的地址不是你的收款地址这种单子本来就等不到页面要写清楚“使用钱包转账不要直接提现”。合约地址复制错一位字符TronGrid 查不到任何交易。主网 USDT-TRC20 合约地址全局只有一个直接复制配置示例里的值。金额精度不一致页面显示的是分链上监听返回的是带 6 位小数的字符串比较前统一转成同一种形式。确认数阈值设定过高测试环境改成 1生产环境再按金额分档。19 个确认的等待时间要提前在支付页告知用户。同地址混入非订单转账外部转入的 USDT 也会触发 notify订单系统查不到对应订单就会一直报错。提示测试币不能转到主网地址联调必须用最小金额在主网真实走一笔。准备一个专用小地址转完就换别拿正式收款地址反复测。另外遇到过一个隐蔽问题监听脚本里对 TronGrid 返回的 blockNumber 做了本地缓存区块更新后又拿旧值算确认数导致订单永远不够确认。解决办法是每次轮询都重新取当前最新区块不要用订单创建时间倒推。5. 验证与进阶用最小脚本自测 TRC20 收款再把确认数调成阶梯分档5.1 一条命令自测整条链路在正式跑交易之前先用 TronGrid 查一笔已知交易来验证监听和回调逻辑有没有通。拿一笔你历史真实交易哈希填充下面的命令能同时确认接口 key 有效性和返回字段结构与你的解析代码是否匹配curl -G https://api.trongrid.io/v1/transactions/TX_ID \ -H TRON-PRO-API-KEY: your_key | python3 -c import sys, json data json.load(sys.stdin)[data][0] print(data[blockNumber]) print(data[raw_data][contract][0][parameter][value][to]) 更贴近业务的端到端自测是在彩虹易支付下一笔 1 元订单往专用收款地址转一笔等值链上金额然后观察 monitor 日志、notify 日志、订单状态三个节点是否依次变化。哪一层长时间没反应就去看对应日志文件这比在代码里到处加 print 管用得多。5.2 确认数分档配置确认数别写死按订单金额分档是这套插件里收益最明显的优化。参考分档订单金额范围建议确认数大致等待时间300 元以内1秒级300 到 3000 元6约 1 分钟3000 元以上19约 3 分钟实现时在 monitor 里对同一笔交易做多轮检查第一次看到它只记录当前确认数达到阈值才通知 notify已经见过的交易只更新 confirmations 字段不重复通知。这样既能保证大额订单足够安全又不会让小额用户等满 19 个确认才能拿货。进阶一点的做法是把收款归集也放进来当检测到收款地址余额超过设定阈值就把它转出到冷钱包。注意归集必须在 notify 确认订单入账之后执行否则会出现“收款地址余额不足但订单已完成”的冲突状态。插件里的私钥只放在监听端支付页面永远只暴露收款地址这个边界比任何防重逻辑都重要。本文还有配套的精品资源点击获取
