VibeFox ECPay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
货币：新台币（TWD）。ECPay 仅收取 TWD，因此只有顾客的购物车为 TWD 时才会显示该付款方式。如果您的商店没有 TWD，请在 International > Localization > Currencies 中添加。由于 ECPay 不接受小数，金额以整数 TWD 发送：购物车总额会四舍五入到最接近的元。为避免舍入，请为 TWD 价格设置 0 位小数。
ECPay 账户：正式付款需要您 ECPay 商户账户的 MerchantID、HashKey 和 HashIV，可在 ECPay 商户后台（vendor.ecpay.com.tw）获取。测试时不需要 ECPay 账户。
网站访问：您的商店必须可通过互联网以 HTTP/HTTPS 的 80/443 端口访问，以便 ECPay 发送付款通知。防火墙或网站前的基本身份验证会阻止这些通知。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥适用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox ECPay Payment Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（见许可证密钥）。
4. 开启 Enable/Disable，选择付款方式，并在首次测试时保持 Test Mode 开启。点击 Save。
5. 正式付款时，填写 Merchant ID、Hash Key 和 Hash IV（见配置），关闭 Test Mode，然后点击 Save。
安装时，模块会创建两个订单状态：Awaiting ECPay payment 和 ECPay payment on hold。PrestaShop 会为所有货币、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中限制它们；模块必须保持允许 TWD。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果您的商店没有 TWD 货币，页面会显示错误（此时结账时不显示 ECPay）；如果默认货币不是 TWD，则显示警告（此时仅向以 TWD 付款的顾客显示 ECPay）。如果正式模式缺少 MerchantID、HashKey 和 HashIV，页面会显示错误。测试模式开启时，页面会警告：付款将发送至 ECPay 沙盒并使用公开测试商户 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：将付款发送至 ECPay 沙盒（payment-stage.ecpay.com.tw），使用公开的 ECPay 测试商户 3002607。不涉及真实资金。下方的凭据仅在测试模式关闭时使用。默认：开启。开启期间，顾客会在付款方式下方看到 TEST MODE — ECPay sandbox, no real money is charged.
Merchant ID：您的 ECPay Merchant ID（正式环境）。测试模式下忽略。
Hash Key：您的 ECPay Hash Key（正式环境）。测试模式下忽略。
Hash IV：您的 ECPay Hash IV（正式环境）。测试模式下忽略。
粘贴的凭据中如果含有空格或换行，会导致每个签名都失败，因此保存时会将其删除，并且页面会提示您。已保存的 Hash Key 和 Hash IV 不会再次显示：字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved secrets：勾选 Hash Key 或 Hash IV 并点击 Save 即可将其删除。空字段会保留已保存的值。
付款选项
Enabled Payment Methods：提供给顾客的付款方式。如果有多种，顾客在结账时选择。ATM、超商代码和条码订单会一直停留在 Awaiting ECPay payment，直到顾客付款。至少需要选择一种付款方式；如果一种都未选择，则会启用 Credit Card，并且页面会提示您。默认：Credit Card。
Default Payment Method：预先选中的付款方式。它必须是已启用的付款方式之一；否则使用第一个已启用的付款方式。默认：Credit Card。
Order Prefix：ECPay 交易编号（MerchantTradeNo）的前缀，最多 5 个字母或数字。保存时其他字符会被删除，并显示提示。当多个商店共用一个 ECPay 账户时很有用：请为每个商店设置各自的前缀。默认：EC。
付款通知
ECPay 会将付款结果发送到您的商店。本部分显示 Notification URL。使用友好网址时，它类似于 https://your-shop/module/wcp_ecpay_payment_gateway/notify，可能带有语言代码，例如 /en/。该 URL 会随每笔付款一起发送，因此无需在 ECPay 中进行任何配置，但它必须可通过互联网以 80/443 端口访问，并且其前面不能有防火墙或基本身份验证。商店的维护模式和国家限制不会阻止它。
每个通知都会使用付款发起时所在环境（测试或正式）的密钥进行 CheckMacValue 签名验证，并验证该笔付款的 MerchantID。没有有效签名的通知会被拒绝，ECPay 会重新发送。没有通知就不会生成订单；请在 ECPay 后台核对付款。
高级
Enable Logging：将订单编号、交易编号、金额和 ECPay 返回代码写入模块文件夹中的 logs/ecpay_p_debug.log.php。该文件无法通过网页打开。不会记录密钥或顾客数据。即使此开关关闭，错误也始终会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete Data on Uninstall：开启时，卸载模块会删除其设置和日志。ECPay 付款记录和订单状态始终会保留，因此现有订单在重新安装后仍可正常使用。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 ECPay（綠界））。启用多种方式时，顾客还会在 Payment Method 下选择 Credit Card、ATM (Virtual Account)、CVS (Convenience Store) 或 Barcode。
确认后，顾客会看到 Redirecting to ECPay for payment. Please wait...，并被转到 ECPay 付款页面；如果跳转没有开始，还有一个 Proceed to ECPay 按钮。购物车总额会以整数 TWD 发送，并附带商品名称和数量。ECPay 页面会根据顾客商店的语言打开：台湾和香港语言显示为繁体中文，这些语言对应的简体中文、韩语或日语显示为相应语言，其他所有语言则显示为英语。此时尚未生成订单。
只有在 ECPay 通过签名的服务器通知确认后，才会生成订单。当顾客点击 ECPay 页面上返回商店的链接，且订单已存在时，会打开标准的订单确认页面。对于已付款的订单，它会显示 Your ECPay payment has been received.；对于处于保留状态的订单，显示 Your ECPay payment was received and is being reviewed by the store.；对于等待付款的 ATM、超商代码或条码订单，则显示付款说明。如果通知尚未到达，Payment confirmation 页面会显示 We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment.，并带有 Check again 和 Back to checkout 按钮。如果 ECPay 报告付款失败，顾客会返回结账页面，并显示 The payment was not completed. You can try again or choose another payment method. 购物车会保留。
对于 ATM、超商代码和条码，顾客会先收到付款信息。订单会以 Awaiting ECPay payment 状态生成，银行代码和虚拟账号、超商付款代码或条码、金额以及 Pay before 日期会显示在订单确认页面和顾客的订单详情中的 ECPay payment instructions 下。顾客付款后，ECPay 会发送另一个通知，订单随即被标记为已付款。付款说明不会添加到 PrestaShop 邮件中。
每次尝试都会生成新的 ECPay 交易编号，因为 ECPay 会拒绝重复使用的编号。因此，付款失败后的重试可以正常工作；如果顾客在浏览器中返回到跳转页面，则会开始新的尝试。一个购物车最多可以有 30 次付款尝试。购物车生成订单后，就无法再通过结账页面付款；处于等待状态的 ATM 或超商订单，将使用已发出的付款信息支付。
如果无法开始付款，顾客会停留在结账页面并看到简短提示，例如当四舍五入后的总额低于 1 TWD 时显示 The order total is too small for ECPay.。ECPay 对各付款方式的金额限制会在 ECPay 页面上检查，而不是在结账页面检查。
本模块仅在 ECPay 页面上接受单次付款。它不支持 PrestaShop 退款、保存银行卡、订阅或定期定额付款（定期定額）、分期付款、Apple Pay、TWQR、WeChat Pay、BNPL、WebATM、电子发票或物流，也不支持服务器端状态查询：如果您的商店无法接收通知，请在 ECPay 后台核对付款。
订单
订单状态
No order yet：顾客已被转到 ECPay，但尚未付款，或通知尚未到达。此时只存在购物车。
Awaiting ECPay payment：顾客选择了 ATM、超商代码或条码，并已收到付款信息。备注显示银行代码和虚拟账号、付款代码或条码以及截止日期。
Payment accepted：付款已确认。付款会以 ECPay TradeNo 作为交易 ID 记录，备注会显示 TradeNo、付款类型、金额和交易编号（沙盒付款会带有测试模式标记）。
ECPay payment on hold：ECPay 报告的金额或货币与购物车不同（例如，付款开始后购物车在另一个标签页中被修改），沙盒付款在您切换到正式模式后到达（未收取真实资金），或付款在订单被取消后到达（此时付款仍会被记录）。备注会说明原因。请与 ECPay 后台核对，然后处理订单或在那里退款。
Payment error：ECPay 报告等待中订单的最近一次 ATM、超商代码或条码付款失败。备注会显示 ECPay 返回代码和信息。
重复的通知会被忽略。已付款、已退款或已取消的订单绝不会因迟到的失败通知而重新开启。对于已付款订单的第二次付款（例如来自两个浏览器标签页），会作为备注记录一次，以便您在 ECPay 后台退款。从 ECPay 后台发起的模拟付款仅作记录，绝不会将订单标记为已付款，因为 ECPay 不会为这些付款收取任何资金。
ECPay 付款区块
订单页面会显示一个 ECPay payment 区块，列出该订单的每次付款尝试：MerchantTradeNo（沙盒尝试带有 Test mode 标记）、付款方式、以 TWD 计的金额、状态、ECPay TradeNo、付款类型和日期，以及 ECPay 返回代码。其下方是订单的 ECPay notes。对于处于 ECPay payment on hold 状态的订单，该区块会提醒您与 ECPay 后台进行核对。
退款
无法从 PrestaShop 退款。请在 ECPay 后台退款，然后在 PrestaShop 中手动更新订单。订单页面上的标准 PrestaShop 退款按钮不会通过 ECPay 退还款项。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ECPay Payment Gateway 是 Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key 并点击 Activate。之后，该区块会以隐藏方式显示密钥、状态（例如许可证有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方有一行 Product: presta-payment-ecpay 和链接 Manage licenses and domains in your account，点击后将打开您的 vibefox.net 账户。只有拥有本模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。修改商店地址后，或在您的账户中释放一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后已知的状态运行。
一个密钥适用于一个域名：即主商店的域名，多商店设置中同样适用。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 ECPay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 的 Alerts 选项卡中会出现提醒。现有订单不受影响：已发起的付款仍会被确认。
许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台时，系统会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需配置 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 ECPay：请检查许可证是否有效、Enable/Disable 是否开启、顾客的购物车是否为 TWD，并且在正式模式下 Merchant ID、Hash Key 和 Hash IV 是否已设置。在上述每种情况下，设置页面都会显示提示。在 Payment > Preferences 中，请检查模块是否允许 TWD、顾客所在国家和顾客所在客户组。
付款已完成，但未生成订单：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。
通知返回 0|Retry：购物车在同一时刻正被另一个通知处理，或者无法生成订单（例如模块已禁用）。ECPay 会重新发送通知。开启 Enable Logging 可查看原因。
通知网址显示 0|Method not allowed in the browser：这是正常现象。该网址只接受来自 ECPay 的请求。
顾客看到 「The order total is too small for ECPay.」：购物车总额四舍五入后低于 1 TWD，无法通过 ECPay 付款。
顾客看到 「Too many payment attempts for this order」：购物车已达到 30 次付款尝试。请让顾客重新开始一个新的购物车。
订单处于 ECPay payment on hold：请阅读 ECPay payment 区块中的备注（见订单状态），与 ECPay 后台核对，然后处理订单或在那里退款。
开发者：钩子 actionEcpayPRequestParams 允许其他模块修改发送给 ECPay 的参数；商户、交易编号和金额无法通过它修改。
卸载
进入 Modules > Module Manager，打开 VibeFox ECPay Payment Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，设置和日志会被删除。如果已关闭，所有设置都会保留，供以后重新安装时使用。ECPay 付款记录以及 Awaiting ECPay payment 和 ECPay payment on hold 订单状态始终会保留，因此重新安装后，旧付款的迟到通知仍会被核对。现有订单会保留其付款备注和交易 ID。
ECPay 是其各自所有者的商标。本模块与 ECPay 无关联，也未获得 ECPay 的认可。