Epusdt支付网关API接口开发指南

前言

Epusdt是一个基于USDT的支付网关系统，为开发者提供了简单易用的HTTP API接口。通过集成这些接口，开发者可以快速在自己的系统中实现USDT支付功能。本文将详细介绍Epusdt的API接口规范和使用方法。

接口安全机制

签名算法详解

Epusdt采用MD5签名算法来确保接口调用的安全性。签名生成过程需要开发者特别注意以下几个关键点：

1. 参数排序规则：所有非空参数需按照参数名的ASCII码从小到大排序（字典序）
2. 空值处理：值为空的参数不参与签名
3. 大小写敏感：参数名区分大小写
4. 签名生成：
   • 将排序后的参数以key=value形式用&连接
   • 末尾拼接API认证token
   • 进行MD5运算并将结果转为小写

签名示例代码

以下是PHP语言的签名生成示例：

function epusdtSign(array $parameter, string $signKey) {
    ksort($parameter);
    reset($parameter); 
    $sign = '';
    $urls = '';
    foreach ($parameter as $key => $val) {
        if ($val == '') continue;
        if ($key != 'signature') {
            if ($sign != '') {
                $sign .= "&";
                $urls .= "&";
            }
            $sign .= "$key=$val"; 
            $urls .= "$key=" . urlencode($val); 
        }
    }
    $sign = md5($sign . $signKey);
    return $sign;
}

创建交易接口

接口说明

通过此接口可以发起一笔USDT支付交易。

请求方式：POST
接口地址：/api/v1/order/create-transaction

请求参数

参数名	类型	必填	说明
order_id	string	是	商户订单号，需保证唯一性
amount	number	是	支付金额(CNY)，保留2位小数，最小0.01
notify_url	string	是	异步回调通知地址
redirect_url	string	否	支付完成后同步跳转地址
signature	string	是	接口签名

成功响应示例

{
  "status_code": 200,
  "message": "success",
  "data": {
    "trade_id": "202203271648380592218340",
    "order_id": "9",
    "amount": 53,
    "actual_amount": 7.9104,
    "token": "TNEns8t9jbWENbStkQdVQtHMGpbsYsQjZK",
    "expiration_time": 1648381192,
    "payment_url": "http://example.com/pay/checkout-counter/202203271648380592218340"
  },
  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
}

响应字段说明

字段名	类型	说明
trade_id	string	Epusdt系统生成的交易号
order_id	string	商户订单号
amount	float	请求支付金额(CNY)
actual_amount	float	实际需要支付的USDT金额
token	string	钱包地址
expiration_time	integer	订单过期时间(时间戳)
payment_url	string	支付页面URL

异步通知处理

通知机制

当支付状态发生变化时，Epusdt会向商户配置的notify_url发送异步通知。商户服务器需要正确处理这些通知并返回响应。

重要提示：

1. 通知最多重试5次
2. 处理成功后必须返回字符串"ok"
3. 必须验证签名确保通知来源可信

通知参数

参数名	类型	说明
trade_id	string	Epusdt交易号
order_id	string	商户订单号
amount	float	订单金额(CNY)
actual_amount	float	实际支付USDT金额
token	string	钱包地址
block_transaction_id	string	区块链交易ID
signature	string	签名
status	int	订单状态(1:等待支付,2:支付成功,3:已过期)

状态码说明

Epusdt定义了丰富的状态码来帮助开发者定位问题：

状态码	含义
400	系统错误
401	签名认证失败
10002	订单已存在
10003	无可用钱包地址
10004	支付金额不满足最小单位
10005	无可用金额通道
10006	汇率计算错误
10007	订单已处理
10008	订单不存在
10009	参数解析失败

最佳实践建议

1. 订单号生成：建议使用时间戳+随机数的方式生成唯一订单号
2. 金额处理：注意金额单位转换，CNY和USDT的转换需要考虑汇率
3. 异常处理：做好网络异常和接口超时的处理
4. 日志记录：建议记录完整的请求和响应数据，便于排查问题
5. 幂等性处理：对于创建订单等操作要实现幂等性

通过合理使用Epusdt提供的API接口，开发者可以快速构建稳定可靠的USDT支付功能，满足各种业务场景的需求。