基于第三方heleket api接入usdt支付

news/2025/10/29 14:37:40/文章来源:https://www.cnblogs.com/yylucky666/p/19174373

app上要接入usdt区块链支付使用第三方通道heleket实现 heleket是国外网站，需要用魔法FQ. 官方文档地址 https://doc.heleket.com/methods/payments/qr-code-pay-form

测试页面

<!doctype html>
<html>
<head><meta charset="utf-8" /><title>USDT 支付示例（Heleket）</title><style>body { font-family: Arial, sans-serif; padding: 20px;}label { display:block; margin-top:10px; }input, select { padding:8px; width:300px; }button { margin-top:12px; padding:10px 16px; }#payFrame { width:100%; height:720px; border:1px solid #ccc; margin-top:20px; display:none; }</style>
</head>
<body>
<h2>创建 USDT 发票（Heleket）</h2><label>金额（例如 20）<input id="amount" value="20"></label>
<label>货币<select id="currency"><option value="USDT">USDT</option><option value="BTC">BTC</option>
</select></label>
<label>网络<select id="network"><option value="">（无）</option><option value="tron">tron</option><option value="bsc">bsc</option><option value="eth">eth</option>
</select></label><button id="payBtn">创建发票并跳转支付页面</button>
<button id="embedBtn">创建发票并在页面内嵌入支付页</button><iframe id="payFrame"></iframe><script>async function createInvoice(embed) {const amount = document.getElementById('amount').value;const currency = document.getElementById('currency').value;const network = document.getElementById('network').value;const payload = {amount: amount,currency: currency,network: network,// 若你有自己的 orderId 可传入; 否则后端会生成// orderId: 'order-12345'
        };const res = await fetch('/heleket/pay', {method: 'POST',headers: { 'Content-Type': 'application/json' },body: JSON.stringify(payload)});if (!res.ok) {alert('创建发票失败：' + res.statusText);return;}const json = await res.json();// Heleket 返回格式示例: { state:0, result: { url: "https://pay.heleket.com/pay/....", ... } }
        const result = json.result || json;const url = (result && result.url) ? result.url : (json.url || null);if (!url) {alert('未收到支付 URL，详见控制台');console.log(json);return;}if (embed) {document.getElementById('payFrame').style.display = 'block';document.getElementById('payFrame').src = url;} else {// 跳转到支付页
            window.location.href = url;}}document.getElementById('payBtn').addEventListener('click', () => createInvoice(false));document.getElementById('embedBtn').addEventListener('click', () => createInvoice(true));
</script>
</body>
</html>

sql脚本

CREATE TABLE `payment_order` (`id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID，自增',`order_id` varchar(64) NOT NULL COMMENT '商户自定义订单号（业务系统唯一）',`invoice_uuid` varchar(64) DEFAULT NULL COMMENT 'Heleket返回的发票唯一UUID',`amount` decimal(20,8) DEFAULT NULL COMMENT '订单金额（下单金额）',`currency` varchar(16) DEFAULT NULL COMMENT '币种，例如 USDT、BTC 等',`network` varchar(16) DEFAULT NULL COMMENT '区块链网络，例如 tron、bsc、eth 等',`address` varchar(128) DEFAULT NULL COMMENT '收款地址（Heleket提供的收款钱包地址）',`payer_amount` decimal(20,8) DEFAULT NULL COMMENT '用户实际支付金额（回调时返回）',`txid` varchar(128) DEFAULT NULL COMMENT '交易哈希（区块链交易ID）',`status` varchar(32) DEFAULT NULL COMMENT '订单状态，例如 pending、paid、confirmed、failed',`created_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',`updated_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',PRIMARY KEY (`id`),UNIQUE KEY `order_id` (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='USDT等加密货币支付订单表（Heleket支付对接）';

🧩 一、接入目标

Heleket 是一个支持 USDT、TRC20、BEP20、ETH 等多链支付的加密支付网关。
我们接入它的核心目的是：
✅ 创建支付订单（invoice）
✅ 生成二维码支付页
✅ 接收支付结果回调

⚙️ 二、核心接口说明

功能	API 路径	Java 方法	说明
创建支付发票	`/v1/payment`	`createInvoice()`	商户生成订单并获得支付链接
生成静态钱包二维码	`/v1/wallet/qr`	`createQrForm()`	用于展示收款钱包二维码
为发票生成二维码	`/v1/payment/qr`	`createTicketQr()`	生成指定发票的二维码
（可选）查询订单	`/v1/payment/info`	自行封装	查询发票状态、交易记录

🏗️ 三、项目结构推荐

com.zoneyet.buinsess.channel.usdtpay
│
├── config
│   └── HeleketConfig.java            # Heleket 商户配置类（merchantId、apiKey、apiBase）
│
├── request                           # 所有请求实体类
│   ├── HeleketInvoiceRequest.java
│   ├── HeleketQrPayRequest.java
│   └── HeleketQrTicketRequest.java
│
├── response                          # 所有响应实体类
│   ├── HeleketInvoiceResponse.java
│   ├── HeleketQrPayResponse.java
│   └── HeleketBaseResponse.java（可选）
│
├── service
│   └── HeleketService.java           # 所有 Heleket API 封装（统一签名 + 调用）
│
└── controller└── PaymentController.java        # 暴露给前端的支付接口

🔐 四、签名规则（Heleket 官方规范）

每个请求都要带上签名头部：

Header	说明
`merchant`	商户编号（从 Heleket 后台获取）
`sign`	签名字符串（Base64(JSON体) + apiKey 后取 MD5）

签名步骤：

请求头：

🚀 五、接口调用示例

1️⃣ 创建支付订单

请求（HeleketInvoiceRequest）：

响应（HeleketInvoiceResponse）：

2️⃣ 生成二维码支付表单

请求（HeleketQrPayRequest）：

响应（HeleketQrPayResponse）：

3️⃣ 回调通知（Heleket → 商户）

Heleket 在交易确认后会回调你配置的 url_callback。
回调内容示例：

建议回调接口返回：

🧰 六、前后端交互流程（时序）

🔧 七、调试建议

环节	建议
签名错误	检查 Base64 编码和 MD5 拼接是否一致
API 错误	打印完整日志（request + response）
超时	Heleket 建议 10s 超时，可用 `RestTemplateBuilder` 设置
JSON 解析	确保字段类型（amount 建议用 String）