HQpay 收款系统接入文档

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

系统介绍

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

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

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

签名生成的通用步骤如下

// 签名方法
function sign(array $data, $appsecret) {
    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.comx/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)
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)
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)
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 分钟后如需推送，可以在后台手动补发。