Tron链 USDT/TRX 支付网关

快速、安全、可靠的加密货币支付解决方案
支持TRC20 USDT和TRX支付，实时区块扫描，自动回调通知

查看文档 开始使用

核心功能

多币种支持

支持TRC20 USDT和TRX两种主流加密货币，满足不同场景需求

实时区块扫描

持续扫描Tron区块链，实时检测支付交易，秒级确认

Webhook回调

支付状态实时推送，支持重试机制，确保消息送达

地址监听

监听任意Tron地址的交易，支持入账/出账双向监控

安全签名

HMAC-SHA256签名验证，防止请求篡改和重放攻击

唯一金额

自动生成唯一支付金额，精准匹配订单，避免混淆

API 文档

响应码说明

所有API响应均采用HTTP标准状态码：

状态码 说明 处理建议
200 请求成功 正常处理返回数据
400 请求参数错误 检查请求参数是否正确
401 认证失败 检查API Key、时间戳、签名是否正确
403 无权访问 检查是否有权限访问该资源
404 资源不存在 检查订单号或地址是否正确
500 服务器内部错误 请稍后重试或联系技术支持

错误响应格式

{
    "detail": "错误描述信息"
}

认证方式

所有API请求需要在Header中包含以下认证信息：

X-API-Key: your_api_key
X-Timestamp: 1732723456
X-Signature: hmac_sha256_signature

签名算法详解

签名计算公式：HMAC-SHA256(api_secret, timestamp + request_body)

Python 签名示例

import time
import hmac
import hashlib
import json
import requests

# 商户凭证
API_KEY = "your_api_key"
API_SECRET = "your_api_secret"
API_URL = "https://your-domain.com"

def create_signature(timestamp: str, body: str) -> str:
    """生成请求签名"""
    message = f"{timestamp}{body}"
    signature = hmac.new(
        API_SECRET.encode('utf-8'),
        message.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

def make_request(endpoint: str, data: dict = None) -> dict:
    """发送API请求"""
    timestamp = str(int(time.time()))
    body = json.dumps(data, separators=(',', ':')) if data else ""
    signature = create_signature(timestamp, body)

    headers = {
        "X-API-Key": API_KEY,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "Content-Type": "application/json"
    }

    if data:
        response = requests.post(f"{API_URL}{endpoint}", headers=headers, json=data)
    else:
        response = requests.get(f"{API_URL}{endpoint}", headers=headers)

    return response.json()

# 使用示例
order_data = {
    "merchant_order_id": "ORDER_001",
    "amount": 100.00,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "notify_url": "https://your-domain.com/webhook"
}
result = make_request("/api/v1/order/create", order_data)

PHP 签名示例

<?php
$api_key = "your_api_key";
$api_secret = "your_api_secret";
$api_url = "https://your-domain.com";

function create_signature($timestamp, $body, $api_secret) {
    $message = $timestamp . $body;
    return hash_hmac('sha256', $message, $api_secret);
}

function make_request($endpoint, $data = null) {
    global $api_key, $api_secret, $api_url;

    $timestamp = (string)time();
    $body = $data ? json_encode($data, JSON_UNESCAPED_SLASHES) : "";
    $signature = create_signature($timestamp, $body, $api_secret);

    $headers = [
        "X-API-Key: $api_key",
        "X-Timestamp: $timestamp",
        "X-Signature: $signature",
        "Content-Type: application/json"
    ];

    $ch = curl_init($api_url . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

    if ($data) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    }

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// 使用示例
$order_data = [
    "merchant_order_id" => "ORDER_001",
    "amount" => 100.00,
    "currency" => "USDT",
    "receiving_address" => "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "notify_url" => "https://your-domain.com/webhook"
];
$result = make_request("/api/v1/order/create", $order_data);
?>

JavaScript/Node.js 签名示例

const crypto = require('crypto');
const axios = require('axios');

const API_KEY = 'your_api_key';
const API_SECRET = 'your_api_secret';
const API_URL = 'https://your-domain.com';

function createSignature(timestamp, body) {
    const message = timestamp + body;
    return crypto.createHmac('sha256', API_SECRET)
                 .update(message)
                 .digest('hex');
}

async function makeRequest(endpoint, data = null) {
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const body = data ? JSON.stringify(data) : '';
    const signature = createSignature(timestamp, body);

    const headers = {
        'X-API-Key': API_KEY,
        'X-Timestamp': timestamp,
        'X-Signature': signature,
        'Content-Type': 'application/json'
    };

    const config = { headers };

    if (data) {
        const response = await axios.post(`${API_URL}${endpoint}`, data, config);
        return response.data;
    } else {
        const response = await axios.get(`${API_URL}${endpoint}`, config);
        return response.data;
    }
}

// 使用示例
const orderData = {
    merchant_order_id: 'ORDER_001',
    amount: 100.00,
    currency: 'USDT',
    receiving_address: 'TXxxxxxxxxxxxxxxxxxxxxxxxxxx',
    notify_url: 'https://your-domain.com/webhook'
};

makeRequest('/api/v1/order/create', orderData)
    .then(result => console.log(result))
    .catch(err => console.error(err));
POST

/api/v1/order/create

创建支付订单，支持USDT和TRX。每次创建订单需传入收款地址。

请求参数

参数名 类型 必填 说明
merchant_order_id string 是 商户订单号，1-64字符
amount float 是 订单金额，0-100000
currency string 否 币种: USDT(默认) 或 TRX
receiving_address string 是 收款地址(TRON地址，34字符)
notify_url string 是 支付成功回调地址
return_url string 否 支付完成跳转地址
extra_data string 否 附加数据，最大1000字符

请求示例

{
    "merchant_order_id": "ORDER_001",
    "amount": 100.00,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "notify_url": "https://your-domain.com/webhook",
    "return_url": "https://your-domain.com/success",
    "extra_data": "{\"user_id\": 12345}"
}

成功响应 (200)

{
    "order_id": "PO20241127123456ABCD1234",
    "merchant_order_id": "ORDER_001",
    "amount": 100.0,
    "pay_amount": 100.01,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "pending",
    "expire_time": "2024-11-27 13:00:00",
    "created_at": "2024-11-27 12:30:00"
}

错误响应示例

// 400 - 参数错误
{"detail": "无效的TRON收款地址格式"}

// 400 - 订单号重复
{"detail": "商户订单号已存在"}

// 401 - 认证失败
{"detail": "无效的API Key"}
{"detail": "请求已过期"}
{"detail": "签名验证失败"}
POST

/api/v1/order/query

查询订单状态，可通过平台订单号或商户订单号查询

请求参数

参数名 类型 必填 说明
order_id string 二选一 平台订单号
merchant_order_id string 二选一 商户订单号

请求示例

// 方式1：通过平台订单号查询
{
    "order_id": "PO20241127123456ABCD1234"
}

// 方式2：通过商户订单号查询
{
    "merchant_order_id": "ORDER_001"
}

成功响应 (200)

{
    "order_id": "PO20241127123456ABCD1234",
    "merchant_order_id": "ORDER_001",
    "amount": 100.0,
    "pay_amount": 100.01,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "paid",
    "expire_time": "2024-11-27 13:00:00",
    "created_at": "2024-11-27 12:30:00"
}

订单状态说明

状态 说明
pending 待支付
paid 已支付
expired 已过期
cancelled 已取消

错误响应示例

// 400 - 参数缺失
{"detail": "请提供order_id或merchant_order_id"}

// 404 - 订单不存在
{"detail": "订单不存在"}

// 403 - 无权访问
{"detail": "无权访问该订单"}
POST

/api/v1/watch/add

添加地址监听，监控指定地址的入账/出账交易

请求参数

参数名 类型 必填 说明
address string 是 要监听的TRON地址(34字符)
notify_url string 是 交易通知回调地址
label string 否 地址标签/备注
watch_usdt bool 否 是否监听USDT(默认true)
watch_trx bool 否 是否监听TRX(默认true)
min_amount float 否 最小通知金额(默认0)

请求示例

{
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "notify_url": "https://your-domain.com/watch-webhook",
    "label": "我的钱包",
    "watch_usdt": true,
    "watch_trx": true,
    "min_amount": 1.0
}

成功响应 (200)

{
    "id": 1,
    "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "label": "我的钱包",
    "notify_url": "https://your-domain.com/watch-webhook",
    "watch_usdt": true,
    "watch_trx": true,
    "min_amount": 1.0,
    "status": "active",
    "created_at": "2024-11-27 12:30:00"
}

错误响应示例

// 400 - 地址格式错误
{"detail": "无效的TRON地址格式"}
DELETE

/api/v1/watch/{address}

删除监听地址

路径参数

参数名 类型 说明
address string 要删除的TRON地址

成功响应 (200)

{
    "status": "ok",
    "message": "监听地址已删除"
}

错误响应示例

// 404 - 地址不存在
{"detail": "监听地址不存在"}
GET

/api/v1/watch/list

获取所有监听地址列表

成功响应 (200)

[
    {
        "id": 1,
        "address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "label": "我的钱包",
        "notify_url": "https://your-domain.com/watch-webhook",
        "watch_usdt": true,
        "watch_trx": true,
        "min_amount": 1.0,
        "status": "active",
        "created_at": "2024-11-27 12:30:00"
    },
    {
        "id": 2,
        "address": "TYyyyyyyyyyyyyyyyyyyyyyyyyyy",
        "label": "热钱包",
        "notify_url": "https://your-domain.com/watch-webhook",
        "watch_usdt": true,
        "watch_trx": false,
        "min_amount": 10.0,
        "status": "active",
        "created_at": "2024-11-27 13:00:00"
    }
]
GET

/api/v1/health

系统健康检查（无需认证）

成功响应 (200)

{
    "status": "ok",
    "timestamp": "2024-11-27T12:30:00.123456",
    "scanner_running": true
}

Webhook 事件

事件类型

事件类型 说明
order.created 订单创建成功
order.paid 订单支付成功
order.expired 订单已过期
address.transaction 监听地址有新交易

订单Webhook数据格式

{
    "event": "order.paid",
    "order_id": "PO20241127123456ABCD1234",
    "merchant_order_id": "ORDER_001",
    "amount": 100.0,
    "pay_amount": 100.01,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "from_address": null,
    "status": "paid",
    "txid": "abc123def456...",
    "paid_at": "2024-11-27 12:35:00",
    "extra_data": "{\"user_id\": 12345}",
    "timestamp": 1732723456,
    "watch_address": null,
    "direction": null
}

地址监听Webhook数据格式

{
    "event": "address.transaction",
    "order_id": null,
    "merchant_order_id": null,
    "amount": 50.0,
    "pay_amount": null,
    "currency": "USDT",
    "receiving_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "from_address": "TYyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "status": null,
    "txid": "abc123def456...",
    "paid_at": null,
    "extra_data": null,
    "timestamp": 1732723456,
    "watch_address": "TXxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "in"
}

Webhook 处理示例 (Python Flask)

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    data = request.json
    event = data.get('event')

    if event == 'order.paid':
        order_id = data.get('order_id')
        merchant_order_id = data.get('merchant_order_id')
        amount = data.get('pay_amount')
        txid = data.get('txid')

        # 处理支付成功逻辑
        print(f"订单支付成功: {order_id}, 金额: {amount}, TXID: {txid}")
        # 更新您的订单状态...

    elif event == 'order.expired':
        order_id = data.get('order_id')
        # 处理订单过期逻辑
        print(f"订单已过期: {order_id}")

    elif event == 'address.transaction':
        address = data.get('watch_address')
        direction = data.get('direction')
        amount = data.get('amount')
        currency = data.get('currency')

        # 处理地址交易通知
        print(f"地址 {address} {direction} {amount} {currency}")

    # 返回200表示接收成功
    return jsonify({'status': 'ok'}), 200

if __name__ == '__main__':
    app.run(port=5000)

简单透明的价格

自部署版本

完全开源，自由部署

免费
  • 无限订单数量
  • 无限监听地址
  • 完整源代码
  • 管理员后台