USDT Payment Gateway for WooCommerce

3 分钟，让 WooCommerce 支持 USDT 在线支付

0 资金托管 · 商户直接收款 · 开源透明 · 完全免费

English | 简体中文（默认）

这是一个面向 WordPress 商店的开源 WooCommerce USDT Payment Gateway（WooCommerce USDT 支付网关）。它为 WooCommerce 增加数字货币结账方式，让独立站能够快速接受 USDT、自动确认链上付款并同步订单状态，无需自行开发 Crypto Payment API 或支付回调系统。

本插件是 USDT-Payment-Gateway 的 WooCommerce 接入端。本项目的支付创建、收银台及链上支付通知等底层能力均来自该仓库；本插件负责连接 WordPress / WooCommerce 与底层网关。

[!IMPORTANT] 本仓库是 WooCommerce 接入层，必须配合底层项目 DigitalShieldOfficial/USDT-Payment-Gateway 使用。建议先完成底层网关部署并取得商户号与 API Secret，再安装本插件。

为什么选择它

• 3 分钟接入：上传插件、填写两项凭据、复制回调地址，即可在结账页显示 USDT 支付。
• 0 资金托管：插件不保存钱包私钥、不接触或中转资金；收款由底层网关按商户配置完成。
• 安全可验证：订单请求由 SDK 签名，支付回调通过 HMAC-SHA256 验签，源码完整公开、可自行审计。
• 完全免费：本插件采用 MIT License，不收插件费、订阅费或交易佣金；链上 Gas、服务器和第三方基础设施费用不在此列。
• 自动化订单：付款成功后自动更新 WooCommerce 订单状态，并记录交易哈希、网络、币种和实收金额等对账信息。
• 兼容两种结账页：支持 WooCommerce 经典结账与 Checkout Blocks。

适用场景

• 希望增加 USDT 支付方式的 WooCommerce 独立站
• 需要自动确认付款并更新订单的 WordPress 商店
• 希望使用开源、非托管 Crypto Payment Gateway 的商户
• 销售数字商品、订阅之外的一次性商品或普通实物商品的商城
• 需要通过 Webhook 将链上付款结果同步到 WooCommerce 的项目

本插件只提供 WooCommerce 商品订单支付，不包含充值、代币兑换、法币出入金或钱包托管服务。

3 分钟接入

第 1 分钟：准备底层支付网关

部署并配置 USDT-Payment-Gateway，然后从网关后台取得：

• Merchant No（商户号）
• API Secret（接口密钥）

第 2 分钟：安装插件

下载本仓库并确保 vendor/ 目录存在，然后将整个目录上传到：

/wp-content/plugins/USDTPAY-woocommerce/

在 WordPress 后台进入「插件」，启用 DSPay for WooCommerce。

如果从源码安装且没有 vendor/ 目录，请先在插件目录运行：

composer install --no-dev --optimize-autoloader

第 3 分钟：完成配置

进入：

WooCommerce → 设置 → 付款 → DSPay

1. 勾选 Enable DSPay。
2. 填写 Merchant No 和 API Secret。
3. Exchange Rate 默认填 1；例如填 7 表示订单金额 7 个法币单位对应 1 个 Token。
4. 保存设置。
5. 复制页面显示的 Callback URL，粘贴到底层网关的商户回调配置中。
6. 创建一笔小额测试订单，确认支付完成后订单状态能够自动更新。

完成。顾客现在可以在 WooCommerce 结账页选择 DSPay，并使用 USDT 完成支付。

支付流程

顾客提交 WooCommerce 订单
          ↓
插件调用 SDK 签名并创建支付单
          ↓
顾客进入 DSPay 收银台并使用钱包付款
          ↓
底层网关监听链上交易并发送签名回调
          ↓
插件验签，自动更新 WooCommerce 订单状态

资金不会经过本插件。插件只传递订单信息、验证支付通知并同步订单状态。

功能

• 跳转/内嵌 DSPay 收银台
• SDK 本地签名创建支付订单
• HMAC-SHA256 回调验签
• 自动处理已支付、失败、取消、退款和等待中状态
• 防止同一状态的回调被重复处理
• 虚拟且可下载商品付款后自动完成订单
• 保存链上交易与结算信息到订单备注
• 支付等待页自动轮询支付状态
• 支持顾客取消未支付订单
• WooCommerce 日志记录
• 后台一键复制回调地址
• 兼容经典结账页和 WooCommerce Blocks

环境要求

• WordPress 5.0+
• WooCommerce 5.0+
• PHP 7.4+
• 已部署并可访问的 USDT-Payment-Gateway
• HTTPS 公网域名，以便接收支付回调

配置说明

安全说明

• API Secret 仅保存在 WordPress 的 WooCommerce 网关设置中，不会发送给顾客浏览器。
• 回调必须携带 X-DSPay-Signature，插件验签成功后才处理订单。
• 本插件不保存助记词或钱包私钥，也不代商户保管资金。
• 请为 WordPress 与底层网关启用 HTTPS，使用高强度独立密钥，并及时更新 WordPress、WooCommerce、PHP 和服务器组件。
• “0 资金托管”描述的是本插件及非托管部署方式的资金路径，不代表软件或区块链系统不存在任何风险；正式上线前请完成安全审计和小额测试。

排查问题

支付或回调异常时，进入：

WooCommerce → 状态 → 日志

选择 dspay-webhook 日志，检查签名、订单号、回调状态及错误信息。同时确认：

• Callback URL 可从公网通过 HTTPS 访问；
• WordPress REST API 未被安全插件或防火墙拦截；
• Merchant No 与 API Secret 正确且属于同一商户；
• 修改固定链接后已重新保存一次「设置 → 固定链接」；
• 服务器时间准确。

常见问题

这是 WooCommerce USDT 支付插件吗？

是。本插件会在 WooCommerce 结账页添加 DSPay 支付方式，顾客完成 USDT 支付后，通过签名回调自动更新订单状态。

是否需要把钱包私钥交给 WordPress？

不需要。本插件配置项只有 Merchant No、API Secret 和汇率，不读取或保存钱包私钥。钱包及链上监听配置由底层网关管理。

资金会进入插件开发者的账户吗？

不会。本插件不创建托管账户、不持有资金，也不参与资金结算。实际收款路径取决于商户部署的底层网关和钱包配置。

插件真的免费吗？

插件代码采用 MIT License，不收插件费、订阅费或交易佣金。你仍需自行承担服务器、域名、网络和链上 Gas 等实际成本。

支持哪些 USDT 网络？

本插件不限定具体区块链网络，它负责创建订单和接收支付结果。最终可用网络与币种以你部署的 USDT-Payment-Gateway 配置和版本为准。

支持 WooCommerce Checkout Blocks 吗？

支持。项目同时集成了 WooCommerce 经典结账页与基于区块的 Checkout Blocks。

为什么付款后订单没有自动更新？

优先检查 WooCommerce → 状态 → 日志 → dspay-webhook，并确认 Callback URL 可从公网访问、API Secret 匹配、REST API 未被防火墙拦截。

项目结构

├── dspay-woocommerce.php       # 插件入口、回调接口、支付等待页与 AJAX
├── src/Gateway.php             # WooCommerce 支付网关
├── src/PaymentStatus.php       # 支付状态映射
├── class-block.php             # WooCommerce Blocks 集成
├── checkout.js                 # Blocks 结账页支付方式
├── templates/                  # 支付等待页模板
├── assets/                     # 前后台 JS/CSS
├── languages/                  # 翻译模板
└── composer.json               # PHP SDK 依赖

底层项目

再次说明：本 WooCommerce 插件的底层支付能力来自：

DigitalShieldOfficial/USDT-Payment-Gateway

如果你需要部署支付服务、配置收款钱包、了解链上监听或扩展支付 API，请访问底层仓库。本仓库只负责 WooCommerce 集成。

License

MIT