HQpay 收款系统接入文档

本文阅读对象：使用 HQpay 收款系统的技术架构师、研发工程师、系统运维工程师。通过本文档，商户可了解 HQpay 接入的技术、接入的产品业务、流程、接入规范等信息，以便于商户顺利完成接入工作。

系统介绍

HQpay 是专业的 USDT 支付平台，简单易用、安全稳定、不掉单/不撞单，强大的财务管理功能。用户直接付款到您自己的钱包地址，确保您的资金安全，支持 API 收付款。自带 USDT 风控系统，可以避免您收到黑 U 和标记 U。可个性化功能定制、私有化部署。

在开始接入之前，你需要：

1. 注册并登录 商户后台；
2. 在商户后台查看接入必需的 AppID 和 Appsecret；
3. 阅读我们有关 安全说明 及 签名算法 相关的说明；
4. 然后你可以阅读后续文档，并尝试通过接口发起 订单创建 请求。

签名生成的通用步骤如下：

1. 移除参数中的 signature 字段
2. 移除值为空的字段
3. 按参数名的字典序排序
4. 使用 http_build_query 拼接参数
5. 对拼接后的字符串进行 URL 解码
6. 添加 &appsecret=商户密钥 后缀
7. 计算 MD5 值并转换为大写

// 签名方法
function sign(array $data, $appsecret) {
    foreach ($data as $key => $value) {
        if ($key == "signature" || $value == '') {
            unset($data[$key]);
        }
    }
    ksort($data);
    $sign = strtoupper(md5(urldecode(http_build_query($data)) . '&appsecret=' . $appsecret));
    return $sign;
}

// 用法示例
$data = [
    'appid' => '12345',
    'pay_money' => 1,
    'order_sn' => '123123123123',
];

// 平台通信密钥
$appsecret = 'xxxxxxxxxxx';
$sign = sign($data, $appsecret);
                

复制代码

商户可调用该接口，查询账户余额信息。

请求地址：https://xusdt.hqitpay.com/api/df/balance

传参方式：数组

请求参数：

字段名称	字段类型	必填参数	说明
appid	string(16)	必填	商户号
signature	string(32)	必填	数据签名 详见签名算法

返回参数：

字段名称	参数含义	必填参数	说明
code	请求状态	必填	1 表示查询成功，其它表示查询失败
msg	消息描述	必填	失败原因
data	订单信息 (数据类型：集合)	必填	返回数据，查看下表

返回值 data 参数：

字段名称	参数含义
appid	商户号
usdt_balance	USDT 余额，单位：USDT
signature	安全校验签名串

用于生成指定数字货币的支付数据，包括收款金额(USDT)、收款地址、收款地址二维码等。商户可选择直接跳转至官方的收银台供用户支付，也可以使用数据自定义收银台。在用户支付成功后，系统将即时进行回调通知。

请求地址：https://xusdt.hqitpay.com/api/pay/unifiedorder

传参方式：数组

请求参数：

字段名称	字段类型	必填参数	说明
appid	string(16)	必填	商户号
pay_money	string(16)	必填	金额，精确到小数点后 2 位
money_type	string(16)	必填	单位： 1:美元 (USD) 2:人民币 (CNY) 3:印度卢比 (INR) 4:日元 (JPY) 5:韩元 (KRW) 6:菲律宾比索 (PHP) 7:欧元 (EUR) 8:英镑 (GBP) 9:瑞士法郎 (CHF) 10:新台币 (TWD) 11:港币 (HKD) 12:澳门元 (MOP) 13:新加坡币 (SGD) 14:新西兰元 (NZD) 15:泰铢 (THB) 16:加拿大元 (CAD) 当切换货币类型时，会实时转换成等值 USDT
chain_type	string(16)	必填	链路：1:波场(TRC20) 2:以太坊(ERC20) 3:币安智能链(BSC) 4:OKExChain(OKT)
channel_type	string(16)	必填	通道类型：2:个人收款地址（需在商户后台设置收款钱包地址）
order_sn	string(32)	必填	用户端自主生成的订单号，在用户端要保证唯一性
notify_url	string(500)	必填	接收平台支付异步通知的回调地址。必须为可直接访问的 URL，不能带参数、session 验证、csrf 验证
callback_url	string(500)	选填	即时回调地址，支付成功后，点击返回到的商户地址。务必包含 http:// 开头
product_name	string(64)	选填	商品名称
pay_username	string(64)	选填	付款人名称
attach	string(127)	选填	用户自定义数据，在 notify 的时候会原样返回
signature	string(32)	必填	数据签名 详见签名算法

请求返回：

特别提醒：支付后回调函数，并不能标示支付状态。用户需进一步完成验单逻辑

返回参数：

字段名称	参数含义	必填参数	说明
code	请求状态	必填	1 表示提交成功，其它表示提交失败
msg	消息描述	必填	失败原因
data	订单信息（数据类型：集合）	必填	返回数据，查看下表

返回值 data 参数：

字段名称	参数含义
appid	商户号
order_sn	商户订单号
pay_usdt	订单金额，需要支付的 USDT
address	收款地址
img	收款地址的二维码
chain_type	链路：1:波场(TRC20) 2:以太坊(ERC20) 3:币安智能链(BSC) 4:OKExChain(OKT)
pay_url	官方收银台地址，商户可直接跳转到该地址供用户支付
en_pay_url	官方英文收银台地址，商户可直接跳转到该地址供国外用户支付
exchange_rate	下单时的汇率
time_out	订单过期时间，时间戳 单位 秒
signature	安全校验签名串

由于区块链转账操作的特殊性（转账金额通常由用户手动输入），不可避免会出现用户实际支付金额与订单金额不符，导致掉单（订单超时失败）的情况。

手动操作补单

商户可前往商户后台，在订单页面 点击【补单】，输入交易哈希、商户订单号等信息进行手动补单。补单成功后，该笔订单状态回调为成功。

收银台

商户可直接从创建订单返回数据中，取出 pay_url 字段，然后跳转至该地址，供用户支付。

该接口供商户主动查询订单状态。多用于商户自定义收银台的场景。

请求地址：https://xusdt.hqitpay.com/api/pay/search

传参方式：数组

请求参数：

字段名称	字段类型	必填参数	说明
appid	string(16)	必填	商户号
order_sn	string(50)	必填	商户订单号
signature	string(32)	必填	数据签名 详见签名算法

返回参数：

字段名称	参数含义	必填参数	说明
code	请求状态	必填	1 表示查询成功，其它表示查询失败
msg	消息描述	必填	失败原因
data	订单信息（数据类型：集合）	必填	返回数据，查看下表

返回值 data 参数：

字段名称	参数含义
appid	商户号
order_sn	商户订单号
pay_usdt	订单金额，支付的 USDT
pay_money	订单金额，支付的 CNY
status	订单状态：查看下表
success_time	成功时间
signature	安全校验签名串

订单状态：

status	描述
0	待支付
1	支付成功
2	超时
3	失败
4	部分付款
5	退款中
6	退款成功
7	部分退款
8	退款失败

用户支付完成后，系统会自动向订单关联的回调地址（notify_url）发送通知消息，告知该笔订单已支付完成。

传参方式：数组

请求参数：

字段名称	说明
appid	商户号
pay_money	金额，单位 CNY
pay_usdt	金额，单位 USDT
order_sn	商户订单号
status	订单状态：查看订单查询表中的订单状态
success_time	成功时间
attach	用户附加数据
signature	数据签名 详见签名算法

商户可调用该接口，发起账户提现申请。

请求地址：https://xusdt.hqitpay.com/api/df/apply

传参方式：数组

请求参数：

字段名称	字段类型	必填参数	说明
appid	string(16)	必填	商户号
money	string(16)	必填	代付金额 单位：USDT
chain_type	string(16)	必填	链路：1:波场(TRC20) 2:以太坊(ERC20) 3:币安智能链(BSC) 4:OKExChain(OKT)
df_sn	string(32)	必填	用户端自主生成的代付订单号，在用户端要保证唯一性
notify_url	string(500)	必填	接收平台异步通知的回调地址。必须为可直接访问的 URL，不能带参数、session 验证、csrf 验证
receive_address	string(64)	必填	收款地址
attach	string(127)	选填	用户自定义数据，在 notify 的时候会原样返回
signature	string(32)	必填	数据签名 详见签名算法

返回参数：

字段名称	参数含义	必填参数	说明
code	请求状态	必填	1 表示提交成功，其它表示提交失败
msg	消息描述	必填	描述

该接口供商户主动查询提现状态。

请求地址：https://xusdt.hqitpay.com/api/df/search

传参方式：数组

请求参数：

字段名称	字段类型	必填参数	说明
appid	string(16)	必填	商户号
df_sn	string(50)	必填	商户代付订单号
signature	string(32)	必填	数据签名 详见签名算法

返回参数：

字段名称	参数含义	必填参数	说明
code	请求状态	必填	1 表示查询成功，其它表示查询失败
msg	消息描述	必填	失败原因
data	订单信息（数据类型：集合）	必填	返回数据，查看下表

返回值 data 参数：

字段名称	参数含义
appid	商户号
df_sn	商户代付订单号
money	代付金额，单位：USDT
status	代付状态：查看下表
success_time	成功时间
signature	安全校验签名串

代付状态：

status	描述
0	处理中
1	代付成功

用户支付完成后，系统会自动向订单关联的回调地址（notify_url）发送通知消息，告知该笔订单已支付完成。

传参方式：数组

请求参数：

字段名称	说明
appid	商户号
pay_money	金额，单位 CNY。
pay_usdt	金额，单位 USDT。
order_sn	商户订单号
status	订单状态：查看订单查询表中的订单状态
success_time	成功时间
attach	用户附加数据
signature	数据签名 详见签名算法

通知返回

商户在收到通知信息后，在页面输出"OK"（ OK 两个字母大写， php 例子：echo "OK";），否则会重复 5 次发送点对点通知。

通知重试

系统向商户创建订单时指定的 notify_url 发送 回调通知 后，如该 notify_url 返回的不是 "OK"（ 没有双引号，OK 两个字母大写 )，则系统会触发 重试机制。相关规则如下：

间隔 5 秒 会进行第 1 次重试。

如第一次重试仍为失败，后续通知频率（秒）：10，20，60，300。超过 5 分钟后如需推送，可以在后台手动补发。

回调签名验证

为确保回调通知的真实性，商户端需要验证回调数据的签名。验证方法与接口请求的签名验证一致：

1. 从回调参数中获取所有字段（包括 signature）
2. 移除 signature 字段
3. 移除值为空的字段
4. 按参数名的字典序排序
5. 使用 http_build_query 拼接参数
6. 对拼接后的字符串进行 URL 解码
7. 添加 &appsecret=商户密钥 后缀
8. 计算 MD5 值并转换为大写
9. 比较计算出的签名与回调中的 signature 字段是否一致

// 商户密钥
$appsecret = 'your_appsecret';

// 获取回调参数
$data = $_POST;
$signature = $data['signature'];

// 验证签名
function verifyCallback($data, $appsecret, $signature) {
    foreach ($data as $key => $value) {
        if ($key == "signature" || $value == '') {
            unset($data[$key]);
        }
    }
    ksort($data);
    $calculatedSign = strtoupper(md5(urldecode(http_build_query($data)) . '&appsecret=' . $appsecret));
    return hash_equals($calculatedSign, $signature);
}

if (verifyCallback($data, $appsecret, $signature)) {
    // 签名验证成功，处理业务逻辑
    echo 'OK';
} else {
    // 签名验证失败，拒绝处理
    echo 'OK'; // 无论成功失败都返回 OK
}
                

复制代码

当接口返回 code 不为 1 时，表示请求处理失败。以下是常见的错误码及说明：

通用错误码

错误码	说明	解决方案
0	请求失败	检查请求参数是否正确
-1	签名错误	检查签名算法和 appsecret 是否正确
-2	商户不存在	检查 appid 是否正确
-3	商户已禁用	联系客服处理
-4	IP 未授权	在商户后台添加请求 IP 白名单
-5	请求过于频繁	降低请求频率

下单错误码

错误码	说明	解决方案
1001	订单号已存在	使用唯一的订单号
1002	金额格式错误	确保金额格式正确，最多2位小数
1003	链路类型错误	检查 chain_type 参数（1:TRC20, 2:ERC20, 3:BSC, 4:OKT）
1004	回调地址格式错误	确保 notify_url 是有效的 URL
1005	货币类型错误	检查 money_type 参数范围（1-16）

代付错误码

错误码	说明	解决方案
2001	余额不足	确保账户 USDT 余额充足
2002	收款地址格式错误	检查 receive_address 格式是否正确
2003	代付订单号已存在	使用唯一的 df_sn
2004	代付金额超出限制	检查代付金额是否在允许范围内

Python 示例 - 创建订单

import hashlib
import urllib.parse
import requests

def sign(data, appsecret):
    """生成签名"""
    sorted_data = dict(sorted(data.items()))
    query_string = urllib.parse.urlencode(sorted_data)
    sign_string = f"{query_string}&appsecret={appsecret}"
    return hashlib.md5(sign_string.encode()).hexdigest().upper()

# 配置
appid = "your_appid"
appsecret = "your_appsecret"
api_url = "https://xusdt.hqitpay.com/api/pay/unifiedorder"

# 请求参数
data = {
    "appid": appid,
    "pay_money": "100.00",
    "money_type": "2",  # 人民币
    "chain_type": "1",  # TRC20
    "channel_type": "2",
    "order_sn": "ORDER202403080001",
    "notify_url": "https://yourdomain.com/notify",
    "callback_url": "https://yourdomain.com/callback",
    "product_name": "测试商品",
    "attach": "自定义数据"
}

# 生成签名
data["signature"] = sign(data, appsecret)

# 发送请求
response = requests.post(api_url, data=data)
result = response.json()

if result["code"] == 1:
    print(f"订单创建成功！")
    print(f"支付地址: {result['data']['pay_url']}")
    print(f"收款地址: {result['data']['address']}")
    print(f"支付金额: {result['data']['pay_usdt']} USDT")
else:
    print(f"创建失败: {result['msg']}")
                

复制代码

Java 示例 - 查询订单

import java.security.MessageDigest;
import java.util.*;
import java.net.URLEncoder;

public class HqPayApi {
    private static final String APPID = "your_appid";
    private static final String APPSECRET = "your_appsecret";
    
    public static String sign(Map<String, String> data, String appsecret) throws Exception {
        // 按键排序
        List<String> keys = new ArrayList<>(data.keySet());
        Collections.sort(keys);
        
        StringBuilder sb = new StringBuilder();
        for (String key : keys) {
            if (sb.length() > 0) sb.append("&");
            sb.append(key).append("=").append(URLEncoder.encode(data.get(key), "UTF-8"));
        }
        sb.append("&appsecret=").append(appsecret);
        
        // MD5 加密
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(sb.toString().getBytes());
        StringBuilder result = new StringBuilder();
        for (byte b : digest) {
            result.append(String.format("%02x", b));
        }
        return result.toString().toUpperCase();
    }
    
    public static void main(String[] args) throws Exception {
        Map<String, String> data = new HashMap<>();
        data.put("appid", APPID);
        data.put("order_sn", "ORDER202403080001");
        data.put("signature", sign(data, APPSECRET));
        
        // 发送 HTTP POST 请求
        System.out.println("查询参数: " + data);
    }
}
                

复制代码

Node.js 示例 - 处理回调

const crypto = require('crypto');
const querystring = require('querystring');
const express = require('express');
const app = express();

app.use(express.urlencoded({ extended: true }));

const APPSECRET = 'your_appsecret';

function verifySign(data, signature) {
    // 移除 signature 字段
    const signData = { ...data };
    delete signData.signature;
    
    // 排序并生成字符串
    const sortedKeys = Object.keys(signData).sort();
    let signString = '';
    sortedKeys.forEach((key, index) => {
        if (index > 0) signString += '&';
        signString += `${key}=${encodeURIComponent(signData[key])}`;
    });
    signString += `&appsecret=${APPSECRET}`;
    
    // MD5 加密
    const md5 = crypto.createHash('md5');
    const calculatedSign = md5.update(signString).digest('hex').toUpperCase();
    
    return calculatedSign === signature;
}

// 回调处理
app.post('/notify', (req, res) => {
    const data = req.body;
    
    console.log('收到回调:', data);
    
    // 验证签名
    if (!verifySign(data, data.signature)) {
        console.log('签名验证失败');
        return res.status(400).send('签名错误');
    }
    
    // 处理订单状态
    if (data.status === '1') {
        console.log(`订单 ${data.order_sn} 支付成功`);
        console.log(`支付金额: ${data.pay_usdt} USDT`);
        // 更新订单状态...
    }
    
    // 必须返回 OK
    res.send('OK');
});

app.listen(3000, () => {
    console.log('回调服务器运行在端口 3000');
});
                

复制代码

cURL 示例 - 余额查询

# 余额查询
curl -X POST https://xusdt.hqitpay.com/api/df/balance \
  -d "appid=your_appid" \
  -d "signature=YOUR_SIGNATURE"

# 创建订单示例
curl -X POST https://xusdt.hqitpay.com/api/pay/unifiedorder \
  -d "appid=your_appid" \
  -d "pay_money=100.00" \
  -d "money_type=2" \
  -d "chain_type=3" \
  -d "channel_type=2" \
  -d "order_sn=ORDER001" \
  -d "notify_url=https://yourdomain.com/notify" \
  -d "signature=YOUR_SIGNATURE"

# 代付申请
curl -X POST https://xusdt.hqitpay.com/api/df/apply \
  -d "appid=your_appid" \
  -d "money=10.00" \
  -d "chain_type=3" \
  -d "df_sn=DF001" \
  -d "notify_url=https://yourdomain.com/notify" \
  -d "receive_address=0x..." \
  -d "signature=YOUR_SIGNATURE"
                

复制代码

HQpay 支持多条区块链网络，商户可根据需求选择合适的链路：

链路对比

链路	chain_type	特点	确认时间	手续费
TRC20 (波场)	1	速度快、手续费低	约 3 秒	极低
ERC20 (以太坊)	2	安全性高、生态完善	约 15 秒	中等
BSC (币安智能链)	3	速度快、兼容 EVM	约 3 秒	低
OKT (OKExChain)	4	高性能、低费用	约 3 秒	低

地址格式

链路	地址格式	示例
TRC20	以 T 开头的 34 位字符串	TN3W4H6rB2...
ERC20	以 0x 开头的 42 位十六进制	0x742d35Cc6...
BSC	以 0x 开头的 42 位十六进制	0x742d35Cc6...
OKT	以 0x 开头的 42 位十六进制	0x742d35Cc6...