VibeFox ECPay for WooCommerce — 帮助
系统要求
WordPress:6.0 或更高版本。
WooCommerce:8.0 或更高版本，已安装并启用。
PHP:8.0 或更高版本。
店铺货币：新台币（TWD）。ECPay 仅以 TWD 结算，当店铺或待付款订单使用其他货币时，该付款方式会被隐藏。由于 ECPay 不接受小数，金额会以整数 TWD 发送：订单总额会四舍五入到最接近的整数。建议将 TWD 价格设为 0 位小数以避免四舍五入。
ECPay 账户：正式付款需要您从 ECPay 商户后台（vendor.ecpay.com.tw）获取的 ECPay 商户账户的 MerchantID、HashKey 和 HashIV。测试无需 ECPay 账户。
网站访问：您的网站必须可通过 HTTP/HTTPS 从互联网的 80/443 端口访问，以便 ECPay 能够送达付款通知。维护模式、防火墙或网站前端的基本身份验证会阻止这些通知。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥可用于一个域名。
安装
1. 在 WordPress 中转到 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_ecpay_payment_gateway 文件夹上传到 /wp-content/plugins/。
2. 点击 Activate。WooCommerce 必须处于启用状态。
3. 打开设置：WooCommerce > Settings > Payments > ECPay (綠界) > Manage，或在插件页面上点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 打开 Enable/Disable，选择付款方式，并在首次测试时保持 Test Mode 开启。在沙盒环境中，您可以使用 ECPay 测试卡 4311-9522-2222-2222 付款（任意未来有效期，CVV 222，沙盒页面上的 3-D Secure 验证码）。
6. 正式付款时，输入 MerchantID、HashKey 和 HashIV（参见「配置」），并取消勾选 Test Mode。
配置
所有设置都在同一个页面：WooCommerce > Settings > Payments > ECPay (綠界)。字段上方，当店铺货币不是 TWD 时（此时 ECPay 不会在结账时显示），以及正式模式下缺少 MerchantID、HashKey 或 HashIV 时，页面会显示错误。测试模式开启期间，页面会提示付款会发送到使用公开测试商户 3002607 的 ECPay 沙盒，不会收取任何款项，并提示任何知道公开沙盒密钥的人都可以确认测试订单，因此在接受真实订单之前必须关闭测试模式。
常规
Enable/Disable:Enable ECPay Payment 用于开启或关闭该付款方式。默认值：关闭。
Title:顾客在结账时看到的付款方式名称。默认值：ECPay (綠界)。
Description:结账时在该付款方式下方显示的文字。默认值：Pay securely via ECPay (Credit Card, ATM, CVS, Barcode)。
ECPay 账户
您可以在 ECPay 商户后台（vendor.ecpay.com.tw）的 System development management > System integration settings（系統開發管理 > 系統介接設定）中找到您的 MerchantID、HashKey 和 HashIV。
Test Mode:Enable sandbox/test mode 会使用公开的 ECPay 测试商户 3002607 将付款发送到 ECPay 沙盒（payment-stage.ecpay.com.tw）。不涉及真实款项。下方的凭据仅在测试模式关闭时使用。默认值：开启。
Merchant ID:您的 ECPay Merchant ID（正式环境）。测试模式下会被忽略。
Hash Key:您的 ECPay Hash Key（正式环境）。测试模式下会被忽略。
Hash IV:您的 ECPay Hash IV（正式环境）。测试模式下会被忽略。
粘贴的凭据中如果包含空格和换行符会破坏所有签名，因此保存时会自动移除，页面会提示您这一点。
付款选项
Enabled Payment Methods:提供给顾客的付款方式。启用多种方式时，顾客可在结账时选择。ATM、CVS 和 Barcode 订单在顾客付款前会保持保留状态。必须至少选择一种方式；如果未选择任何方式，则会启用 Credit Card。默认值：Credit Card。
Default Payment Method:预先选中的方式。该方式必须是已启用的方式之一；否则会使用第一个已启用的方式。默认值：Credit Card。
Order Prefix:ECPay 交易编号（MerchantTradeNo）的前缀，最多 5 个字母或数字。其他字符在保存时会被移除。当多家店铺共用一个 ECPay 账户时很有用：为每家店铺设置各自的前缀。默认值：EC。
付款通知
ECPay 会将付款结果发送到您的店铺。本节显示通知 URL，格式类似于 https://your-site/wc-api/ecpay_p_callback/。该 URL 会随每次付款一起发送，因此无需在 ECPay 中进行任何配置，但它必须可通过 80/443 端口从互联网访问，且前端不能有维护模式、防火墙或基本身份验证。
每个通知都会根据付款发起时所在环境（测试或正式）的密钥，通过 CheckMacValue 签名进行校验。没有有效签名的通知会被拒绝，ECPay 会再次发送。没有通知，任何订单都不会被标记为已付款；请在 ECPay 后台核对付款情况。
高级
Enable Logging:Log payment events and API calls 会将订单 ID、交易编号、金额和 ECPay 返回代码写入 WooCommerce > Status > Logs，来源为 wcp_ecpay_payment_gateway。不会记录密钥或顾客数据。默认值：关闭。
Delete Data on Uninstall:Delete all plugin data when uninstalling。将移除本插件的所有设置、日志和订单元数据。默认值：关闭。
结账
顾客选择付款方式（默认为 ECPay (綠界)）。启用多种方式时，顾客还需选择 Credit Card、ATM (Virtual Account)、CVS (Convenience Store) 或 Barcode。测试模式开启期间，该付款方式会显示 TEST MODE — ECPay sandbox, no real money is charged.
下单后，顾客会看到 Redirecting to ECPay for payment. Please wait...，并被转到 ECPay 付款页面，同时提供 Proceed to ECPay 按钮以防跳转未能自动开始。订单总额会以整数 TWD 以及商品名称和数量一起发送。对于台湾和香港的网站语言，ECPay 页面会以繁体中文打开；对于简体中文、韩语或日语网站语言，会以相应的语言打开；其他所有语言则以英语打开。
订单只有在 ECPay 通过已签名的服务器通知确认后才会标记为已付款。如果顾客在确认到达之前返回订单接收页面，页面会显示 We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again:，并带有一个 Pay 按钮。
对于 ATM、CVS 和 Barcode，顾客会先收到付款详情。订单会被置为保留状态，银行代码和虚拟账号、超商付款代码或条码、金额以及 Pay before 日期会显示在感谢页面、My account > Orders 以及保留订单邮件中的 ECPay payment instructions 下。顾客付款后，ECPay 会发送另一通知，订单随即被标记为已付款。
由于 ECPay 会拒绝重复使用的编号，每次访问付款页面都会生成新的 ECPay 交易编号。因此 Pay for order 页面和付款失败后的重试都能正常工作，而且任何这些编号的通知都会与该订单匹配。一个订单最多可以有 30 次付款尝试。
ECPay 按付款方式设定的自有金额限制（例如超商付款）会在 ECPay 页面上核对，而不是在结账时核对。
该付款方式适用于经典结账、结账区块和 Pay for order 页面，并与 WooCommerce High-Performance Order Storage（HPOS）兼容。
本插件仅在 ECPay 页面上支持单次付款，不支持 WooCommerce 退款、保存银行卡、订阅或定期付款（定期定額）、分期付款、Apple Pay、TWQR、WeChat Pay、BNPL、WebATM、电子发票或物流，也没有服务器端状态查询：如果您的网站无法收到通知，请在 ECPay 后台核对付款情况。
订单
订单状态
Pending payment:顾客已被转到 ECPay 但尚未付款，或通知尚未到达。
On hold, waiting for payment:顾客选择了 ATM、CVS 或 Barcode，并已收到付款详情。订单备注会显示银行代码和虚拟账号、付款代码或条码以及截止日期。
Processing:付款已确认（WooCommerce 默认状态；仅含虚拟可下载商品的订单会变为已完成）。订单备注会显示 ECPay TradeNo、付款类型、金额和交易编号。交易 ID 即为 ECPay TradeNo。
On hold after payment:ECPay 报告的金额或货币与订单不符，切换到正式模式后收到了沙盒付款（未收取真实款项），或付款是在订单被取消后到达的。订单备注会说明原因。请与 ECPay 后台核对，并手动完成或退款该订单。
Failed:ECPay 报告最近一次付款尝试失败。备注会显示 ECPay 返回代码和消息。顾客可以重新尝试。
重复的通知会被忽略。已付款、已取消或已退款的订单绝不会因旧通知而重新开启。对已付款订单的第二次付款（例如来自两个浏览器标签页）会以订单备注记录，以便您在 ECPay 后台进行退款。从 ECPay 后台发起的模拟付款只会被记录，绝不会将订单标记为已付款，因为 ECPay 不会为这些付款收取款项。
退款
不支持通过 WooCommerce 退款。请先在 ECPay 后台退款，然后在 WooCommerce 中手动记录退款。
许可证密钥
本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > ECPay (綠界) 页面顶部。将密钥粘贴到 License key 中并点击 Activate。该区块会显示状态，例如许可证的有效截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入另一个密钥，使用 Remove key 从本站点移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。
一个密钥只能用于一个域名。从站点移除密钥不会释放其占用的域名名额。请在您的 vibefox.net 账户中释放该名额。
如果没有有效密钥，ECPay 不会在结账时显示给顾客。如果仍有付款被启动，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍可看到该付款方式，标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置并测试本插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已启动的付款仍会被确认。
许可证到期后，插件仍会继续运行，但更新和支持需要续订。状态会在后台自动重新检查。
故障排查
ECPay 未在结账时出现：请检查许可证是否处于活动状态，Enable/Disable 是否已开启，店铺货币是否为 TWD，以及在正式模式下 Merchant ID、Hash Key 和 Hash IV 是否已设置。设置页面会在每种情况下显示错误。
付款已完成，但订单仍停留在待付款状态：ECPay 通知未能到达您的网站（网站无法访问、防火墙、维护模式、基本身份验证）。ECPay 会重试多次。您也可以在 ECPay 后台核对交易，并手动完成订单。打开 Enable Logging 以查看插件收到的通知。
通知返回 0|CheckMacValue verification failed：Hash Key 或 Hash IV 与您的 ECPay 账户不匹配。请从 ECPay 后台重新复制它们。
通知返回 0|MerchantID mismatch：该通知属于与发起付款时所用的商户不同的 ECPay 商户。
通知返回 0|Order not found：该交易编号并非由本店铺发出，例如多家店铺共用一个 ECPay 账户时。请为每家店铺设置各自的 Order Prefix。
顾客看到 The order total is too small for ECPay.：订单总额在四舍五入后低于 1 TWD，无法使用 ECPay 付款。
订单处于保留状态并带有金额不一致的备注：ECPay 报告的金额与订单总额不同，例如订单在顾客开始付款后被编辑过。请与 ECPay 后台核对，并手动完成或退款该订单。
订单在沙盒付款后处于保留状态：该付款是在测试模式下完成的，但店铺目前处于正式模式。未收取真实款项。请手动核对该订单。
顾客看到 Too many payment attempts for this order：该订单已达到 30 次付款尝试上限。请让顾客重新下单。
许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。如果网站地址发生了变化，点击 Check now 即可为新域名激活密钥。如果无法连接到许可证服务器，插件会按照最后已知的状态继续运行。
卸载
停用本插件会保留所有数据。要移除本插件，请在 Plugins 页面将其停用并删除。本插件的许可证密钥和许可证状态始终会被移除。设置、存储在订单中的 ECPay 数据以及日志只有在开启 Delete Data on Uninstall 时才会被移除。否则，它们会保留以便日后重新安装。现有订单会保留其付款备注和交易 ID。
ECPay 是其各自所有者的商标。本插件与 ECPay 无关联，也未获得 ECPay 的认可。