简介：原版彩虹易支付虽然扩展性强，但默认不集成加密货币通道。面向使用该系统的站长与开发者，这款USDT-TRC20收款插件可直接补足这一缺口：接入后，客户以TRC20网络支付USDT，资金直接进入个人钱包，不经过任何第三方通道，适合个人或小微站点低成本启用加密支付。资源包采用RAR压缩，共5个文件，以3个PHP脚本为核心，分别承担支付方式注册、订单支付处理和定时链上查询功能，另含1份Markdown配置说明和1份License文件，整体体积仅7KB，部署简单，目录结构清晰。当前已有758人学习浏览，尤其适合具备一定PHP基础的易支付使用者作为参考；内容包含可运行的插件源码、挂载说明与回调逻辑梳理，既能帮助理解易支付插件扩展机制，也能为二次开发或生产部署提供轻量模板。
1. 彩虹易支付的 USDT（TRC20）收款，绕不开的两个问题
做资源站或出海业务的人，大概率遇到过这种尴尬：彩虹易支付接好了支付宝、微信，但客户里总有那么一批人只愿意打 USDT。临时去接第三方 USDT 通道，手续费高不说，资金还要在别人那过一手，结算周期拖三天都算快。这个插件的做法是把 USDT（TRC20）直接注册成易支付的一种新支付方式，顾客扫码后链上转账，钱秒到你自己的钱包，你不需要打开交易所或钱包 App 去对账，后台订单状态自己更新。它的技术要点是两件事：一是搞懂易支付的插件接口怎么扩展，二是把 TRC20 链上交易和传统回调逻辑对接起来。看完这篇，你不仅能装上，还能知道链上确认、通知回调这些环节在哪调、断在哪。
2. 支付插件与 TRC20 链上监听的回调链路
2.1 彩虹易支付的插件没有想象中复杂
彩虹易支付原版（PayJS 那套分支）本身就预留了第三方支付方式的扩展点。所谓的「插件」，就是往plugins目录丢一个文件夹，文件夹里放一个继承某个支付类、实现统一接口的 PHP 文件。支付流程里，易支付核心会把订单参数交给这个插件类的pay()方法，由它生成跳转链接或二维码；用户付款后，再由插件类的notify()或callback()方法接收第三方支付平台的异步通知，改订单状态。
这个 USDT 插件走的也是同一套机制，只是它把「第三方支付平台」换成了「TRC20 链上转账」。usdt_plugin.php这个类注册后，核心代码在创建订单时会调它的getQrcode()或类似的生成方法，返回一个收款的 TRC20 地址；而订单是否支付成功，则由cron.php定时去链上扫交易来确认。所以它不依赖外部支付网关，这也是它能「直接到钱包」的根本原因：整个资金链路里只有你自己的钱包地址。
2.2 链上交易到订单回调的完整链路
一张订单从创建到完成的完整时序大概是这样的：
- 用户在商城下单，易支付核心生成订单。
- 核心调用插件生成收款信息，页面展示一个 TRC20 地址（或二维码）。
- 用户用任意支持 TRC20 的钱包往这个地址转 USDT。
- 链上广播后约 1 到 2 分钟，TRON 网络打包出块，交易进入「已确认」状态。
cron.php在下一个执行周期请求 TRONSCAN 或 TRON Grid 接口，查询该地址最近的 USDT 转账。- 匹配到对应订单、校验金额无误后，调用易支付核心的订单完成方法。
关键在最后一步。易支付核心标注订单完成，通常通过POST参数把订单号和金额传给某个固定的回调 URL，或者直接调用本地函数改库。写这类插件时，你要在每个关键节点输出日志，因为链上转账具备不可逆性——订单漏标意味着收到币但客户拿不到东西，所以轮询和金额校验要格外保守。
2.3 确认数与安全边界
TRC20 的 USDT 转账在 TRON 网络上的确认时间和确认数有关。链上出现一笔交易后，如果只等一个区块确认，理论上存在极小的重组风险。虽然 TRON 的 DPoS 机制下单区块确认稳定性较高，但插件设计里通常会做两个安全阀：
- 等待至少 2 到 19 个区块确认（具体看插件配置，通常可以自己调确认数）。
- 金额校验精确到小数位。TRC20 的 USDT 是 6 位精度，而主流 PHP 的浮点数直接比较会出问题，必须用整数比较或
bccomp()对比。
2.4 钱包地址的本地派生
「直接到自己的钱包」意味着钱包地址是本地的——收款地址要么来自你自己的 TRON 私钥生成的地址，要么是某个导入的助记词地址。多数插件在cron.php或配置页里让你填私钥或助记词，然后用tron-php库生成地址。如果你不想把私钥写在服务器配置里，也有另一种折衷方案：
在配置页填一个观察地址（你交易所或收款钱包的地址），插件只做链上监控，不碰私钥。这样安全边界更清晰，但也意味着插件无法做什么签名操作，一般也不需要。
3. 安装与配置：把 USDT 插件挂到易支付
3.1 目录结构与命名
拿到epay_usdt-main解压后，你会看到这些文件：
epay_usdt-main/ ├── pay.php ├── cron.php ├── usdt_plugin.php ├── LICENSE └── README.md安装的第一步不是直接传上去，而是把epay_usdt-main重命名为usdt，然后整体上传到易支付站点的plugins目录。命名决定了支付方式在系统内部的调用值，所以plugins目录下这个文件夹名必须是usdt。
# 在服务器站点根目录执行 mv epay_usdt-main usdt cp -r usdt /www/wwwroot/你的域名/plugins/ chown -R www:www /www/wwwroot/你的域名/plugins/usdt chmod -R 755 /www/wwwroot/你的域名/plugins/usdtchown和chmod是很多 PHP 项目最容易踩的坑：如果cron.php对日志文件或数据缓存没有写权限，后台配置保存后会出现「保存成功但定时任务一直跑不起来」的怪现象，日志文件根本写不进去。另外，上传时注意隐藏文件，.git目录或README.md里的换行符可能导致部分环境下的路径解析异常。
3.2 后台添加支付方式
登录易支付后台，找到「支付方式」或「支付接口配置」，点击新增：
| 配置项 | 填写内容 | 说明 |
|---|---|---|
| 支付方式名称 | USDT 或 稳定币收款 | 前台展示用，随意 |
| 调用值 | usdt | 必须和插件目录名一致 |
| 支持设备 | PC + Mobile | 两种端都勾上 |
| 商户号 | 留空或填你的 TRON 地址 | 取决于插件实现 |
| 商户密钥 | 留空 | 链上收款不需要 |
| 请求方式 | 标准跳转或返回 | 看插件README说明 |
| 状态 | 启用 | 必须启用 |
设置完保存后，去网站前台测试下单，确认支付方式列表里出现了 USDT 图标或名称。如果没出现，优先检查调用值是否填了usdt——大小写和空格都会被当成另一个支付方式。
3.3 定时任务与队列
因为链上交易只能靠轮询发现，cron.php必须被系统定时器周期性执行。常见做法是每 30 秒到 60 秒跑一次，频率太低会导致订单支付后迟迟不回调，太高会让服务器频繁请求 TRON 接口然后被限流。
*/1 * * * * cd /www/wwwroot/你的域名/plugins/usdt && php cron.php >> /www/wwwroot/你的域名/plugins/usdt/cron.log 2>&1这里的运行用户要和站点运行用户一致，绝大多数 PHP 站点是www。把输出重定向到日志文件有个好处：链上接口偶发超时或 JSON 解析失败时，你翻日志能看到是哪一个环节出问题，而不是像很多站点那样傻等订单状态。
3.4 收款地址的配置边界
许多版本支持两种收款模式：
- 统一地址模式：所有订单都显示同一个 USDT 地址，靠「金额 + 自定义备注」来区分订单。
- 独立地址模式：每个订单生成一个新地址，靠地址区分订单。
如果你用的是独立地址模式，usdt_plugin.php里大概率有生成钱包地址的代码，每次下单都会调用一次tron-php的generateAddress()。这样安全性更高，但需要每天备份地址库，否则换服务器后旧地址的私钥就丢了，历史订单无法对账。多数个人站长建议用统一地址模式，省心且不容易出数据事故。
4. 核心代码逻辑与参数调优
4.1 usdt_plugin.php 的类实现
这个文件是整个插件能否被易支付识别的核心。典型的类结构如下：
class epay_usdt { public function __construct($config) { $this->config = $config; } public function pay($order) { $address = $this->getUsdtAddress($order['pid']); $amount = number_format($order['money'], 6, '.', ''); $param = [ 'address' => $address, 'amount' => $amount, 'orderid' => $order['trade_no'], 'note' => 'USDT TRC20 收款' ]; return ['type' => 'qrcode', 'data' => $param]; } public function notify($order) { // 查询链上交易是否到账 $confirmed = $this->checkTrc20Confirmed($order['trade_no']); if ($confirmed) { return ['status' => 'success', 'message' => 'ok']; } return ['status' => 'fail', 'message' => 'pending']; } }pay()方法返回qrcode类型，易支付前台核心会把这个data结构渲染为二维码。重点注意amount的处理：number_format把金额格式化为 6 位小数，这是为了和 TRC20 的 6 位精度对齐，避免后面金额比对时出现浮点误差。notify()里并不直接改订单状态，而是返回一个统一的成功标记，因为真正改状态的动作在易支付核心内部完成。
4.2 pay.php 的支付请求组装
pay.php是插件暴露给易支付核心的接收入口。它会解析订单参数，生成带收款地址和金额的二维码信息。这里有一个常见坑：TRC20 地址是以T开头的 34 位 Base58 字符串，很多插件在没有引入外部解码库时只用正则去校验：
if (!preg_match('/^T[1-9A-HJ-NP-Za-km-z]{33}$/', $address)) { throw new Exception('无效的 TRC20 地址'); }这个正则可作为第一道防线，但要注意它只保证了「看起来像一个地址」，不能保证「这个地址在 TRON 网络上真实存在」。更稳妥的做法是调用 TRONSCAN 的验证接口：
$ch = curl_init(); curl_setopt_array($ch, [ CURLOPT_URL => 'https://apilist.tronscanapi.com/api/account?address=' . $address, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5, ]); $response = curl_exec($ch); curl_close($ch); $account = json_decode($response, true); if (empty($account['address'])) { throw new Exception('TRON 地址不存在'); }这里的CURLOPT_TIMEOUT设为 5 秒比较合适。TRONSCAN 的公共 API 偶尔响应慢，超时过短容易误报地址无效，过长又会让下单页面卡住。如果插件支持填写多个钱包地址，你还可以在这里做轮询切换——查每个地址的最近交易，把流量分散到不同地址上。
4.3 cron.php 的扫块与订单匹配
cron.php的工作是找到「已付款但未标记完成」的订单。常见的实现是查数据库里交易状态为 pending 的订单，然后逐个去链上校验。它的核心函数通常是这样的逻辑：
SELECT trade_no, money, addtime FROM epay_order WHERE status = 0 AND type = 'usdt' AND addtime > UNIX_TIMESTAMP(NOW() - INTERVAL 30 MINUTE);查出最近的未完成订单后，调用apilist.tronscanapi.com/api/filter/trc20/transfers接口，按收款地址过滤最近的 USDT 转账记录：
curl -G 'https://apilist.tronscanapi.com/api/filter/trc20/transfers' \ --data 'limit=20' \ --data 'start=0' \ --data 'relatedAddress=你的钱包地址' \ --data 'contract_address=TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' \ --data 'token_name=USDT' \ --data 'direction=0'参数说明：
relatedAddress：收款钱包地址，必须和订单里的地址一致。contract_address：TRC20 USDT 的合约地址，固定是TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t，写错的话查不到任何数据。direction=0：只查转入，转账方向的账户是收款地址。limit和start：分页参数，建议limit=20就够用，扫交易时不是扫全量，只扫近 30 分钟的新增记录。
拿到转账记录后，用金额和订单号去匹配。匹配的核心逻辑建议这样写：
foreach ($transactions as $tx) { $amount = $tx['quant']; // TRONSCAN 返回值是 6 位整数 $decimals = 6; $realAmount = $amount / pow(10, $decimals); foreach ($pendingOrders as $order) { if (bccomp((string)$realAmount, (string)$order['money'], 6) === 0) { // 标记订单为已支付 $order->update(['status' => 1, 'trade_no' => $order['trade_no']]); } } }关键点在于bccomp。PHP 的浮点数0.1 + 0.2 === 0.3是false，如果你直接用==比较金额，会出现「客户转了 10 USDT，插件却说金额不匹配」的诡异问题。bccomp把两个金额当字符串比较，就不会有二进制浮点误差。
4.4 参数调优建议
| 参数 | 默认值建议 | 调整方向 |
|---|---|---|
| 扫描间隔 | 60 秒 | 带宽裕余缩短到 30 秒，用户体验更接近实时到账 |
| 确认区块数 | 2 到 19 | 小额单 2 个区块即可；大额超过 500 USDT 建议 19 个区块再确认 |
| 金额精度 | 6 | 不要改，改了和链上对不上 |
| TRONSCAN 超时 | 5 秒 | 频繁出现超时时调到 10 秒，但会拖慢下单页面 |
| 订单过期时间 | 30 分钟 | 链上超时未付款的订单状态置为已取消 |
确认区块数是个权衡：设大了安全性高但用户等得急；设小了秒到但极端情况下可能遇到网络重组。TRON 是 DPoS 共识，出块速度约 3 秒一个，2 个区块确认大约 6 秒，日常小额收款完全够用。
5. 上线前的验证清单与两个高频坑
5.1 用一笔小额转账跑通全链路
上线前不要直接拿大额测试。从插件后台看下有没有「测试模式」或「模拟回调」按钮，没有的话就自己转一笔，比如 1.5 USDT（带小数，能顺带验证精度处理是否正常）。
测试时要盯三个位置：
- 下单页面：二维码能不能正常渲染，地址是不是你的钱包地址。
- 链上浏览器：在 TRONSCAN 上搜该地址，确认这笔交易已经出现，且
tokenName是 USDT。 - 后台订单列表：订单状态在 30 到 90 秒内（取决于你的 cron 间隔）变成「已支付」。
如果订单状态一直不变，优先看cron.php的日志输出。多数插件的cron.php会记录「最近一次执行时间」和「最近一次查询到的交易数」，这两个值能快速定位问题：
- 日志里没有「最近一次执行时间」，说明 cron 没跑起来，检查系统定时器里的 PHP 路径和运行用户。
- 有执行时间但查到的交易数一直是 0，说明链上查询接口挂了或
contract_address填错。 - 查到交易但匹配不到订单，多半是金额精度问题，检查日志里的
$realAmount和订单金额的对比结果。
5.2 坑一：ERC20 地址冒充 TRC20
很多用户会把以太坊上0x开头的地址或交易所充值页面的「网络选择」看错，直接往 TRC20 收款地址发了一笔 ERC20 的 USDT。这个插件本身解决不了这个问题，但你有两个补救手段：
- 在支付页明显位置标注「仅支持 TRC20 网络，请勿使用 ERC20 或其他网络转账，否则无法到账」。
- 在
usdt_plugin.php的支付接口生成二维码时，附带一个network=trc20的备注信息，这样即使用户扫码后误选网络，至少有个参照。
5.3 坑二：cron 重复标记订单
轮询机制的天然风险是同一瞬间跑两个cron.php进程，把同一笔订单标记两次。虽然不会造成实际财产损失，但订单表里可能出现重复的状态更新记录，影响对账。防御做法是给订单加一个「处理中」状态锁：
UPDATE epay_order SET status = 1, paytime = NOW() WHERE trade_no = '订单号' AND status = 0;用UPDATE后检查受影响行数，如果行数为 0 说明订单已经被其他进程处理过了，放弃本次操作。这比先SELECT再UPDATE安全得多，因为它是原子操作。
最后提一个运维细节：如果你把确认区块数设得比较大（比如 19），用户看到「已支付」时的实际到账时间会延长到 1 分钟左右。此时不要在前台提示「支付失败」，而是提示「支付确认中」，否则用户会以为钱丢了，转头去提工单。确认中状态的订单建议在后台单独一个列表展示，方便你自己盯。
本文还有配套的精品资源，点击获取
)
