一个完整的虚拟币支付解决方案，支持 TRC20 网络的 USDT 支付。可以轻松集成到 Telegram Bot、Discord Bot 等应用中。
- ✅ 订单生成：自动生成支付订单和二维码
- ✅ 自动监控：实时监控区块链交易，自动确认收款
- ✅ 订单管理：查询订单状态、用户订单列表、统计数据
- ✅ 回调机制：支付成功、订单超时等事件的自定义回调
- ✅ 手动退款：不暴露私钥的安全退款管理
- ✅ 线程安全：支持多线程并发处理
- ✅ 易于集成：提供完整的 Telegram Bot 和 Discord Bot 示例
git clone https://github.com/yourusername/tron_payment.git
cd tron_paymentpip install -r requirements.txt复制配置文件并填入你的信息：
cp config_example.py config.py编辑 config.py，填入你的 TRON 地址和 TronScan API Key：
TRON_WALLET_ADDRESS = "TYourWalletAddressHere"
TRONSCAN_API_KEY = "your-tronscan-api-key"from tron_payment import TronPayment
# 初始化支付系统
payment = TronPayment(
wallet_address="TYourWalletAddress",
tronscan_api_key="your-api-key",
poll_interval=15, # 15秒检查一次
default_timeout=30 # 订单30分钟超时
)
# 设置回调函数
def on_payment_received(order_id, order_info):
print(f"收到支付: {order_id}, 金额: {order_info['amount']} USDT")
# 在这里解锁用户功能
payment.set_callback('payment_received', on_payment_received)
# 创建订单
order = payment.create_order(
user_id="user123",
amount_usdt=10.5,
timeout_minutes=30,
notes="购买 VIP 会员"
)
print(f"订单 ID: {order['order_id']}")
print(f"支付地址: {order['wallet_address']}")
print(f"支付 URI: {order['pay_uri']}")
# 保存或发送二维码
order['qr_code'].save('payment_qr.png')
# 查询订单状态
status = payment.get_order_status(order['order_id'])
print(f"订单状态: {status['status']}")
# 系统会自动监控支付，支付成功后会调用回调函数| 状态 | 说明 |
|---|---|
pending |
等待支付 |
paid |
已支付 |
timeout |
已超时 |
cancelled |
已取消 |
refunded |
已退款 |
payment = TronPayment(
wallet_address: str, # 收款地址
tronscan_api_key: str, # API Key
db_path: str = 'orders.db',
poll_interval: int = 15, # 轮询间隔（秒）
default_timeout: int = 30, # 默认超时（分钟）
min_confirmations: int = 1 # 最小确认数
)order = payment.create_order(
user_id: str, # 用户 ID
amount_usdt: float, # USDT 金额
timeout_minutes: Optional[int], # 超时时间（分钟）
notes: str = "" # 订单备注
)返回：
{
'order_id': str, # 订单 ID
'qr_code': BytesIO, # 二维码图片
'pay_uri': str, # 支付 URI
'amount': float, # 金额
'wallet_address': str, # 收款地址
'timeout_at': datetime, # 过期时间
'memo': str, # 备注
'usdt_contract': str # USDT 合约地址
}# 查询单个订单
order = payment.get_order_status(order_id: str)
# 查询用户所有订单
orders = payment.get_user_orders(
user_id: str,
status: Optional[str] = None, # 筛选状态
limit: int = 50
)
# 查询所有订单（管理员）
orders = payment.get_all_orders(
status: Optional[str] = None,
start_date: Optional[datetime] = None,
end_date: Optional[datetime] = None,
limit: int = 100
)
# 获取统计信息
stats = payment.get_statistics(user_id: Optional[str] = None)success = payment.cancel_order(
order_id: str,
reason: str = 'manual'
)# 申请退款（不需要私钥）
refund_info = payment.request_refund(
order_id: str,
refund_address: str, # 用户的退款地址
notes: str = ""
)
# 查看待处理退款（管理员）
refunds = payment.get_pending_refunds()
# 手动转账后确认退款
success = payment.confirm_refund(
order_id: str,
tx_hash: str # 退款交易哈希
)def on_payment_received(order_id: str, order_info: dict):
# 处理支付成功
pass
def on_order_timeout(order_id: str, order_info: dict):
# 处理订单超时
pass
payment.set_callback('payment_received', on_payment_received)
payment.set_callback('order_timeout', on_order_timeout)# 验证交易
tx_info = payment.verify_transaction(tx_hash: str)
# 清理旧订单
deleted_count = payment.cleanup_old_orders(days: int = 90)
# 导出订单
payment.export_orders(
filepath: str,
start_date: Optional[datetime] = None,
end_date: Optional[datetime] = None
)
# 关闭系统
payment.close()查看 example_telegram_bot.py 获取完整示例。
# 安装依赖
pip install python-telegram-bot
# 配置 Bot Token
# 编辑 example_telegram_bot.py，填入你的 Bot Token
# 运行
python example_telegram_bot.py功能：
/start- 开始使用/buy- 购买会员/orders- 查看订单- 自动支付检测和通知
查看 example_discord_bot.py 获取完整示例。
# 安装依赖
pip install discord.py
# 配置 Bot Token
# 编辑 example_discord_bot.py，填入你的 Bot Token
# 运行
python example_discord_bot.py功能：
/buy- 购买会员/orders- 查看订单/refund- 申请退款/admin_stats- 管理员统计/admin_refunds- 查看待退款- 自动分配身份组
from flask import Flask, jsonify, request
from tron_payment import TronPayment
app = Flask(__name__)
payment = TronPayment(...)
@app.route('/api/create-order', methods=['POST'])
def create_order():
data = request.json
order = payment.create_order(
user_id=data['user_id'],
amount_usdt=data['amount']
)
# 返回订单信息
return jsonify({
'order_id': order['order_id'],
'wallet_address': order['wallet_address'],
'amount': order['amount'],
'qr_code_url': f"/api/qr/{order['order_id']}"
})
@app.route('/api/order/<order_id>', methods=['GET'])
def get_order(order_id):
order = payment.get_order_status(order_id)
return jsonify(order)
if __name__ == '__main__':
app.run(debug=True)- 建议值：10-30 秒
- TRON 区块时间约 3 秒，15 秒轮询可以在 1-2 个区块内确认
- 过小会增加 API 调用次数，可能触发限流
- 建议值：15-60 分钟
- 太短可能导致用户来不及支付
- 太长会占用内存和数据库资源
- 建议值：1-3
- TRON 网络较安全，1 个确认通常足够
- 大额交易建议 3-5 个确认
默认使用 SQLite，生产环境建议：
- 定期备份数据库文件
- 或迁移到 PostgreSQL/MySQL
- 不暴露私钥：本系统采用手动退款机制，无需在服务器上存储私钥
- API Key 保密：不要将 TronScan API Key 提交到 Git
- HTTPS 部署：生产环境使用 HTTPS
- 金额验证：严格验证支付金额
- 定期备份：定期备份订单数据库
- ❌ 不要将私钥存储在代码或服务器上
- ❌ 不要使用主网地址测试
- ❌ 不要在日志中记录敏感信息
- ❌ 不要信任客户端传来的金额
A: 使用 TronLink、Trust Wallet 等钱包创建地址。
A: 使用 Nile 测试网：
# 修改配置
TEST_MODE = True
TRON_WALLET_ADDRESS = "TTestNetAddress"
USDT_CONTRACT_ADDRESS = "TXYZopYRdj2D9XRtbG411XZZ3Q5Z8VWLk7"从 Nile 水龙头 获取测试币。
检查：
- 是否使用了 TRC20 网络（不是 ERC20 或 BEP20）
- 金额是否准确匹配
- 订单是否已超时
- TronScan API Key 是否有效
- 用户调用
request_refund() - 管理员查看
get_pending_refunds() - 手动使用钱包转账到用户地址
- 调用
confirm_refund()标记完成
可以。系统使用多线程，每个订单独立监控。
# 复制数据库文件
cp orders.db orders_backup_$(date +%Y%m%d).db
# 或导出为 JSON
python -c "from tron_payment import TronPayment; p = TronPayment(...); p.export_orders('orders.json')"- 支持并发监控 1000+ 订单
- 单个订单内存占用 < 1KB
- 数据库查询优化，带索引
- API 调用限流保护
- ✨ 初始版本
- ✅ 支持订单创建和监控
- ✅ 支持回调机制
- ✅ 支持手动退款管理
- ✅ 提供 Telegram 和 Discord 集成示例
MIT License
欢迎提交 Issue 和 Pull Request！
- GitHub: [your-github]
- Email: your-email@example.com
本软件仅供学习和研究使用。使用本软件进行的任何交易和支付行为，风险由用户自行承担。作者不对使用本软件造成的任何损失负责。
⭐ 如果这个项目对你有帮助，请给个 Star！