Xboard 和 V2Board 是销售 VPN 和代理订阅的常用面板。默认情况下，用户通过银行卡或您自己托管的网关付款。本指南介绍如何加入加密货币支付：用户使用 TRC20、ERC20 或 BEP20 网络的 USDT 或其他币种付款，面板自动开通订单。无需自建钱包、节点或自托管网关，资金直接进入您的 SnapEX Pay 商户余额。
支付流程
用户 → 面板下单 → SnapEX Pay 收银台
SnapEX Pay → 签名 Webhook → 面板
插件 → 通过 API 查询账单 → paid?
面板 → 开通订单
- 下单时，插件为订单创建一张 SnapEX Pay 账单（面板的
trade_no作为账单的external_id），并把用户跳转到收银台。 - 用户选择币种并付款。账单支付完成后，SnapEX Pay 向面板发送签名 Webhook。
- 插件校验签名，通过 SnapEX Pay API 查询账单，只有状态为
paid时才把订单标记为已支付。
准备条件
- 带插件系统的 Xboard（PHP 8.2+），或 V2Board / 从
app/Payments加载网关的旧版 Xboard（PHP 7.3+）。 - PHP cURL 扩展。
- 面板可通过公网 HTTPS 访问：SnapEX Pay 只向公网 HTTPS 地址发送 Webhook。
- SnapEX Pay 商户账户：在 pay.snapex.pro 注册。
第 1 步：安装插件
下载压缩包 snapexpay-xboard-1.2.0.zip（MIT 许可，免费）。
Xboard。 后台 → 插件 → 上传 ZIP → 安装 → 启用「SnapEX Pay」。也可以把压缩包解压到面板目录：
cd /path/to/Xboard
curl -fsSLO https://pay.snapex.pro/downloads/xboard/snapexpay-xboard-1.2.0.zip
unzip snapexpay-xboard-1.2.0.zip
mv snapexpay-xboard-1.2.0 plugins/Snapexpay
目录名必须正好是 plugins/Snapexpay——Linux 下区分大小写。然后 插件 → 安装 → 启用。
V2Board 和旧版 Xboard。 从压缩包中复制一个文件到面板：
unzip -p snapexpay-xboard-1.2.0.zip \
snapexpay-xboard-1.2.0/app/Payments/SnapexPay.php \
> /path/to/v2board/app/Payments/SnapexPay.php
如果使用 OPcache 或 Octane，请重启 PHP-FPM 或 Octane。请确认 V2Board 设置中已填写站点地址（app_url）：否则付款后插件无法把用户带回订单页。
第 2 步：获取 API 密钥
在 SnapEX Pay 商户后台打开 Developers 页面，生成 API 密钥。密钥只显示一次，请立即复制。后台生成的密钥自动拥有 Merchant API 的全部权限，包括插件需要的 invoices.read 和 invoices.write。重新生成密钥会立即作废旧密钥，因此请同时更新面板中的配置。
第 3 步：添加支付方式
面板后台 → 支付配置 → 添加支付方式 → 网关选择 SnapexPay。各字段：
- API key：第 2 步的密钥。
- Webhook secret：在第 4 步填写。
- Network fee paid by：
merchant（默认），用户正好支付订单金额；customer，网络费用加在用户应付金额之上。详见：加密货币账单的手续费由谁支付。 - Payment window, minutes：账单可支付的分钟数。Xboard 默认 60，最多 120；V2Board 默认 20，最多 30。上限低于面板自身取消未支付订单的时间，避免用户为已被面板取消的订单付款。
- USD per 1 shop currency：价格为 USD 时填
1。面板以「分」存储金额，插件发送total / 100 × usd_rate。CNY 店铺约为0.14。这是固定汇率，汇率变化时需要您自己更新。 - Environment：
live或test（见第 5 步）。 - Partner ID：自行配置请留空；如果是集成商为您接入，这里填写其 ID。
- API URL：保留默认值
https://snapex.pro/api/v1/merchant。
账单最低金额为 0.50 USD：换算后低于该金额的订单在下单时会报错。
第 4 步：配置 Webhook
面板中每个支付方式都有自己的回调地址：
https://your-panel.example/api/v1/guest/payment/notify/SnapexPay/{uuid}
Xboard 会在支付方式列表中显示完整地址。在商户后台 Developers 页面把它填为 Webhook 地址并保存。签名密钥 whsec_… 只在第一次保存后显示一次——请把它复制到支付方式的 Webhook secret 字段。
商户后台每个账户只有一个 Webhook 地址，所有事件都发送到这里。插件只在账单已支付时开通订单；对其他事件，面板会返回错误（Xboard 为 422，V2Board 为 500）。在投递日志中这显示为投递失败——属于正常现象。
插件如何校验通知：
Webhook-Signature请求头：用您的密钥对{Webhook-Timestamp}.{原始请求体}计算 HMAC-SHA256；Webhook-Timestamp与服务器时间相差不超过 5 分钟——请保持 NTP 开启；- 账单本身：用您的密钥通过 SnapEX Pay API 重新查询，只有状态为
paid时订单才会被标记为已支付。
关于签名和重试的更多内容：加密货币支付 Webhook。
第 5 步：不用真实资金测试订单
- 把 Environment 设为
test并保存。 - 在面板中创建订单并进入支付。
- SnapEX Pay 页面会显示 Test 标记。任选币种和网络：页面显示测试地址，大约 10 秒后支付自动确认，无需转账。
- 订单应在几秒内变为已支付。如果没有，请查看 Developers 页面上的投递日志和面板日志（
storage/logs）。 - 把 Environment 改回
live。
支付方式处于 test 时，通过它支付的任何订单都会在没有真实资金的情况下开通，所以请尽快完成测试。改回 live 后，插件会拒绝测试账单，测试付款无法开通真实订单。详见：如何不用真实资金测试加密货币支付。
用户看到什么
SnapEX Pay 收银台，可选择币种：TRC20、ERC20、BEP20 网络的 USDT，以及 SnapEX Pay 针对该账单金额提供的其他币种（共 50 多种）。用户再次点击「支付」时，只要账单仍有效，就会打开同一张账单；如果已过期，会为同一订单创建新账单（external_id 为 {trade_no}-1、-2 等）。
如果用户少付，订单不会开通：已收到的金额进入您的 SnapEX Pay 余额，差额由您与用户协商处理。少付的处理方式：用户付款不足怎么办。
常见问题排查
- 网关列表中没有 SnapexPay（Xboard）。 目录必须正好是
plugins/Snapexpay，插件需已安装并已启用。 - 下单时提示「A valid merchant API key is required」或「This source IP is not allowed」。 密钥错误或已作废，或者密钥的 IP 白名单不包含面板服务器的出口 IP。
- 提示「Amount is below the … USD minimum」。 换算后订单金额低于 0.50 USD——请检查 USD per 1 shop currency。
- 用户已付款，订单仍未支付。 查看商户后台的投递日志。常见原因：Webhook secret 不匹配、服务器时间偏差超过 5 分钟、地址指向了其他支付方式的 UUID、反向代理修改了请求体，或面板无法访问 SnapEX Pay API。失败的投递可以在日志中重新发送。
费用
每笔支付 1%，无开户费，无月费。插件免费。
插件页面：Xboard / V2Board。VPN 服务概览：VPN 加密货币支付。注册：pay.snapex.pro。