🚀 USDT 支付系统 - 商户后台

2.1 场景说明

创建 USDT 支付订单，获取支付地址和订单信息，用户支付后系统自动回调通知。

2.2 接口详情

2.3 参数说明

2.4 请求示例

{
    "merchantNo": "M2032545595611709440",
    "payAddress": "TYxAwcVyyZgD1n2c4APkgbVeK48Mht2gqo",
    "productName": "充值10USDT",
    "timestamp": 1741916400000,
    "sign": "d41d8cd98f00b204e9800998ecf8427e..."
}

2.5 返回状态码

2.6 返回示例

成功：

{
    "code": 200,
    "message": "SUCCESS",
    "data": {
        "orderNo": "P2026031412345678",
        "merchantOrderNo": "ORDER_202603140001",
        "payAddress": "TYxAwcVyyZgD1n2c4APkgbVeK48Mht2gqo",
        "amount": "10.00",
        "expireTime": "2026-03-14 13:00:00"
    }
}

3.1 场景说明

查询订单的支付状态、交易哈希等详细信息。

3.2 接口详情

3.3 参数说明

3.4 返回状态码

3.5 返回示例

{
    "code": 200,
    "message": "SUCCESS",
    "data": {
        "orderNo": "P2026031412345678",
        "merchantOrderNo": "ORDER_202603140001",
        "status": 1,
        "statusText": "已支付",
        "payAmount": "10.00",
        "payAddress": "TYxAwcVyyZgD1n2c4APkgbVeK48Mht2gqo",
        "txHash": "7f3a8f611aee7dcca3ac6869e3097f641132b783...",
        "payTime": "2026-03-14 12:30:00"
    }
}

订单状态说明：

4.1 场景说明

当订单支付成功后，系统会向您配置的回调地址发送 POST 请求，通知支付结果。

重要：请在接收回调后进行签名验证，确保请求来源合法。

4.2 回调参数

4.3 回调示例

{
    "address": "TYxAwcVyyZgD1n2c4APkgbVeK48Mht2gqo",
    "amount": "10.00",
    "label": "user_10001",
    "txHash": "7f3a8f611aee7dcca3ac6869e3097f641132b783...",
    "timestamp": 1741916400000,
    "sign": "e5b7c8d9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5..."
}

4.4 响应要求

请返回字符串 success 表示接收成功，否则系统将按以下策略重试：

• 第1次重试：5分钟后
• 第2次重试：15分钟后
• 第3次重试：30分钟后
• 第4次重试：1小时后
• 第5次重试：2小时后

超过5次重试后，系统不再自动重试，您可在后台手动触发。

5.1 签名规则

1. 将所有请求参数（不含 sign 和空值）按参数名 ASCII 码升序排列
2. 拼接成 key1=value1&key2=value2 格式的字符串
3. 在末尾拼接 &key=您的API Secret
4. 对整个字符串进行 SHA256 哈希运算
5. 结果转为小写十六进制字符串

5.2 签名示例

请求参数：

merchantNo = M2032545595611709440
label = user_10001
timestamp = 1741916400000
apiSecret = AS_d710bd5f7ffba8cdf1c7ca9dda6506bc...

排序拼接后：

label=user_10001&merchantNo=M2032545595611709440×tamp=1741916400000&key=AS_d710bd5f7ffba8cdf1c7ca9dda6506bc...

SHA256后：

sign = e5b7c8d9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7

5.3 Java 示例代码

import java.security.MessageDigest;
import java.util.*;
import java.util.stream.Collectors;

public class SignUtil {
    
    public static String generateSign(Map params, String apiSecret) {
        // 1. 过滤空值和sign，按key排序
        String sortedParams = params.entrySet().stream()
            .filter(e -> e.getValue() != null && !e.getValue().isEmpty())
            .filter(e -> !"sign".equals(e.getKey()))
            .sorted(Map.Entry.comparingByKey())
            .map(e -> e.getKey() + "=" + e.getValue())
            .collect(Collectors.joining("&"));
        
        // 2. 拼接密钥
        String signStr = sortedParams + "&key=" + apiSecret;
        
        // 3. SHA256哈希
        return sha256Hex(signStr);
    }
    
    public static String sha256Hex(String str) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            byte[] hash = md.digest(str.getBytes("UTF-8"));
            StringBuilder sb = new StringBuilder();
            for (byte b : hash) {
                sb.append(String.format("%02x", b));
            }
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

5.4 PHP 示例代码

<?php
function generateSign($params, $apiSecret) {
    // 1. 过滤空值和sign
    $params = array_filter($params, function($v, $k) {
        return $v !== '' && $v !== null && $k !== 'sign';
    }, ARRAY_FILTER_USE_BOTH);
    
    // 2. 按key排序
    ksort($params);
    
    // 3. 拼接字符串
    $signStr = http_build_query($params) . '&key=' . $apiSecret;
    
    // 4. SHA256
    return hash('sha256', $signStr);
}

// 使用示例 - 生成地址
$params = [
    'merchantNo' => 'M2032545595611709440',
    'label' => 'user_10001',
    'timestamp' => time() * 1000
];
$apiSecret = 'AS_your_api_secret';
$sign = generateSign($params, $apiSecret);
$params['sign'] = $sign;
?>

5.5 注意事项

• 请确保服务器时间准确，时间戳误差超过5分钟将被拒绝
• 签名区分大小写，请统一使用小写
• API Secret 请妥善保管，切勿泄露

⚠️ 重要提示：TRX 余额

请确保您的主地址保持足够的 TRX 余额（建议不低于 50 TRX），用于支付子地址归集时的手续费。

TRX 余额不足将导致：

• 子地址 USDT 无法自动归集到主地址
• 资金满留在子地址，影响资金周转

建议在主地址中始终保持 50-100 TRX 以保证归集正常进行。