简介这是一套面向区块链支付开发者的USDT跑分支付系统完整源码适合想研究数字货币收款、API监听回调与三级分销机制的中高级开发者也可作为创业团队搭建支付平台的参考底稿。压缩包共约2000个文件整体40.69MB以609个js脚本、148个php后端逻辑、174个html页面、165个css样式为主另含8个sql建表脚本、104个json配置、154个md说明文档及若干图片与字体资源前后端与数据库结构基本齐全。系统核心围绕USDT支付请求的API监听与自动回调展开交易状态变化时主动通知业务端省去轮询开销三级分销模块负责记录推荐关系并逐层计算佣金。源码完整呈现了数据库连接、接口定义、安全防护与分销逻辑读者可据此理解支付系统架构学习异步回调、并发事务处理与防注入等实践要点。目前已有959人学习下载。1. USDT 支付回调系统从「手动查单」到「链上事件驱动」的落地拆解做交易所周边工具或者数字商品自动发货的团队几乎都绕不开一个场景用户用 USDT 转账系统要自动确认到账、自动发货、自动给上级分佣。早期很多团队靠人工查单运营盯着区块浏览器刷新用户催一句查一次日订单过百就彻底崩了。后来大家开始做 API 监听自动回调核心思路是让程序订阅链上事件一旦检测到目标地址的入账立刻触发业务回调把「确认到账」这件事从人工变成事件驱动。这个方向适合三类人一是做数字商品自动发货的开发者二是需要给多级代理自动分佣的平台方三是想理解链上监听与业务回调如何解耦的工程师。标题里提到的「三级分销」不是营销噱头它本质是一套分佣计算模型难点在于回调触发后如何保证分佣只算一次、层级不串、金额不丢精度。下面按「链上监听怎么选 → 回调怎么设计 → 分佣怎么算 → 坑在哪」的顺序拆开讲能直接照着搭一套最小可跑的系统。2. 链上监听方案选型轮询、WebSocket 与第三方 API 的取舍2.1 三种监听方式的真实差异链上监听 USDT 入账常见做法有三种定时轮询节点 RPC、订阅节点 WebSocket 事件、接入第三方索引 API。很多人一上来就想用 WebSocket觉得实时性最好但实际落地时节点断连、事件漏推、重组回滚这些问题会让回调系统变成黑匣子出了问题很难排查。轮询 RPC 的方式最笨但最稳。以 TRC20-USDT 为例通过triggerconstantcontract或者直接查账户的 TRC20 转账记录接口按区块高度递增拉取每次记录 last_scanned_block下次从上次高度继续。缺点是延迟取决于轮询间隔通常 3 到 10 秒一次比较合理再快会触发节点限流。优点是状态完全可控漏了能补回滚能重扫。WebSocket 订阅适合对延迟极敏感的场景比如秒级到账提醒。但要注意节点推送的事件不保证顺序也不保证不重复必须自己做去重和幂等。第三方索引 API 比如常见的区块链数据服务省去了自己维护节点的成本但免费额度通常有限商用要评估调用量和稳定性而且不同链的接口规范不统一切换成本高。我一般会这样组合主链路用轮询保证不漏辅链路用 WebSocket 做低延迟提醒两者结果做交叉校验。下面是一个轮询扫描的最小实现。import time import requests RPC_ENDPOINT https://api.trongrid.io # 节点或索引服务地址 USDT_CONTRACT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t # TRC20-USDT 合约 TARGET_ADDRESS 你的收款地址 SCAN_INTERVAL 5 # 秒 CONFIRM_BLOCKS 19 # 建议确认区块数 def get_trc20_transfers(min_block, max_block): 拉取指定区块区间内发往目标地址的 USDT 转账 url f{RPC_ENDPOINT}/v1/accounts/{TARGET_ADDRESS}/transactions/trc20 params { limit: 200, min_timestamp: min_block, max_timestamp: max_block, contract_address: USDT_CONTRACT, only_to: true } resp requests.get(url, paramsparams, timeout10) resp.raise_for_status() return resp.json().get(data, []) def scan_loop(): last_ts int(time.time() * 1000) - 60000 # 从一分钟前开始 while True: now_ts int(time.time() * 1000) transfers get_trc20_transfers(last_ts, now_ts) for tx in transfers: # 只处理确认数足够的交易 confirm tx.get(confirmations, 0) if confirm CONFIRM_BLOCKS: continue handle_callback(tx) # 触发业务回调 last_ts now_ts time.sleep(SCAN_INTERVAL)这段代码的关键参数有三个SCAN_INTERVAL控制轮询频率太小会被限流太大延迟高CONFIRM_BLOCKS是确认区块数TRON 上一般等 19 个块再确认比较稳妥太少可能遇到回滚only_to过滤只保留入账方向减少无效数据。last_ts用时间戳而不是区块高度是因为部分索引服务按时间过滤更稳定但要注意时间戳边界可能重复所以handle_callback里必须做幂等。2.2 确认数、回滚与「到账」的定义很多人把「交易上链」当成到账这是最大的误区。链上交易在确认数不足时可能因为分叉被回滚尤其是 TRON 这种出块快的链表面看几秒就确认实际最终确定性要等十几个块。我的做法是分两阶段检测到交易先标记为「待确认」写入数据库但不触发发货确认数达标后再触发回调。这样即使回滚也只是把待确认记录删掉不会造成已发货却钱没了的翻车。确认数怎么定TRON 官方建议 19 个块BSC 一般 15 个以太坊主网 12 个起步。实际还要看金额大额可以多等几个块。这个参数不要写死在代码里放到配置表不同链不同币种分开配。提示确认数不是越高越好太高会让用户等太久体验差太低有回滚风险。按链的最终确定性时间乘以 1.5 倍来估比较稳。3. 回调接口设计幂等、重试与签名验证3.1 回调触发的三种时机与幂等保证回调不是「检测到就发」而是要设计触发时机。常见三种检测到交易立即回调、确认数达标后回调、人工审核后回调。自动发货场景一般用第二种兼顾速度和安全性。但无论哪种回调必须幂等因为轮询可能重复拉到同一笔交易WebSocket 可能重复推送网络重试也可能重复调用。幂等的实现靠唯一键。每笔链上交易有唯一的 txid用 txid 作为业务侧的唯一约束回调前先查库存在就跳过。数据库层面加唯一索引插入冲突直接忽略。下面是一个带幂等和签名的回调发送示例。import hashlib import hmac import json import requests CALLBACK_SECRET 你的回调密钥 def build_signature(payload: dict, secret: str) - str: 按 key 排序后拼接再 HMAC-SHA256防止参数被篡改 raw .join(f{k}{v} for k, v in sorted(payload.items()) if k ! sign) return hmac.new(secret.encode(), raw.encode(), hashlib.sha256).hexdigest() def send_callback(order_id, txid, amount, callback_url): payload { order_id: order_id, txid: txid, amount: str(amount), # 金额用字符串避免浮点精度丢失 timestamp: int(time.time()) } payload[sign] build_signature(payload, CALLBACK_SECRET) # 重试三次指数退避 for attempt in range(3): try: resp requests.post(callback_url, jsonpayload, timeout5) if resp.status_code 200 and resp.json().get(code) 0: return True except requests.RequestException: pass time.sleep(2 ** attempt) return False这里有两个容易忽略的点。一是金额必须用字符串传输USDT 有 6 位小数用 float 会在累加分佣时出现精度误差最后对不上账。二是签名要覆盖所有业务参数接收方验签后再处理防止伪造回调。重试策略用指数退避避免回调方短暂故障时把请求打爆。3.2 回调失败后的补偿与对账回调不可能 100% 成功接收方宕机、网络抖动、接口超时都会失败。必须有补偿机制。我的做法是回调记录落库状态分「待发送、成功、失败」失败的任务进重试队列超过重试次数进人工对账列表。同时每天跑一次全量对账把链上入账记录和业务订单做比对找出「链上有钱但没发货」和「发了货但链上没记录」两类异常。对账的粒度按 txid 对齐金额允许极小误差比如 0.000001超出就告警。这一步是后悔药平时看不出价值出问题时能救命。注意回调接口不要同步等业务处理完再返回接收方应该先落库再异步处理否则链上监听方会被慢接口拖死。4. 三级分销的佣金计算层级、比例与精度处理4.1 分佣模型的数据结构三级分销的核心是「谁推荐了谁」的关系链。常见存储方式是用户表里存parent_id形成树。计算佣金时从下单用户往上找三级分别按配置比例分佣。关系链一旦确定不要轻易改否则历史订单的分佣会乱。下面是一个简化的分佣计算。from decimal import Decimal, ROUND_DOWN # 分佣比例配置按层级 COMMISSION_RATES { 1: Decimal(0.10), # 一级 10% 2: Decimal(0.05), # 二级 5% 3: Decimal(0.02), # 三级 2% } def calc_commission(order_amount: Decimal, user_chain: list): order_amount: 订单金额Decimal 类型 user_chain: 从下单用户往上三级的用户ID列表如 [u1, u2, u3] 返回: [(user_id, amount), ...] result [] for level, user_id in enumerate(user_chain, start1): if level 3 or user_id is None: break rate COMMISSION_RATES.get(level) if not rate: continue # 向下取整到 6 位小数避免分佣总额超过订单金额 amount (order_amount * rate).quantize(Decimal(0.000001), roundingROUND_DOWN) result.append((user_id, amount)) return result关键在Decimal和ROUND_DOWN。用浮点数算分佣累加后可能比订单金额还多平台倒贴。向下取整保证分佣总额不超过订单金额差额归平台。比例配置放数据库支持按活动调整但调整只影响新订单历史订单按当时快照算。4.2 分佣的触发时机与防重复分佣必须在订单确认到账后触发且只触发一次。触发点放在回调处理成功之后用订单号做唯一约束。如果回调重试导致重复触发靠唯一索引挡住。分佣记录要落库包含订单号、层级、用户、金额、状态方便对账和提现。还有一个坑是「关系链变更」。如果用户在订单产生后改了推荐关系分佣按哪个算我的做法是下单时快照关系链存到订单表分佣时用快照不用实时关系。这样即使后续关系变了历史订单不受影响。提示分佣金额和提现余额要分开记分佣是「待结算」提现时才扣减中间可以加冻结期防止刷单套佣。5. 避坑与排查回调系统最常见的 5 个翻车点5.1 现象同一笔交易触发多次发货原因轮询重复拉到同一 txid或 WebSocket 重复推送回调没有幂等。解决用 txid 做唯一索引回调前查库存在就跳过数据库插入用INSERT IGNORE或ON CONFLICT DO NOTHING。5.2 现象确认数够了但交易被回滚钱没了货发了原因确认数设置太低或用了「交易上链」而非「最终确定性」作为到账标准。解决提高确认数到链的最终确定性标准分两阶段处理待确认不发货达标才回调。5.3 现象分佣金额累加后超过订单金额原因用 float 计算精度丢失或比例之和超过 100%。解决全程用 Decimal向下取整比例配置做校验三级之和不超过 100%。5.4 现象回调接口超时监听方以为失败一直重试原因接收方同步处理业务逻辑太慢接口响应超过监听方超时时间。解决接收方先落库立即返回业务异步处理监听方重试用指数退避设最大次数。5.5 现象节点限流导致扫描中断漏单原因轮询间隔太短或单次拉取数据量太大。解决间隔不低于 3 秒分页拉取记录 last_ts 断点续扫失败后从断点恢复而不是从头扫。6. 进阶技巧用对账任务兜底与灰度验证回调链路系统上线后最怕的是「以为没问题」。我一般会加一个每日对账任务把链上入账和业务订单做全量比对输出三类结果匹配、链上有单无、单有链上无。匹配的正常链上有单无说明漏回调需要补发单有链上无说明可能伪造或数据错乱需要人工介入。对账任务用定时调度结果推送到告警群。灰度验证回调链路也很重要。新接入的收款地址先跑小额比如 1 USDT走完整链路监听 → 确认 → 回调 → 分佣 → 发货。确认无误再放大额。回调接收方可以先做一个 mock 接口只记录不处理验证签名和幂等逻辑再切到真实业务。def daily_reconcile(start_ts, end_ts): 每日对账链上入账 vs 业务订单 onchain fetch_onchain_transfers(start_ts, end_ts) # 链上记录 orders fetch_paid_orders(start_ts, end_ts) # 业务已支付订单 onchain_txids {tx[txid] for tx in onchain} order_txids {o[txid] for o in orders} missing_callback onchain_txids - order_txids # 链上有单无 fake_order order_txids - onchain_txids # 单有链上无 if missing_callback: alert(f漏回调 {len(missing_callback)} 笔需补发) if fake_order: alert(f异常订单 {len(fake_order)} 笔需人工核查)对账的窗口按天跑时间范围用链上区块时间对齐避免时区问题。补发操作要幂等补发前再查一次订单状态防止重复发货。这套兜底机制跑顺之后回调系统的可靠性会从「靠运气」变成「可度量」。我自己踩过最深的坑是早期没做对账某次节点升级导致漏扫了三个小时的交易用户投诉才发现。从那以后任何回调系统我都先搭对账再上线。希望帮到你。本文还有配套的精品资源点击获取