BoltUtil 使用指南：稳定币收款、店铺接入与支付排障

BoltUtil 是面向开发者、SaaS 和数字业务商户的非托管稳定币收款工具：客户将 USDT 或 USDC 转入商户配置的钱包，BoltUtil 核对链上付款，达到确认条件后把结果通知业务系统。它把“收款地址、支付订单、付款确认、业务交付”连接起来，减少依靠截图查账和人工开通服务的环节。

这篇指南介绍收款 API、钱包收银台、WooCommerce 插件以及配套排障工具，帮助你判断是否适合自己的业务，并按实际流程开始接入。功能与文档核对日期为 2026 年 10 月 14 日；可用渠道以当前启用状态和商户配置为准。

什么业务适合使用 BoltUtil

如果客户已经持有稳定币，而你的系统需要根据付款自动开通服务、交付数字商品或给账户入账，BoltUtil 可以承担链上付款与业务订单之间的连接工作。

• SaaS 与会员服务：付款确认后，由你的后端按业务规则开通对应权益。收款接口本身不等于自动续费授权。
• 数字产品：把付款结果关联到商品订单，驱动许可证发放、下载权限或内容访问。
• 账户充值：将确认后的付款记入业务账户，同时通过幂等逻辑避免重复入账。
• WooCommerce 商店：使用插件接入收银台和订单状态核验，减少单独编写支付对接代码的工作。

BoltUtil 的前提是客户会使用相应网络的钱包。它不会把银行卡付款自动变成稳定币，也不能消除选错网络、钱包密钥管理或代币版本带来的风险。非托管意味着收款直接进入商户钱包，商户仍需管理钱包及资金。

它解决哪些常见痛点

收款后，不知道对应哪一笔订单

只公开一个钱包地址，通常还需要人工比对转账与业务订单。BoltUtil 从商户后端创建支付订单，结合网络、币种、地址、金额等条件核对付款，再把结果关联到订单。商户需要保留自己的订单号与支付订单之间的映射。

客户提交了交易，系统却不知道何时交付

钱包提交交易、链上执行成功、达到付款确认条件和商户收到通知，是不同环节。BoltUtil 提供付款状态与签名 Webhook，让后端据此处理交付。不能仅凭客户返回成功页面、截图或提供一个交易哈希就发货。

每个项目都要重新做支付排障

实际接入常见的问题不是少一个按钮，而是金额被取整、币种版本不一致、确认尚未完成，或者回调验签失败。交易检测器和 Webhook 测试器分别帮助核对付款信息与调试通知接收逻辑，缩短定位问题的路径。

支持哪些网络和币种

当前公开文档列出六条网络。TRON 支持 USDT；Ethereum、BNB Smart Chain、Polygon、Solana 和 Base 支持 USDT 与 USDC。下图统计的是文档列出的币种数量，不是交易速度、成功率、费用或实测性能。

同名币种也需要区分代币版本。Ethereum、Polygon、Solana 和 Base 的 USDC 为 Circle 原生 USDC；BNB Smart Chain 使用 Binance-Peg USDC。Base 的 USDT 为桥接版本。接入前应核对官方指南中的合约和网络，不能仅凭钱包里显示的代币名称判断是否支持。

从创建订单到业务交付，如何使用

第一步：配置收款钱包与服务端凭据

在 BoltUtil 配置计划启用网络的有效收款地址，准备 API Key 和 Webhook 配置。收款地址不需要钱包私钥或助记词。API Key 用于 API 认证，Webhook 密钥用于验证付款通知，两者用途不同。

这些凭据应保存在服务端。不要把 API Key 或 Webhook 密钥放进公开网页、前端 JavaScript、截图或代码仓库。开始创建订单前，可按开发文档通过 ping 接口检查 API Key；建单还需要请求签名和时间戳。

第二步：由后端创建支付订单

商户后端调用 POST /api/v1/order/create，传入商户订单号、金额、币种和网络。字段、签名规则及响应结构以当前开发文档为准。

保存响应中的支付订单信息，并使用返回的 checkoutUrl 引导客户付款。若自行展示支付信息，应完整采用 payment 中的地址、网络、币种及 payment.amount。payment.qrData 是用于生成二维码的内容，不是可直接显示的二维码图片。

不要自行修改最终应付金额。比如收银台显示 199.001，就不能为了界面整洁让客户转 199。这个例子仅说明保留精度的要求，不代表固定收费或每笔订单的实际金额。

第三步：让客户选择钱包快捷支付或手动转账

收银台支持钱包快捷支付，也保留扫码或复制地址的手动转账方式。快捷支付可以减少手动填写地址和金额的步骤，但仍需客户核对信息并在钱包中授权。首次连接、切换网络和钱包解锁可能需要额外操作，可用钱包随设备与网络变化。

手动付款时，客户需要使用指定的网络和币种，转入正确地址，填写完整金额，并准备支付网络手续费所需的原生币。不要为同一订单重复付款。

第四步：等待确认，再可靠处理通知

后端收到通知后，先按当前回调协议验证原始请求体签名、时间戳及事件与业务订单的关联，检查应付金额、实付金额、状态和结算类型。人工接受少付的付款，实付金额可能低于应付金额，业务逻辑必须识别这个分支。

将事件写入数据库或可靠队列后再返回 HTTP 2xx。按实际回调的事件标识去重，同时确保同一个业务订单不会重复交付。通知可以重复到达，客户也可能重复刷新页面，付款处理必须能够安全重试。

确认速度受网络和渠道规则影响。例如 Base 指南说明需等待以太坊最终确认，通常约 20 分钟，也可能更久。不要向客户承诺所有网络都能秒到账；付款在有效期内发起与确认结果稍后到达，需要在界面中清楚区分。

WooCommerce 店铺如何开始

WooCommerce 插件适合希望直接在店铺里增加稳定币付款方式的商户。当前范围是 USD 店铺，不提供实时汇率报价；不能直接把其他店铺货币的数值当作美元金额使用。

• 从官方 GitHub Releases 下载带版本号的插件安装 ZIP，在 WordPress 上传安装并启用；不要把自动生成的源码压缩包当作安装包。
• 检查 WordPress、PHP、WooCommerce 版本要求和 HTTPS，将店铺货币设为 USD。
• 在 BoltUtil 准备 LIVE API Key，并为启用的网络配置有效收款地址。
• 将插件设置中显示的店铺 Webhook 地址配置到 API Key 所属商户下，启用 Webhook 并保存对应密钥。
• 在插件中填写 API Key 与 Webhook 密钥，选择币种和网络，保存后验证完整订单流程。

顾客返回店铺不是付款凭证。插件核验签名回调并复查支付状态，也会定时查询；核验通过后才更新订单。上线前应使用自己控制的钱包做小额付款验收，检查收银台、付款确认、回调、店铺订单和交付结果，而不是只确认插件已启用。

三个配套工具，分别用于什么问题

稳定币交易检测器：定位付款信息差异

打开工具中心的交易检测器，选择网络和币种，输入真实交易哈希查询。查询成功后可查看转入地址、金额、区块及确认信息，再填写订单要求进行对比。

排查时依次核对网络、币种与合约、收款地址、完整金额、确认要求和订单有效状态。页面的“填入示例”使用虚构信息，适合先理解核对界面；示例核对通过不代表查到了真实交易。

这个工具提供查询与对比线索，不会替你完成订单，也不能仅凭全部填写项通过就认定业务已到账。历史交易、订单关联和时间条件仍需结合真实订单核验。

Webhook 签名测试器：调试接收端验签

填写测试接收地址、测试 Webhook 密钥和毫秒时间戳，编辑示例 JSON。工具会在浏览器中生成 HMAC-SHA256 签名和对应 cURL 请求。它只生成请求，不会自动向该地址发起通知；需要你在自己的测试环境执行。

签名规则使用时间戳、一个英文句点和请求体原文。JSON 的空格、换行或字段顺序发生变化，都可能改变签名。因此应先保留原始请求体用于验签，再解析业务字段。请使用测试密钥，不要为了调试复制生产凭据。

验签通过后，还应测试重复通知、错误签名、过期时间戳以及事件持久化失败等情况。生成一个签名，只验证了调试链路的一部分，不代表真实付款和完整交付已经验收。

加密资源导航：快速找到查询入口

资源导航集中提供区块浏览器和开发资源入口，适合在排障时查找对应网络的查询工具。浏览器上的交易记录用于核对链上事实，BoltUtil 的订单与投递记录用于核对业务匹配和通知状态，两类信息需要结合使用。

按问题选择起点

• 还没有接入收款：先阅读开发者中心的快速接入指南，明确钱包、建单、收银台和回调之间的关系。
• 已有 WooCommerce 店铺：先检查 USD 店铺与插件环境要求，再按插件指南配置。
• 客户说已付款但订单仍在等待：先查交易和订单信息，不要直接要求客户再付一笔。
• 订单已确认但服务没开通：检查回调投递、验签、事件持久化与业务幂等处理。
• 准备正式启用：完成小额真实付款与异常场景验收，并给用户提供清楚的网络、金额和等待确认提示。

BoltUtil 的价值在于把链上付款接入现有业务流程。先从一个明确场景和一个已配置网络开始，把付款与交付完整跑通，再按实际需求扩展币种与渠道。下方来源区提供官方产品、接入、插件与工具入口，便于逐项操作。