购买套餐
{{dashboard.subscription?('当前套餐：'+dashboard.subscription.plan_name+' · 到期 '+fmt(dashboard.subscription.expires_at)):'先购买有效套餐，开启站点创建和收款能力。'}}
Getting Started
使用步骤
按顺序完成套餐、钱包、站点和接口接入；下方继续保留经营数据。
配置钱包
新增 USDT-TRC20 或 Binance 钱包，作为用户付款的收款方式。
创建站点
填写站点名称、回调地址和返回地址，并选择可用钱包。
接入接口
保存 API Key、API Secret 和 Webhook Secret，由服务端创建支付订单。
近 14 天支付订单
按创建时间统计，深色为成功支付订单
订单状态
当前账户全部支付订单分布
{{payStatusText(s)}}
{{dashboard.status_counts&&dashboard.status_counts[s]||0}}套餐与配置
站点、钱包和套餐用量
站点额度{{dashboard.usage&&dashboard.usage.site_used||0}} / {{dashboard.usage&&dashboard.usage.site_limit||0}}
本月订单额度{{dashboard.usage&&dashboard.usage.monthly_order_limit?((dashboard.usage.monthly_orders||0)+' / '+dashboard.usage.monthly_order_limit):((dashboard.usage&&dashboard.usage.monthly_orders||0)+' / 不限')}}
本月交易额{{dashboard.usage&&dashboard.usage.monthly_volume_limit?((dashboard.usage.monthly_volume||'0.000000')+' / '+dashboard.usage.monthly_volume_limit+' USDT'):((dashboard.usage&&dashboard.usage.monthly_volume||'0.000000')+' USDT / 不限')}}
站点{{dashboard.site_stats&&dashboard.site_stats.active||0}} active
钱包{{dashboard.wallet_stats&&dashboard.wallet_stats.active||0}} active
币安钱包{{dashboard.wallet_stats&&dashboard.wallet_stats.binance||0}}
回调失败{{dashboard.webhooks&&dashboard.webhooks.failed||0}}
站点表现
按收款金额和订单数排序
{{site.name}}{{site.domain}}
{{site.paid_amount}} USDT{{site.total_orders}} 单
暂无站点数据
近期订单
最新 6 笔商户支付订单
| 支付编号 | 站点 | 标题 | 金额 | 状态 | 创建时间 |
|---|---|---|---|---|---|
| {{o.payment_id}} | {{o.site_name}} | {{o.subject}} | {{o.pay_amount}} USDT | {{payStatusText(o.status)}} | {{fmt(o.created_at)}} |
| 暂无订单 | |||||
Subscription
套餐订阅
有效期内续费会从当前到期时间累加
{{plan.name}}
USDT{{Number(plan.price)}} USDT
{{plan.description}}
- {{plan.duration_days}} 天有效期
- {{plan.site_limit}} 个站点
- {{plan.monthly_order_limit||'不限'}} 笔/月
购买记录
未完成订单可继续支付或取消
| 订单号 | 套餐 | 应付金额 | 状态 | 到期 | 操作 |
|---|---|---|---|---|---|
| {{o.order_no}} | {{o.plan_name}} | {{o.pay_amount}} USDT | {{payStatusText(o.status)}} | {{fmt(o.expires_at)}} | - |
| 暂无购买记录 | |||||
Wallets
钱包配置
先维护钱包类型和地址，站点只选择钱包类型
| 钱包类型 | 名称 | 账号 / 地址 | 状态 | 操作 |
|---|---|---|---|---|
| {{w.wallet_type}} {{walletProviderLabel(w)}} · {{walletDetail(w)}} | {{w.name}} | {{walletDisplay(w)}} | {{w.status}} | |
| 尚未配置钱包 | ||||
Merchant Sites
商户站点
每个站点拥有独立密钥，并从钱包配置中选择收款类型
| 站点 | 钱包类型 | API Key | 状态 | 操作 |
|---|---|---|---|---|
| {{s.name}} | {{s.wallets&&s.wallets.length?('已选 '+s.wallets.length+' 个钱包'):'未选择'}} {{s.wallet_name||short(s.wallet_address)}} | {{s.api_key}} | {{s.status}} | |
| 尚未创建站点 | ||||
Payments
支付订单
查看链上确认与回调状态
| 支付编号 | 商户订单 | 标题 | 应付金额 | 网络 | 状态 | 倒计时 | 操作 | 确认数 | 创建时间 |
|---|---|---|---|---|---|---|---|---|---|
| {{o.payment_id}} | {{o.merchant_order_no}} | {{o.subject}} | {{o.pay_amount}} | {{o.network}} | {{o.status}} | {{orderCountdown(o)}} | - | {{o.confirmations}} | {{fmt(o.created_at)}} |
| 暂无订单 | |||||||||
{{orderPage}} / {{Math.max(1,Math.ceil(orderTotal/20))}}
Support Tickets
工单处理
处理用户在支付页提交的问题反馈
| 工单号 | 支付订单 | 站点 | 问题原因 | 状态 | 提交时间 | 操作 |
|---|---|---|---|---|---|---|
| {{t.ticket_no}} | {{t.payment_id}} {{t.merchant_order_no}} | {{t.site_name}} | {{t.reason}} | {{ticketStatusText(t.status)}} | {{fmt(t.created_at)}} | |
| 暂无工单 | ||||||
{{ticketPage}} / {{Math.max(1,Math.ceil(ticketTotal/20))}}
Integration
接入文档
默认使用快速接入：创建订单、拿到 checkout_url、跳转收银台，支付结果以 Webhook 为准。
API Base
下载本地对接包{{apiOrigin}}/api/v1对接方案
根据你的站点类型选择最短路径
快速接入
- 在“钱包配置”添加收款钱包，再到“商户站点”为站点选择默认钱包。
- 在站点里填写 notify_url 和 return_url，后台配置优先级高于代码传参。
- 服务端调用简单创建接口，只传 order_no、amount、title。
- 接口返回 checkout_url，你的网站把用户跳转过去付款。
- 收到 Webhook 后按 order_no 更新本地订单。
默认钱包、网络、回调地址和返回地址都放在后台配置，代码里只处理订单本身。
自定义后端接入
- 在“商户站点”创建站点，只填写回调地址 notify_url 和付款完成返回地址 return_url。
- 在“钱包配置”维护收款钱包，并为站点选择一个或多个可用钱包。
- 保存 API Key、API Secret、Webhook Secret。
- 业务后端创建本地订单后，调用创建支付订单接口获取 checkout_url。
- 前端跳转到 checkout_url，用户在收银台选择钱包并付款。
- 收到 Webhook 后验签，按 merchant_order_no 更新本地订单。
WordPress Plugin 接入
- 在 WordPress 后台上传并启用 bestuPay 插件。
- 插件设置中填写 API Base、API Key、API Secret、Webhook Secret。
- 回调地址填写插件提供的 notify URL，返回地址填写订单详情页或会员中心地址。
- 选择订单创建时机：下单后立即创建支付，或用户选择 USDT 支付方式时创建。
- 插件收到 payment.paid 回调后，将本地订单标记为已支付。
插件模式仍依赖服务端签名；不要在主题 JS 或页面短代码中暴露 API Secret。
WooCommerce 支付网关
- 在 WooCommerce 支付方式中启用 bestuPay USDT。
- 把 WooCommerce 订单号作为 merchant_order_no，订单金额作为 amount。
- 创建支付订单成功后，将用户重定向到 checkout_url。
- Webhook 验签成功且 status=paid 时调用 payment_complete，并记录 tx_hash。
- expired、underpaid、overpaid 建议保留为待处理或人工审核，避免自动发货。
独立收银台跳转
- 你的系统只负责创建订单和重定向，收款地址、二维码、剩余时间由 bestuPay 收银台展示。
- 支付页支持用户在站点已选钱包之间切换，历史订单保留创建时的钱包快照。
- 支付完成后用户可返回 return_url，真实订单状态以 Webhook 或查询接口为准。
return_url 只用于用户跳转展示，不能作为发货依据。发货必须依赖 Webhook 验签或服务端查询结果。
高级安全接入
- 适合交易量较大、需要 nonce 防重放和完整 HMAC 签名的商户。
- 请求头带 API Key、时间戳、Nonce 和签名。
- 请求体使用 merchant_order_no、amount、network、subject 等完整字段。
- Webhook 仍使用 Webhook Secret 验签。
创建支付订单
推荐默认使用，字段最少，适合大多数商户
所有支付订单都必须由服务端创建。平台返回 checkout_url 后，你的网站再把用户跳转过去。
MethodPOST
Path
{{apiOrigin}}/api/v1/simple/paymentsAuth
Authorization: Bearer 你的 API Secret请求示例
Content-Type: application/json{
"order_no": "site_order_202609200001",
"amount": "100.00",
"title": "商品标题"
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
order_no | string | 是 | 你的系统订单号。同一站点内必须唯一，用于 Webhook 回调后匹配本地订单。 |
amount | decimal string | 是 | 订单原始金额，单位 USDT。最多 2 位小数，例如 100.00。 |
title | string | 是 | 订单标题，会在后台和订单查询中展示，建议传商品名或订单摘要。 |
notify_url | url | 否 | 代码里的回调地址。后台站点已配置时，后台优先；只有后台留空才使用这里。 |
return_url | url | 否 | 用户付款后返回你网站的页面。不能作为发货依据，真实状态以 Webhook 或查询接口为准。 |
expires_in | integer | 否 | 订单过期秒数，范围 300 到 86400。不传时使用平台默认值。 |
notify_url、return_url、默认钱包都优先读取站点配置；只有后台留空时，接口传入的 notify_url 和 return_url 才会生效。
创建支付订单
使用 HMAC 签名、时间戳和 Nonce 做请求校验
高级接口使用 HMAC 签名，适合需要更强请求校验的商户系统。
MethodPOST
Path
{{apiOrigin}}/api/v1/paymentsAuth
X-API-Key + X-Signature请求示例
Content-Type: application/json{
"merchant_order_no": "site_order_202609200001",
"amount": "100.00",
"network": "TRC20",
"subject": "商品标题",
"notify_url": "https://example.com/bestupay/notify",
"return_url": "https://example.com/orders/site_order_202609200001",
"expires_in": 1800
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
merchant_order_no | string | 是 | 你的系统订单号。同一站点内必须唯一，重复创建会返回已存在订单的 payment_id。 |
amount | decimal string | 是 | 订单原始金额，单位 USDT。最多 2 位小数，例如 100.00。 |
network | string | 是 | 当前支持 TRC20。快速接口默认使用 TRC20。 |
subject | string | 是 | 订单标题，展示在后台订单列表和订单详情中。 |
notify_url | url | 否 | 代码里的回调地址。后台站点已配置时，后台优先；只有后台留空才使用这里。 |
return_url | url | 否 | 用户付款后返回你网站的页面。不能作为发货依据。 |
expires_in | integer | 否 | 订单过期秒数，范围 300 到 86400。不传时使用平台默认值。 |
终端用户不能自己拼接支付链接。后台配置的 notify_url 和 return_url 优先级高于这里传入的值。
快速接入示例
创建成功后直接 302 跳转或返回给前端跳转
$payload = [
'order_no' => 'site_order_202609200001',
'amount' => '100.00',
'title' => 'Product title',
];
$ch = curl_init('https://your-domain.com/api/v1/simple/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiSecret,
],
CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_SLASHES),
]);
$res = json_decode(curl_exec($ch), true);
header('Location: ' . $res['data']['checkout_url']);
const payload = {
order_no: 'site_order_202609200001',
amount: '100.00',
title: 'Product title'
};
const res = await fetch('https://your-domain.com/api/v1/simple/payments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiSecret}`
},
body: JSON.stringify(payload)
});
const json = await res.json();
response.redirect(json.data.checkout_url);
import requests
payload = {
"order_no": "site_order_202609200001",
"amount": "100.00",
"title": "Product title",
}
res = requests.post(
"https://your-domain.com/api/v1/simple/payments",
json=payload,
headers={"Authorization": f"Bearer {api_secret}"},
)
checkout_url = res.json()["data"]["checkout_url"]
String body = """
{"order_no":"site_order_202609200001","amount":"100.00","title":"Product title"}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://your-domain.com/api/v1/simple/payments"))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + apiSecret)
.POST(HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
body := strings.NewReader(`{"order_no":"site_order_202609200001","amount":"100.00","title":"Product title"}`)
req, _ := http.NewRequest("POST", "https://your-domain.com/api/v1/simple/payments", body)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+apiSecret)
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
签名规则
商户 API 请求头：
X-API-Key: 你的 API Key X-Timestamp: 当前 Unix 秒级时间戳 X-Nonce: 每次请求唯一随机字符串 X-Signature: HMAC-SHA256 签名
签名原文
METHOD|/api/v1/payments|timestamp|nonce|sha256(rawBody)| 请求头 | 说明 |
|---|---|
X-API-Key | 站点 API Key，用于定位商户站点。 |
X-Timestamp | 当前 Unix 秒级时间戳，超出允许窗口会被拒绝。 |
X-Nonce | 每次请求唯一随机字符串，已使用的 Nonce 不能重复。 |
X-Signature | 使用 API Secret 对签名原文计算 HMAC-SHA256 后转小写十六进制。 |
GET 请求没有 body 时，rawBody 按空字符串计算。
订单返回与查询
创建成功后使用 checkout_url 跳转用户付款
返回示例
快速接口只返回核心字段；高级接口会返回更多钱包信息{
"success": true,
"data": {
"payment_id": "pay_xxxxxxxxxxxxxxxxxxxxxxxx",
"checkout_url": "https://pay.example.com/checkout/?payment_id=pay_xxx",
"address": "T...",
"requested_amount": "100.000000",
"pay_amount": "100.003421",
"qr_content": "T...",
"expires_at": "2026-09-20T21:34:46+08:00"
}
}| 字段 | 说明 |
|---|---|
payment_id | 平台支付订单号，用于查询订单、取消订单和拼接收银台链接。 |
checkout_url | 用户付款页面。你的网站应跳转到这个地址，不要让终端用户自己拼接支付链接。 |
requested_amount | 原始订单金额，单位 USDT。 |
pay_amount | 用户需要精确支付的金额。平台会加唯一小数尾数用于识别订单。 |
address | 创建订单时选中的收款地址或钱包地址快照。 |
expires_at | 订单过期时间，ISO 8601 格式。 |
| 接口 | 用途 | 鉴权 |
|---|---|---|
GET /api/v1/payments/{payment_id} | 查询单笔订单状态 | HMAC |
GET /api/v1/payments?status=pending | 按状态分页查询订单 | HMAC |
POST /api/v1/payments/{payment_id}/cancel | 取消仍处于 pending 的订单 | HMAC |
Webhook 回调
真实支付结果以 Webhook 或服务端查询为准
订单状态变化后平台向 notify_url 推送 JSON。验签成功后再更新本地订单，并返回 HTTP 2xx。
请求头
X-BestuPay-Signature: HMAC-SHA256(raw JSON body, Webhook Secret) X-BestuPay-Event: 回调事件 ID
{
"event_id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
"event_type": "payment.paid",
"payment_id": "pay_xxx",
"merchant_order_no": "site_order_202609200001",
"status": "paid",
"requested_amount": "100.000000",
"pay_amount": "100.003421",
"received_amount": "100.003421",
"address": "T...",
"timestamp": 1790000000,
"tx_hash": "..."
}| 字段 | 说明 |
|---|---|
event_id | 回调事件 ID，建议用于幂等处理，避免重复发货。 |
event_type | 事件类型，例如 payment.paid、payment.expired。 |
payment_id | 平台支付订单号。 |
merchant_order_no | 你的系统订单号。快速接口对应 order_no。 |
status | 订单最新状态。发货通常只接受 paid。 |
requested_amount | 原始订单金额。 |
pay_amount | 用户应付的精确金额。 |
received_amount | 链上实际到账金额。 |
address | 收款地址或钱包地址。 |
timestamp | 回调生成时的 Unix 秒级时间戳。 |
tx_hash | 链上交易哈希，未检测到交易时可能为空。 |
Webhook 可能因网络原因重试。你的业务系统应按 event_id 或 payment_id 做幂等处理。
订单状态说明
| 状态 | 含义 | 建议处理 |
|---|---|---|
pending | 等待用户付款 | 继续展示收银台，不发货 |
confirming | 已检测到账，等待链上确认数达标 | 等待 Webhook 或查询变为 paid |
paid | 支付成功 | 可以按业务规则发货或开通服务 |
expired | 订单已过期 | 让用户重新创建订单 |
underpaid | 少付 | 人工核对或联系用户补差额 |
overpaid | 多付 | 人工核对，多余金额按你的规则处理 |
manual_review | 需要人工处理 | 查看链上交易和工单后处理 |
cancelled | 订单已取消 | 不再接受该订单支付 |
签名示例
按开发语言切换
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = time();
$nonce = bin2hex(random_bytes(12));
$canonical = 'POST|/api/v1/payments|' . $timestamp . '|' . $nonce . '|' . hash('sha256', $body);
$signature = hash_hmac('sha256', $canonical, $apiSecret);
const crypto = require('crypto');
const body = JSON.stringify(payload);
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomBytes(12).toString('hex');
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
const canonical = `POST|/api/v1/payments|${timestamp}|${nonce}|${bodyHash}`;
const signature = crypto.createHmac('sha256', apiSecret).update(canonical).digest('hex');
import hashlib, hmac, json, secrets, time
body = json.dumps(payload, separators=(',', ':'), ensure_ascii=False)
timestamp = str(int(time.time()))
nonce = secrets.token_hex(12)
body_hash = hashlib.sha256(body.encode()).hexdigest()
canonical = f"POST|/api/v1/payments|{timestamp}|{nonce}|{body_hash}"
signature = hmac.new(api_secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
String bodyHash = sha256Hex(body);
String canonical = "POST|/api/v1/payments|" + timestamp + "|" + nonce + "|" + bodyHash;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(apiSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String signature = HexFormat.of().formatHex(mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8)));
bodyHash := sha256.Sum256(body)
canonical := fmt.Sprintf("POST|/api/v1/payments|%s|%s|%x", timestamp, nonce, bodyHash)
mac := hmac.New(sha256.New, []byte(apiSecret))
mac.Write([]byte(canonical))
signature := hex.EncodeToString(mac.Sum(nil))
Webhook Logs
回调记录
查看 Webhook 推送状态、响应码和重试情况。
| 事件 ID | 支付订单 | 站点 | 事件类型 | 目标地址 | 状态 | 响应码 | 次数 | 下次重试 | 送达时间 | 创建时间 | 响应内容 | 操作 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {{w.event_id}} | {{w.payment_id||'-'}} {{w.merchant_order_no||w.subject||'-'}} | {{w.site_name}} | {{w.event_type}} | {{w.target_url}} | {{webhookStatusText(w.status)}} | {{w.response_status||'-'}} | {{w.attempt_count}} | {{fmt(w.next_attempt_at)}} | {{fmt(w.delivered_at)}} | {{fmt(w.created_at)}} | {{w.response_body||'-'}} | - |
| 暂无回调记录 | ||||||||||||
{{webhookPage}} / {{Math.max(1,Math.ceil(webhookTotal/20))}}
Payment Button
付款按钮
适合没有后端签名能力的页面，复制链接或嵌入代码即可发起固定金额付款。
账户设置
管理个人资料和登录安全
个人资料
修改密码
最近登录
| 时间 | IP 地址 | 结果 | 设备 |
|---|---|---|---|
| {{fmt(r.created_at)}} | {{r.ip_address}} | {{r.successful==1?'成功':'失败'}} | {{r.user_agent}} |
| 暂无登录记录 | |||
{{loginPage}} / {{Math.max(1,Math.ceil(loginTotal/20))}}