简介这是一款面向彩虹易支付系统的 USDT-TRC20 收款插件适合需要接入稳定币支付、且希望绕过第三方代收环节的个人站长、开发者或中小商户。插件安装后会在易支付后台新增一种支付方式调用值设为 usdt支持 PC 与 Mobile 双端收到的 USDT 直接进入收款方自有钱包资金链路更透明可有效降低对第三方资金托管环节的依赖。资源包共 5 个文件以 PHP 功能源码为主另含 README 使用说明与 LICENSE 协议文件整体约 7KB轻量易部署目前已有 759 人学习浏览。通过该插件可快速理解易支付第三方支付平台的插件扩展机制并获得符合原版彩虹易支付调用规范的完整源码便于个人学习、二次开发、自用收款环境搭建等场景注意按作者声明仅限学习研究使用请勿用于商业或非法用途。1. 彩虹易支付加USDT-TRC20通道这不是“写个插件”是补一条完整的收款链路拆这个标题的人多半手里已经跑着一套彩虹易支付想在收款列表里多一个“USDTTRC20”选项。真动手后你会发现难点根本不在支付页放一个二维码而在于让TRC20链上的转账自动变成订单里的“已支付”再把结果用彩虹的协议回传。所以这个标题背后是一整条链路地址生成、链上监听、订单匹配、回调签名缺一环都会让用户付了款却收不到货。适合谁手里有彩虹易支付源码、或正在给独立站/出海业务加USDT通道的开发者。读完你可以跑起一个最小可用版本再决定要不要上生产。2. 收款方案选型单地址、memo、多地址以及轮询节点的稳定性2.1 单地址memo识别用户还是每笔订单一个地址做USDT收款第一件事不是写代码是选地址模型。两套主流做法单地址加memo和每笔订单一个独立地址。单地址加memo的意思是你的收款服务就一个TRC20地址用户转账时在备注memo里填订单号监听脚本靠memo匹配订单。优点非常明显——地址管理成本为零热钱包地址只有一个私钥只备份一次。但缺点在用的是真实用户时会暴露不少主流钱包的TRC20转账界面根本不显示备注输入框或者用户根本没意识到要填。一旦memo缺失或填错链上到账了你的监听脚本看着一串转账记录却不知道属于谁只能人工介入去核查订单状态卡在待支付用户投诉“我付了”就来了。每笔订单一个地址是当前做USDT代收更稳的方案。订单创建时用助记词派生一个新地址展示给用户监听脚本只需要认“钱到了哪个地址”。因为地址和订单强绑定匹配逻辑就退化成一条SQL查这个地址有没有未支付订单。付出的代价是私钥管理变重、地址数量大、需要有一个稳定的派生和记账机制。还有一个隐藏收益即使memo没填、填错只要地址对订单就能确认客服成本低很多。维度单地址 memo每笔订单一个地址地址管理简单需要派生与归档用户操作依赖备注字段只看地址扫码订单匹配易漏单、易错配地址即订单ID私钥风险单点暴露助记词统一管理推荐场景小额、低频、内部转账对外商户收款、自动化要求高我自己的项目选的是“每笔订单一个地址”。理由很直接省下的地址管理成本远低于漏单和客服扯皮的成本。后面所有代码都按这个模型写。2.2 轮询TronGrid还是自建节点稳定性优先确定了地址模型下一步是怎么拿到链上交易。TRON这套链提供TronGridTRON官方的公共API服务也有WebSocket事件订阅能力。很多第一次做的人会直接去连WebSocket因为“实时、不用一直拉”但实际生产里它让人相当头疼断线重连要自己实现心跳超时没人管多个订阅通道还要分散维护。与其赌长连接的稳定性不如回到最朴素的轮询。我一般会用一个同步节点或TronGrid的HTTP接口每3秒拉一次最新区块高度然后逐个扫新增区块里有没有TRC20的Transfer事件。TRON的出块速度约3秒一个所以轮询间隔设3秒不会漏块网络偶发延迟时再补一次拉取。轮询虽然看起来“笨”但状态全部由自己控制游标存本地重启不丢网络断了下次继续从断点扫。自建节点也可以但那是另一个成本等级归档节点同步两天起步磁盘占用数百G维护起来比写监听脚本费劲得多。你的项目如果一天订单不到几百笔TronGrid的免费额度完全够用单日几千笔再考虑自建或托管节点。这个选型决定了你能把精力留在订单逻辑上而不是跟节点同步较劲。2.3 把支付流程串起来从扫码到自动完成把两件事连起来看整个流程是这样的用户在你的站点下单彩虹易支付生成一笔待支付订单系统把这笔订单映射到一个新生成的TRC20地址用户用任意支持TRC20的钱包扫码向这个地址转USDT你的监听服务扫到这笔转账校验到账地址、金额、确认数确认后把订单标记为已支付同时模拟支付平台向彩虹易支付发起异步通知彩虹收到通知后再按自己的逻辑最终确认订单并回传给商户。这个链路里最容易写错的是顺序必须先链上确认再通知彩虹绝不能“先通知后确认”。因为通知出去订单就变成已支付了发货动作可能立刻触发。链上转账可能有孤儿块、可能短暂确认又被回滚你等不到足够确认数就把订单置为已支付后面回滚一次就产生一笔坏账。所以务实做法是转账进入本地库后先标记“待确认”达到确认阈值后再推通知。3. 搭一套可跑的TRC20监听服务地址生成、扫块、确认入账3.1 用tronpy生成收款地址私钥别进数据库生成地址是整个方案的起点。使用Python的tronpy库可以很快生成Tron地址和对应私钥。生产环境我不会拿一个在线工具去生成而是在离线环境跑下面这段# pip install tronpy from tronpy.keys import PrivateKey import json, os # num 表示一次生成多少地址建议批量生成后加密归档 num 20 keys [] for _ in range(num): priv PrivateKey.random() addr priv.public_key.to_base58check_address() keys.append({ address: addr, private_key: priv.hex(), }) # 注意私钥绝不写进数据库只写入加密文件权限设为 600 with open(usdt_keys.json, w) as fp: json.dump(keys, fp, indent2) os.chmod(usdt_keys.json, 0o600) print(生成完成地址示例, keys[0][address])这段代码生成的是“裸”私钥地址不是HD派生。如果订单量大建议改用BIP39助记词派生用path区分订单号。生成后的私钥要离线保存最好再拆成多份加密备份程序运行时只需要把目标地址列表加载到内存。私钥进数据库是这个方案最危险的做法一旦库被拖走资金全没了。3.2 写一个轮询扫块的监听脚本监听脚本的核心是一个死循环拿最新块号从上次扫到的块号开始逐个拉块解析TRC20转账日志。下面是一个可运行的最小骨架以TronGrid为例# listen_trc20.py import time, requests from tronpy import Tron from tronpy.providers import HTTPProvider API_KEY your_trongrid_api_key # 可去TronGrid官网申请免费key client Tron(HTTPProvider(api_keyAPI_KEY, endpoint_urlhttps://api.trongrid.io)) # USDT-TRC20 的合约地址是公开固定的 USDT_CONTRACT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t # 你的收款地址白名单程序启动时从 DB 或配置文件加载 my_addresses { TJ...: 1001, # 格式: 收款地址 - 订单ID } last_block 0 # 首次跑建议先记录当前块号之后每次写入文件/DB def process_block(block_num): block client.get_block(block_num) for tx in block[transactions]: # 只看合约调用和日志字段普通转账跳过 raw tx.get(raw_data, {}).get(contract, []) for contract in raw: if contract.get(type) ! TriggerSmartContract: continue logs tx.get(raw_data, {}).get(log, []) for log in logs: if log.get(address) ! USDT_CONTRACT: continue topics log[topics] if len(topics) ! 3: continue # topics[0] 是 Transfer 事件签名1/2是from/todata是金额 # TRON日志里的地址是 0x 格式需要转回 Base58 from_hex 41 topics[1][-40:] to_hex 41 topics[2][-40:] # 这里用 tronpy 的地址转换工具 to_addr client.to_base58check_address(to_hex) if to_addr in my_addresses: amount_raw int(log[data], 16) / 1_000_000 # USDT为6位小数 order_id my_addresses[to_addr] # 进入落库/确认流程见 3.3 print(订单, order_id, 收到, amount_raw, USDT) while True: latest client.get_latest_block_number() while last_block latest: try: process_block(last_block 1) last_block 1 except Exception as e: print(扫块失败稍后重试, e, 当前块, last_block) time.sleep(3) break # 持久化 last_block防止进程挂掉后重复扫或漏扫 time.sleep(3)逻辑说明last_block是游标必须持久化到文件或数据库很多线上事故都是因为游标没存住导致重启后从旧块扫起重复处理了一堆老交易。amount_raw换算成“元”单位的USDT时除以1_000_000因为USDT-TRC20是6位小数。这里打印日志只是示意真正要做的是幂等落库。3.3 把确认结果落库并触发后续流程监听到转账只是一半还要把转账变成“订单已支付”。关键是落库表和触发时机。我习惯建一个trc20_records表CREATE TABLE trc20_records ( id BIGINT PRIMARY KEY AUTO_INCREMENT, order_id INT NOT NULL, txid VARCHAR(100) NOT NULL UNIQUE, -- 唯一索引防重复入账 from_address VARCHAR(64) NOT NULL, to_address VARCHAR(64) NOT NULL, amount DECIMAL(18,6) NOT NULL, confirmations INT DEFAULT 1, status TINYINT DEFAULT 0, -- 0待确认 1已确认 2已通知 created_at DATETIME DEFAULT CURRENT_TIMESTAMP, confirmed_at DATETIME NULL );监听脚本在解析到目标转账后先执行INSERT IGNORE靠txid唯一索引挡住重复扫块带来的重复入账。插入成功后检查这笔转账的确认数。TRON出块快一般等1个块约3秒就已经很稳保守的项目等6个块也就20多秒大额订单可以动态提高确认数阈值。确认数满足后把订单状态更新为已支付然后才进入第4章的彩虹通知流程。如果发现同一地址收到了多笔转账按“金额精确匹配且只确认一次”处理多余的金额记成客户余额。这一步不做后面对账一定是糊涂账。4. 把确认结果回传给彩虹易支付验签、金额与状态顺序4.1 彩虹异步通知的参数与签名结构彩虹易支付的第三方通道接入核心就是异步通知支付平台把支付结果以POST方式发给彩虹的接口彩虹验签后更新自己的订单。我们做USDT插件就是扮演那个“支付平台”。通知参数的常见结构包括商户IDpid、平台订单号trade_no、商户订单号out_trade_no、支付方式type、商品名name、金额money、状态trade_status以及附加参数param和签名sign。不同版本字段名可能有差异接的时候以你手里的彩虹源码为准但签约方式是通用的按参数名字典序拼接最后拼上商户密钥然后取MD5。调通这个回调就相当于告诉彩虹“这笔订单已经被这个支付方式完成了”。下面这段Python代码演示如何构造一次通知并生成彩虹能认的签名。# notify_rainbow.py import hashlib, requests, time # 和你彩虹后台配置保持一致 PID 1001 KEY 你的商户密钥 NOTIFY_URL https://你的彩虹域名/pay/usdt/notify.php def md5_sign(params: dict, key: str) - str: # 字典排序后拼接: k1v1k2v2... 再拼 key items .join(f{k}{params[k]} for k in sorted(params)) return hashlib.md5((items key).encode()).hexdigest() def send_notify(out_trade_no, money, trade_no): params { pid: PID, trade_no: trade_no, out_trade_no: out_trade_no, type: usdt, name: USDT-TRC20, money: f{money:.2f}, trade_status: TRADE_SUCCESS, param: , # 下单时透传的参数原样带回 } params[sign] md5_sign(params, KEY) resp requests.post(NOTIFY_URL, dataparams, timeout10) print(通知返回, resp.text) # 示例确认订单 20240301 收到 100.00 USDT 后调用 send_notify(20240301, 100.00, USDT20240301XXXX)注意金额格式化用两位小数。彩虹侧记录的订单金额一般也是元、保留两位如果你直接f{amount:.6f}发过去签名和你库里金额算法不一致彩虹会出现“验签通过但金额对不上”的诡异状态这是高频翻车点。4.2 金额、币种、地址三重校验回调脚本收到通知后彩虹会按它自己的逻辑处理但你的监听服务在发起通知前必须做三重校验。一是目标地址是系统生成的订单地址二是实际到账金额必须等于订单应付金额允许误差为0除非你明确开通了“多付补余额”功能三是确认数达标。订单金额在创建时就应存入订单表和地址绑定。监听脚本匹配到转账后先查订单金额再和链上amount_raw比较。因为USDT是6位小数订单金额如果是100元链上就是100.000000如果用户少转了0.000001你都应该按“金额不匹配”处理而不是直接置为已支付。少一分钱宁可卡住等人工干预也不要因为“差不多”把单放了这种财务口径问题在结算时最吃亏。4.3 用状态机保证顺序先入账再通知再发货我在3.3的订单状态里加了status0待确认 /1已确认 /2已通知这个状态机看着简单却解决了真实的大麻烦通知发出去后彩虹会回调商户商户那边就去发货了。如果监听脚本因为网络抖动重发通知彩虹又没做幂等就可能重复发货。所以通知动作必须满足两个条件一笔订单只发一次通知只有状态从“已确认”变成“已通知”的那个线程能发其余请求要么直接退出要么等状态。代码里用UPDATE trc20_records SET status2 WHERE order_id? AND status1判断影响行数只有影响行数为1的才继续发通知。这一步能在数据库层面挡住绝大多数重复发货。另外通知要带重试机制彩虹接口偶发5xx发送失败需要把状态回滚到status1留一个定时任务每5分钟补发未通知的订单。很多“用户付了钱但商户不知道”的工单都是通知发了一次失败后没重试导致的。5. USDT-TRC20收款高频踩坑从“没到账”到“重复通知”5.1 用户转错链或转错合约订单永远等不到完成现象用户说付了但监听服务完全没反应订单一直待支付。去区块链浏览器查链上确实有一笔转账但转账地址或代币对不上。原因用户把ERC20的USDT转到TRC20地址或转了其他链的同名代币有些钱包默认走的是BSC、Polygon用户没切网络。这类错误基本无法自动识别钱大概率需要找平台客服协调退回成本极高。解决在收款页用醒目的方式展示“仅支持TRC20网络不支持其他链”。地址旁边放一个复制按钮而不是让用户手输手输最容易缺字符。同时监听脚本可以额外监控常见的错误链比如BSC上的同名合约发现转账及时提示用户填工单而不是默默等。5.2 新地址第一次收USDT正常转出却说带宽不足现象新生成的收款地址收到第一笔USDT很顺利但你想把这笔钱归集到冷钱包时交易反复失败报带宽或能量不足。原因TRC20转账需要消耗一定TRX作为带宽/能量费用新地址里没有TRX无法支付手续。收款不需要手续费转出才需要。很多人以为地址里不需要留TRX结果归集时卡住。解决生成地址并充入少量TRX比如几十TRX作为“激活手续费”或者用冷钱包直接导入这些地址签名广播。更省事的做法是每批次生成的地址先统一注入一笔小额TRX记账成本摊到每一笔收款里。5.3 监听服务重启后漏单或重复入账现象服务半夜重启了一下第二天发现有两笔订单没确认或者同一笔转账在数据库里出现两条记录给彩虹通知了两次。原因last_block游标没有持久化重启后从0开始扫或者从内存里丢掉的块号继续扫导致漏块落库时没有唯一索引重复扫块又把老交易再插一遍。解决游标每次扫完写库或写文件启动时先读游标不读就算初始化当前最新块并记录下来。落库SQL加UNIQUE KEY(txid)用INSERT IGNORE或ON DUPLICATE KEY UPDATE confirmationsVALUES(confirmations)处理重复。这个坑几乎人人会踩先做防重复再谈其他。5.4 确认数设太高用户等得不耐烦现象区块里看到转账了但订单状态要过一两分钟才变。用户等得着急反复刷新甚至去群里问“为什么付了没到账”。原因监听脚本把确认数设成了19个块甚至更多按3秒一个块算光确认就要快1分钟加上扫块延迟用户体验很差。解决默认1个块确认足够USDT-TRC20这条链没有像比特币那样的长重组风险1~2个块已经是工程上限。只对超大额订单动态提升确认阈值。同时前端付款页轮询订单状态每2秒一次一旦确认立刻刷新减少人工刷新造成的“怎么还没好”反馈。5.5 回调签名不符精度和编码的锅现象监听脚本确认了转账也发了通知但彩虹那边一直不更新订单日志里验签失败。原因常见是三件事——金额保留小数不一致链上100.000000通知发100.00签名拼接时字段排序不一致或者字符串编码不是UTF-8中文参数出现乱码。解决在彩虹的验签函数里临时打印收到的参数和本地算出的签名逐字段比对。金额统一格式化成两位小数参数名按字典序排序所有字段encode(utf-8)后再拼接。还有一个隐蔽点彩虹的SDK如果对sign也参与排序你要先剔除sign字段再签名否则永远对不上。6. 进阶离线签名、定期归集、对账脚本让系统敢放大额6.1 每天跑一次对账脚本检查孤儿交易和漏单上线后我每天会跑一遍对账扫链上所有进过这个批次地址的USDT转账跟本地trc20_records表做全量比对。重点查两类数据一是本地没有对应订单的“孤儿交易”用户转了但系统没认多半是金额不符或地址映射丢了二是本地标记已支付但链上核对不到的交易可能确认数没达到就通知了。对账脚本不需要复杂拉API数据和本地明细放内存比对半小时内跑完即可。6.2 热钱包只留零头定期归集监听服务跑在服务器上私钥暴露面越大风险越高。我的习惯是所有收款地址的私钥在离线环境统一管理线上只保留地址列表和确认逻辑每天把热钱包地址收到的USDT归集到冷钱包热钱包只留够用户退款用的零头。归集也是TRC20转账需要冷钱包地址里有TRX做手续费所以我每次归集前先估算所需TRX从冷钱包反向打一点给热钱包再执行批量归集。6.3 冷钱包离线签名大额资金不碰热容器归集到冷钱包也不能真的“永不触碰”。真正让我放心的是离线签名流程在无网络的机器上导入冷钱包私钥构造好未签名的交易用U盘把签名后的交易带到线上节点广播。这样即使线上服务器被攻破攻击者也拿不到冷钱包私钥最坏情况只是热钱包的零头被转走。第一次做这套时我图省事把冷钱包私钥也导进了线上服务器的Python环境里后来想想当时真是在赌运气。后面所有大额地址的私钥都不进任何联网容器资金安全才算真正交到自己手里。这整套方案从地址生成到归集走完前期花最多时间的一定不是写代码而是把“什么时候确认、什么时候通知、什么时候归集”这几个财务节点想清楚。踩过的坑基本都集中在边界条件启动时游标没了、金额差一位小数、地址转错了格式。只要把幂等和确认边界守住这套USDT-TRC20收款链路能做得很稳。希望帮到你。本文还有配套的精品资源点击获取