几年前，我曾经分享过一篇 WooCommerce 对接易支付的教程。当时使用的是较早的收费插件，支付方式不够完整，对 PHP 8 和新版 WooCommerce 区块结账的兼容性也有限。
这一次我重新整理并开发了一套 EPay for WooCommerce 插件，已经在 GitHub 免费开源。新版插件为每一种支付方式提供独立的 WooCommerce 网关，支持经典结账页和新版 Checkout Block，也加入了支付签名、金额、商户号、通道和重复回调验证。
插件费用：插件源码免费开源，采用 GPL-3.0 许可证。易支付平台、服务器和具体支付通道可能产生各自的服务费用。
当前教程版本：EPay for WooCommerce 2.1.0
一、新版插件有哪些变化？
旧版教程主要解决“让 WooCommerce 能跳转到易支付”的问题。现在的开源版本不只是简单修改旧插件，而是重新整理了插件结构和关键逻辑。
- 免费开源：源码托管在 GitHub，用户可以自行下载、检查、修改和提交问题。
- 10 个独立支付网关：客户在 WooCommerce 结账页直接选择具体支付方式，不使用空 type 的聚合收银台。
- 支持 PHP 7.4 及以上版本：已经分别通过 PHP 7.4 和 PHP 8.4 语法检查。
- 支持 HPOS：订单读写使用 WooCommerce API，并声明兼容高性能订单存储。
- 支持 Checkout Block：新版 WooCommerce 区块结账页可以识别并显示已经启用的 EPay 支付方式。
- 独立支付图标：银联、Revolut、PayPal、AlipayHK、USDT、LINE Pay、PayNow 和银行卡等通道使用独立图标。
- 回调验证更完整：验证签名、商户 ID、支付状态、订单支付方式、API type 和完整订单金额，并安全处理重复通知。
二、支持哪些支付方式？
目前插件包含以下 10 个独立网关：
| 结账页名称 | API type | 使用条件 |
|---|---|---|
| 微信支付 | wxpay | 易支付服务端支持微信通道 |
| 支付宝 | alipay | 易支付服务端支持支付宝通道 |
| 银联支付 | bank | 服务端将银联映射为 bank |
| Revolut | revolut | 服务端支持 Revolut 插件 |
| PayPal | paypal | 服务端支持 PayPal 插件 |
| AlipayHK | alipayhk | 服务端支持香港支付宝通道 |
| USDT | usdt | 服务端支持 USDT 通道及对应网络 |
| LINE Pay | linepay | 服务端支持 LINE Pay |
| PayNow | paynow | 服务端支持新加坡 PayNow |
| 信用卡 / 借记卡 | card | 服务端支持银行卡收款通道 |
可以陆续增加更多支付
你不需要把 10 种方式全部打开。只启用服务端真实可用、并且已经测试成功的通道，能够减少客户误选和支付失败。
三、安装前需要准备什么？
开始前建议准备以下内容：
- 一套可以正常访问的 WordPress 网站。
- 已经安装并启用 WooCommerce。
- 一个可以正常使用的易支付商户账户。
- 易支付站点根地址、商户 ID 和商户密钥。
- 至少一个已经在易支付服务端测试过的支付通道。
- 网站启用 HTTPS，并允许易支付服务器访问 WooCommerce 回调地址。
- 一个低价测试商品，建议使用你能承担风险的最小测试金额。
四、从 GitHub 下载并安装插件
方法一：从 GitHub 页面下载
- 打开项目主页：wxcydzcc/epay。
- 点击绿色的 Code 按钮。
- 点击 Download ZIP。
- 解压后将目录名称从 epay-main 改成 epay。
- 重新压缩为 epay.zip。
也可以直接使用下面的源码下载地址：
方法二：在 WordPress 后台上传
- 登录 WordPress 后台。
- 进入“插件 → 安装新插件”。
- 点击“上传插件”。
- 选择刚才准备好的 epay.zip。
- 点击“立即安装”，安装完成后点击“启用插件”。
如果通过 FTP 或服务器面板安装，也可以把完整的 epay 目录上传到：
/wp-content/plugins/epay/
五、填写易支付全局参数
启用插件后，进入：
WooCommerce → 易支付设置
这里的参数由所有支付方式共同使用。
1. 支付网关地址
填写易支付站点的根地址，例如：
https://pay.example.com
不需要手动添加 /submit.php，插件会自动拼接。建议不要在末尾添加多余路径或参数。
2. 商户 ID
填写易支付商户后台分配的 PID。不要填写支付平台订单号、登录账号或插件编号。
3. 商户密钥
填写商户后台对应的 Key。这个密钥用于生成和校验 MD5 签名，不能公开。以后修改其他设置时，如果不需要更换密钥，可以把密钥输入框留空，插件会保留原值。
4. 自定义支付后返回地址
通常建议留空，让 WooCommerce 自动返回订单完成页。只有明确知道业务需求时，才填写自定义 HTTPS 地址。
六、启用需要的支付方式
填写全局参数后，还需要单独启用支付方式。进入：
WooCommerce → 设置 → 付款
你会看到微信支付、支付宝、银联支付、Revolut、PayPal、AlipayHK、USDT、LINE Pay、PayNow 和信用卡 / 借记卡。
- 先选择一个服务端已经支持的支付通道。
- 打开“启用”开关。
- 进入管理页面，确认结账标题和说明。
- 保存设置。
- 依次启用其他已经测试可用的通道。
如果你的易支付服务端没有对应的 type，不要在 WooCommerce 中启用该方式。例如服务端没有 paynow 通道，启用 PayNow 后客户虽然可以看到选项，但提交订单时可能无法进入正确的支付页面。
七、新版 Checkout Block 说明
WooCommerce 新网站通常默认使用 Checkout Block。旧版支付插件经常出现后台已经启用，但结账页提示“无可用的付款方式”的问题。
EPay for WooCommerce 2.1.0 已加入 Checkout Block 的 PHP 和 JavaScript 注册层。已经启用的 EPay 网关会同时显示在：
- 经典 shortcode 结账页：[woocommerce_checkout]
- WooCommerce 新版 Checkout Block
区块结账会沿用传统网关中的启用状态、标题、说明、图标和 process_payment 跳转流程，不需要重复填写商户参数。
八、创建测试商品并完成付款
支付插件安装完成后，不要直接上线推广，先做一笔完整的小额测试。
- 创建一个低价测试商品。
- 使用无痕窗口或退出管理员账号访问网站。
- 把商品加入购物车。
- 进入结账页，填写测试所需的账单信息。
- 选择刚刚启用的 EPay 支付方式。
- 点击“下单”或“Place order”。
- 确认浏览器跳转到正确的易支付地址和通道。
- 完成付款，等待返回 WooCommerce。
插件提交给易支付的主要参数包括商户 ID、支付 type、WooCommerce 订单号、异步通知地址、返回地址、商品名称、订单金额、签名和签名类型。
九、检查异步回调是否成功
客户在支付页面看到“支付成功”并不等于 WooCommerce 已经收到回调。完整测试必须回到 WordPress 后台检查订单状态。
进入：
WooCommerce → 订单 → 打开刚才的测试订单
正常情况下可以看到：
- 订单从“待付款”变成“处理中”或“已完成”。
- 订单备注中出现易支付付款成功及平台交易号。
- 付款方式与本次选择的 EPay 通道一致。
- 易支付服务端收到纯文本 success，不再重复通知。
插件接收回调时会检查：
- MD5 签名是否正确；
- 回调商户 ID 是否与后台配置一致；
- trade_status 是否为 TRADE_SUCCESS；
- WooCommerce 订单是否存在；
- 订单支付方式与回调 type 是否一致；
- 回调金额与订单完整金额是否一致；
- 订单是否已经支付，避免重复完成订单。
十、常见问题排查
问题 1：结账页提示“无可用的付款方式”
- 确认插件已启用。
- 确认至少一个 EPay 支付方式已经在“WooCommerce → 设置 → 付款”中启用。
- 确认安装的是 2.1.0 或更新版本。
- 清除 WordPress、对象缓存、页面缓存和 CDN 缓存。
- 确认测试订单确实需要付款，免费订单不会显示普通付款方式。
- 临时停用可能过滤支付方式的多币种、地区限制或结账优化插件进行排查。
问题 2：点击下单后提示易支付配置不完整
检查支付网关地址、商户 ID 和商户密钥是否都已保存。网关地址填写根域名，不要重复添加 submit.php。
问题 3：能够下单，但没有跳转到付款页面
- 确认易支付地址使用 http:// 或 https:// 开头。
- 直接访问易支付站点，确认服务端没有故障。
- 确认服务端支持本次选择的 API type。
- 检查安全插件或防火墙是否阻止外部跳转。
问题 4：付款成功，但 WooCommerce 订单仍然待付款
- 在“WooCommerce → 易支付设置”查看插件显示的异步通知地址。
- 确认该地址可以从公网访问，不能被登录验证、维护模式或 IP 白名单拦截。
- 检查 Cloudflare、宝塔防火墙、WordPress 安全插件和服务器 WAF。
- 确认易支付后台的商户 ID 和密钥与 WordPress 配置完全一致。
- 检查订单金额和支付币种，避免通道换算后回调金额不一致。
- 进入“WooCommerce → 状态 → 日志”，查找来源为 epay-callback 的警告。
问题 5：部分支付方式跳转错误
通常是易支付服务端的插件调用值与本项目约定不一致。WooCommerce 端使用的是固定值，例如银联为 bank、银行卡为 card。如果服务端使用其他调用值，需要先统一两端协议，不要只修改显示名称。
问题 6：图标没有更新
清除浏览器、WordPress 和 CDN 缓存；检查服务器是否允许正确返回 SVG 文件。如果安全策略不允许 SVG，可以把对应图标转换成 PNG，并同步修改网关类中的图标文件名。
十一、安全与使用建议
- 不要在文章、视频、截图或 GitHub Issue 中公开商户密钥。
- WordPress、WooCommerce 和插件都应及时更新。
- 网站和易支付服务端应使用有效 HTTPS 证书。
- 不要通过前端返回页面直接把订单标记为已支付，应以服务器异步通知为准。
- 先测试单一通道，再逐个增加其他通道。
- 正式上线前分别测试成功付款、取消付款、金额不一致和重复通知。
- WooCommerce 商店币种必须与实际支付通道的结算逻辑相符。插件本身不会自动进行汇率转换。
- 定期核对 WooCommerce 订单、易支付订单和最终到账记录。
十二、常见问题 FAQ
这个 WooCommerce 易支付插件收费吗？
插件源码已经在 GitHub 免费开源。易支付服务器、支付通道、收单机构和银行卡处理服务可能有自己的费用。
支持 PHP 8 吗？
支持。项目代码已经通过 PHP 7.4 和 PHP 8.4 语法检查。实际运行仍建议搭配受支持版本的 WordPress、WooCommerce 和 PHP 扩展。
支持新版 WooCommerce Checkout Block 吗？
2.1.0 及以上版本支持 Checkout Block，同时保留经典 shortcode 结账。
为什么我启用了 PayPal 或 USDT，但仍然无法支付？
WooCommerce 插件只负责传递对应的 API type。易支付服务端必须已经安装、启用并正确配置相应的 PayPal 或 USDT 支付插件。
可以跳转到不指定通道的聚合收银台吗？
当前开源版有意采用独立支付方式，不提供空 type 的聚合收银台。这样客户选择的方式、订单记录和回调通道可以保持一致。
支付成功后订单没有自动完成怎么办？
先检查异步通知地址是否能被公网访问，再检查防火墙、缓存、商户密钥、订单金额和 epay-callback 日志。只有浏览器跳回网站，不代表异步回调已经成功。
总结
新版 EPay for WooCommerce 把旧教程中依赖收费插件的流程改成了可公开检查、可持续维护的 GitHub 开源方案。它适合希望把 WooCommerce 与自有易支付服务端连接起来，并在结账页提供多个独立支付通道的用户。
如果这篇教程对你有帮助，欢迎访问 GitHub 项目点一个 Star，也欢迎订阅我的 YouTube 频道。后续我还会继续更新易支付、WooCommerce、跨境收款、银行卡支付和 USDT 支付方面的实际演示。
查看 GitHub 开源项目 | 订阅八道科技 YouTube 频道
