UPG API 接入文档

UPG（USDT Pay Gateway）是一套无托管的 USDT 链上收款网关。商户调用 API 创建收款订单后，资金将直接打入商户自己配置的收款地址，平台不经手资金。

接口基本信息

快速开始

以下示例演示如何用 5 分钟完成首笔 USDT 收款订单的创建与回调处理。

// 1. 构建签名
$params = [
    'api_key'          => 'YOUR_API_KEY',
    'merchant_order_no' => 'ORDER_' . time(),
    'amount'           => 100.00,
    'currency'         => 'CNY',
    'chain'            => 'TRC20',
    'notify_url'       => 'https://your-site.com/notify',
    'timestamp'        => time(),
    'nonce'            => bin2hex(random_bytes(8)),
];
ksort($params);
$parts = [];
foreach ($params as $k => $v) {
    if ($v === '' || $v === null) continue;
    $parts[] = $k . '=' . $v;
}
$signStr = implode('&', $parts); // api_secret 仅作 HMAC 密钥，不拼入字符串
$params['sign'] = hash_hmac('sha256', $signStr, 'YOUR_API_SECRET');

// 2. 发起请求
$ch = curl_init('https://your-domain.com/api/pay/create');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($params),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
]);
$resp = json_decode(curl_exec($ch), true);

// 3. 处理结果
if ($resp['code'] === 200) {
    $order  = $resp['data'];
    // 引导用户访问收银台
    header('Location: ' . $order['pay_url']);
}

import hmac, hashlib, time, random, string, requests

api_key    = 'YOUR_API_KEY'
api_secret = 'YOUR_API_SECRET'

params = {
    'api_key':          api_key,
    'merchant_order_no': f'ORDER_{int(time.time())}',
    'amount':           100.00,
    'currency':         'CNY',
    'chain':            'TRC20',
    'notify_url':       'https://your-site.com/notify',
    'timestamp':        int(time.time()),
    'nonce':            ''.join(random.choices(string.ascii_lowercase, k=16)),
}
sorted_params = dict(sorted(params.items()))
sign_str = '&'.join([f'{k}={v}' for k, v in sorted_params.items() if v != '' and v is not None])
# api_secret 仅作 HMAC 密钥，不拼入字符串
params['sign'] = hmac.new(api_secret.encode(), sign_str.encode(), hashlib.sha256).hexdigest()

resp = requests.post('https://your-domain.com/api/pay/create', json=params, timeout=10)
data = resp.json()
if data['code'] == 200:
    print('收银台：', data['data']['pay_url'])

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

const API_KEY    = 'YOUR_API_KEY';
const API_SECRET = 'YOUR_API_SECRET';

const params = {
  api_key:          API_KEY,
  merchant_order_no:`ORDER_${Date.now()}`,
  amount:           100.00,
  currency:         'CNY',
  chain:            'TRC20',
  notify_url:       'https://your-site.com/notify',
  timestamp:        Math.floor(Date.now() / 1000),
  nonce:            crypto.randomBytes(8).toString('hex'),
};
// api_secret 仅作 HMAC 密钥，不拼入字符串
const signStr = Object.keys(params).sort()
  .filter(k => params[k] !== '' && params[k] != null)
  .map(k => `${k}=${params[k]}`).join('&');
params.sign = crypto.createHmac('sha256', API_SECRET).update(signStr).digest('hex');

const { data } = await axios.post('https://your-domain.com/api/pay/create', params);
if (data.code === 200) console.log('收银台：', data.data.pay_url);

接口鉴权

所有业务接口（创建订单、查询订单等）均需通过 HMAC-SHA256 签名鉴权。每次请求需携带以下公共参数：

签名算法

签名示例

参数：api_key=abc，amount=100，nonce=xyz123，timestamp=1700000000

# 排序后拼接（字典序）：
api_key=abc&amount=100&nonce=xyz123×tamp=1700000000
# 上面就是完整签名字符串，api_secret 不在字符串内，只作 HMAC 密钥

# PHP:
$sign = hash_hmac('sha256', $signStr, 'YOUR_SECRET');

# Python:
sign = hmac.new(secret.encode(), sign_str.encode(), hashlib.sha256).hexdigest()

# Node.js:
sign = crypto.createHmac('sha256', secret).update(signStr).digest('hex');

创建收款订单

创建一笔 USDT 收款订单。同一 merchant_order_no 若存在未过期的待支付订单，将返回原订单（幂等）。

请求参数

响应数据 data

响应示例

{
  "code": 200,
  "message": "订单创建成功",
  "data": {
    "order_no":         "UPG20240101120000A1B2C3",
    "merchant_order_no": "ORDER_1704067200",
    "chain":            "TRC20",
    "pay_address":      "TNVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "usdt_amount":      "13.726870",
    "fiat_amount":      100,
    "fiat_currency":    "CNY",
    "exchange_rate":    7.2845,
    "pay_url":          "https://your-domain.com/pay?order=UPG20240101120000A1B2C3",
    "qr_url":           "https://your-domain.com/pay/qr?order=UPG...",
    "expire_at":        "2024-01-01 12:30:00",
    "expire_seconds":   1800,
    "status":           0
  }
}

查询订单状态

通过系统订单号或商户订单号查询订单当前状态。

请求参数

响应数据 data

查询可用收款链

查询当前商户已配置的收款链，可选传入金额做计费预检。建议在创建订单前调用，避免必然失败的请求。

请求参数

响应数据 data

回调通知规范

回调参数

验证回调签名（PHP 示例）

$notifySecret = 'YOUR_NOTIFY_SECRET'; // 在商户后台「API 配置」获取
$data = json_decode(file_get_contents('php://input'), true);

// 取出 sign，其余参数参与签名
$sign  = $data['sign'];
unset($data['sign']);

// 按 key 升序拼接，notify_secret 仅作 HMAC 密钥
ksort($data);
$parts = [];
foreach ($data as $k => $v) {
    if ($v === '' || $v === null) continue;
    $parts[] = $k . '=' . $v;
}
$signStr  = implode('&', $parts); // notify_secret 仅作 HMAC 密钥
$expected = hash_hmac('sha256', $signStr, $notifySecret);

if (!hash_equals($expected, $sign)) {
    http_response_code(400);
    exit('INVALID SIGN');
}

// 处理业务：更新订单状态
if ((int)$data['status'] === 1) {
    // TODO: 标记订单已支付，发货/开通会员等
    updateOrderStatus($data['merchant_order_no'], 1);
}

echo 'OK'; // 必须返回 OK，否则系统会重试