VibeFox ECPay for OpenCart — 帮助

系统要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

PHP：8.0 或更高版本。

货币：新台币（TWD）。ECPay 仅以新台币收款，因此仅当顾客以新台币结账时才会显示该付款方式。如果您的店铺没有新台币，请在 System > Localisation > Currencies 中添加代码为 TWD 的新台币。由于 ECPay 不接受小数，金额以整数新台币发送：订单总额会四舍五入到最接近的元。为避免舍入误差，请将新台币的小数位数设为 0。

ECPay 账户：正式收款需要您的 ECPay 商户账户中的 MerchantID、HashKey 和 HashIV，可在 ECPay 商户后台（vendor.ecpay.com.tw）获取。测试时无需 ECPay 账户。

站点访问：您的店铺必须可以通过互联网以 HTTP/HTTPS 访问 80/443 端口，以便 ECPay 能够发送付款通知。站点前面的防火墙或基本身份验证会阻止这些通知。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含适用于两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_ecpay_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_ecpay_payment_gateway.ocmod.zip。只安装适合您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_ecpay_payment_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将此安装包中 upload 文件夹的内容复制到店铺的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox ECPay Payment Gateway，然后点击 Install（绿色 + 按钮）。您的管理员用户需要有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。

4. 开启 Enable/Disable，选择付款方式，并在首次测试时保持 Test Mode 开启。点击 Save。

5. 正式收款时，填写 Merchant ID、Hash Key 和 Hash IV（参见配置），关闭 Test Mode，然后点击 Save。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_ecpay_payment_gateway.ocmod.zip。不要重命名该文件：OpenCart 4 从文件名读取扩展代码，重命名后的安装包无法工作。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox ECPay Payment Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥和设置。设置页面及其字段在两个版本中相同。只有通知 URL 不同（参见付款通知）。

新安装默认关闭付款方式，并开启测试模式。每次付款都会发送通知 URL，因此无需在 ECPay 中进行任何配置。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox ECPay Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果店铺的默认货币不是 TWD 且没有已启用的 TWD 货币，页面会显示错误（此时结账时不会显示 ECPay）；如果 TWD 只是第二货币，页面会显示警告（此时仅向以新台币付款的顾客显示 ECPay）。如果正式模式缺少 MerchantID、HashKey 或 HashIV，页面会显示错误。测试模式开启时，页面会提示：付款将发送到 ECPay 沙盒，使用公开测试商户 3002607，不会收取任何费用，并且任何知道公开沙盒密钥的人都可能确认测试订单，因此在接受真实订单之前必须关闭测试模式。如果没有修改扩展的权限，页面会显示设置但无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数，Total 必须为 0 或更大的数字；否则不会保存任何内容。其他更正会在设置上方以消息形式保存（参见下方字段）。

ECPay (綠界)

Enable/Disable：Enable ECPay Payment 用于开启或关闭该付款方式。默认：关闭。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：ECPay (綠界)。必填。

Description：在 Confirm Order 步骤向顾客显示的文字。默认：Pay securely via ECPay (Credit Card, ATM, CVS, Barcode)。

Sort Order：ECPay 在结账时的付款方式中的位置。留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 ECPay。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的、以店铺默认货币计算的结账总额，达到后才会提供 ECPay。留空则对任何总额都提供 ECPay。

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。不会产生真实费用。下方的凭据仅在测试模式关闭时使用。默认：开启。开启时，顾客在 Confirm Order 步骤会看到 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 the saved value on save，然后点击 Save。

付款选项

Enabled Payment Methods：提供给顾客的付款方式。如果有多种，顾客在 Confirm Order 步骤中进行选择。ATM、CVS 和 Barcode 订单会一直处于等待状态，直到顾客付款。至少必须选择一种方式；如果一种都没有选，则会自动启用 Credit Card，并且页面会提示您。默认：Credit Card。

Default Payment Method：预先选中的付款方式。它必须是已启用的方式之一；否则使用第一个已启用的方式。默认：Credit Card。

Order Prefix：ECPay 交易编号（MerchantTradeNo）的前缀，最多 5 个字母或数字。保存时会删除其他字符，并显示消息。当多个店铺共用一个 ECPay 账户时很有用：为每个店铺设置各自的前缀。默认：EC。

付款通知

ECPay 会将付款结果以及 ATM、CVS 和条形码的详细信息发送到您的店铺。本部分显示 Notification URL。在 OpenCart 3 中其格式类似：https://your-store/index.php?route=extension/payment/wcp_ecpay_payment_gateway/notify，在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_ecpay_payment_gateway/payment/wcp_ecpay_payment_gateway.notify。该 URL 会随每次付款发送，因此无需在 ECPay 中进行任何配置，但它必须可以通过互联网在 80/443 端口访问，前面不能有防火墙或基本身份验证。维护模式不会阻止它。

每个通知都会通过 CheckMacValue 签名进行验证，使用付款发起时所在环境（测试或正式）的密钥，并核对该付款的 MerchantID。没有有效签名的通知会被拒绝，ECPay 会重新发送。如果没有收到通知，订单不会获得任何状态；请在 ECPay 商户后台核实该付款。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（即缺失订单）。只有收到经过签名的 ECPay 通知后，订单才会获得状态。失败或中途放弃的银行卡付款会使订单保持无状态，顾客可以重新付款。下方每个字段都列出了您的 OpenCart 订单状态。

Payment accepted：ECPay 以预期金额确认付款时设置的状态。默认：Processing。

Awaiting ECPay payment：顾客收到 ATM 虚拟账户、CVS 付款代码或条形码、并稍后在 ATM 或门店付款时设置的状态。默认：Pending。

ECPay payment on hold：ECPay 报告的金额或币种不同、正式模式下收到沙盒付款，或付款在订单状态被更改（例如已取消）之后到达时设置的状态。订单备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态并在此处选择。

Payment error：等待中的订单最近一次 ATM、CVS 或条形码付款失败时设置的状态。默认：Failed。

高级

Enable Logging：将订单编号、交易编号、金额和 ECPay 返回代码写入 OpenCart 日志文件夹（storage/logs）中的 ecpay_p_debug.log.php。该文件无法通过网页打开，当大小达到 5 MB 时会移动到 ecpay_p_debug.old.log.php。不记录任何密钥或顾客数据。即使此开关关闭，错误也始终会被记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete Data on Uninstall：开启后，卸载扩展时会删除其设置和日志。ECPay 付款记录始终保留，因此重新安装后现有订单仍可正常使用。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。Hash Key 和 Hash IV 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 Hash Key 和 Hash IV 会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 ECPay (綠界)）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the ECPay payment page to complete the payment. 如果启用了多种方式，顾客还会在 Payment Method 下选择 Credit Card、ATM (Virtual Account)、CVS (Convenience Store) 或 Barcode。OpenCart 在此步骤创建订单，仍然不带状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击页面底部的 Confirm Order；ECPay 方式的选择显示在该按钮上方。

顾客点击 Confirm Order 后，页面会显示 Redirecting to ECPay for payment. Please wait...，并将顾客带到 ECPay 付款页面。订单总额以整数新台币发送，并附带商品名称和数量。根据顾客店铺的语言，ECPay 页面会以繁体中文（适用于台湾和香港语言）、简体中文、韩文或日文（适用于相应语言）显示，其他语言则使用英文。

只有在 ECPay 通过经过签名的服务器通知确认付款后，订单才会被标记为已付款。随后订单会按照 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。顾客点击 ECPay 页面上的返回店铺链接时，如果订单已有状态，则会打开 OpenCart 订单成功页面。已付款订单显示 Your ECPay payment has been received.，待审核订单显示 Your ECPay payment was received and is being reviewed by the store.，等待中的 ATM、CVS 或 Barcode 订单则显示付款说明。如果通知尚未到达，Payment confirmation 页面会显示 We have not received a payment confirmation from ECPay for this order yet. Your order will be confirmed 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. 在 OpenCart 4 中，这些消息显示在结账页面上方。购物车将被保留。

对于 ATM、CVS 和 Barcode，顾客会先收到付款详情。订单获得 Awaiting ECPay payment 状态，银行代码和虚拟账户、便利店付款代码或条形码、金额以及 Pay before 截止日期，会在订单成功页面的 ECPay payment instructions 下显示；对于已登录的顾客，也会显示在其客户账户的订单信息中。顾客付款后，ECPay 会发送另一条通知，订单随即被标记为已付款。付款说明不会添加到 OpenCart 邮件中。

每次尝试都会生成一个新的 ECPay 交易编号，因为 ECPay 会拒绝重复使用的编号。因此付款失败后的重试可以正常进行；如果顾客在浏览器中返回并再次点击 Confirm Order，则会开始新的尝试。一个购物车最多可以有 30 次付款尝试。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 为结账保留一个订单并对其进行更新，新的尝试会获得新的 ECPay 交易编号；如果同一购物车的另一订单已付款或正在等待 ATM 或 CVS 付款，顾客会被带到成功页面，并且不会开始新的付款。

OpenCart 4 会在成功页面显示之前一直把订单保留在结账中。如果该订单在未付款的情况下已被关闭（例如您取消了它，或 ATM 或 CVS 付款失败），顾客会被带回结账页面，并显示 Your previous order was cancelled or its payment failed. Please confirm the order again.，随后的 Confirm Order 会为该购物车支付一个新订单。如果订单已付款（或正在等待 ATM 或超商付款），且此后购物车发生了变化（包括数量变化），则显示 Your previous order is already paid (or awaits its ATM / convenience store payment). Please confirm the order again: the cart will be paid with a new order.。已付款的订单绝不会对另一购物车显示为已付款。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如当四舍五入后总额低于 1 TWD 时显示 The order total is too small for ECPay. ECPay 对各付款方式的金额限制会在 ECPay 页面上检查，而不是在结账时检查。

即使您关闭了付款方式，对已开始付款的通知仍会被接受，并且顾客仍可看到已下订单的付款说明。

该扩展仅支持在 ECPay 页面上进行的一次性付款。它不支持从 OpenCart 退款、保存银行卡、订阅或定期定额付款（定期定額）、分期付款、Apple Pay、电子发票或物流，也不支持服务器端状态查询：如果您的店铺无法接收通知，请在 ECPay 商户后台核实付款。

订单

订单状态

No status (missing order)：顾客已被转到 ECPay 但尚未付款，银行卡付款失败，或通知尚未到达。在 Sales > Orders 中，只有将 Order Status 筛选条件设为 Missing Orders，才会显示此类订单。

Awaiting ECPay payment (default Pending)：顾客选择了 ATM、CVS 或 Barcode，并收到了付款详情。备注中会显示银行代码和虚拟账户、付款代码或条形码以及截止期限。

Payment accepted (default Processing)：付款已确认。备注中会显示 ECPay TradeNo、付款类型、金额和交易编号（对沙盒付款会标注测试模式标记）。

ECPay payment on hold (default Pending)：ECPay 报告的金额或币种与订单不同（例如付款开始后，购物车在另一标签页中被修改），沙盒付款在您切换到正式模式后到达（未收取真实费用），或付款在您更改订单状态（例如取消）之后到达。备注会说明情况。请与 ECPay 商户后台核对，然后处理订单或在那里退款。

Payment error (default Failed)：ECPay 报告等待中订单的最近一次 ATM、CVS 或条形码付款失败。备注中会显示 ECPay 返回代码和消息。

重复的通知会被忽略。已付款的订单不会因为迟到的失败通知而重新打开。对已付款订单的第二次付款（例如来自两个浏览器标签页）只会作为备注记录一次，以便您在 ECPay 商户后台退款。从 ECPay 商户后台发起的模拟付款仅作备注，绝不会将订单标记为已付款，因为 ECPay 不会为这些付款收取费用。

备注是订单 History 中顾客看不到的记录。

VibeFox ECPay Payment Gateway 标签页

在 Sales > Orders 中打开一个通过 ECPay 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox ECPay Payment Gateway 标签页会列出该订单的每一次付款尝试：MerchantTradeNo（沙盒尝试会带有 Test mode 标签）、付款方式、以新台币计的金额、状态、ECPay TradeNo、付款类型和日期、ECPay 返回代码以及开始日期。下方是该订单的 ECPay notes。对于处于等待状态的订单，该标签页会提醒您与 ECPay 商户后台核对。该标签页为只读，仅向有权访问该扩展的用户显示。

退款

无法从 OpenCart 退款。请在 ECPay 商户后台退还付款，然后在 OpenCart 中手动更新订单状态。Sales > Returns 中的商品退货不会通过 ECPay 退还款项。

许可证密钥

该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox ECPay Payment Gateway 位于 Extensions > Extensions > Payments > VibeFox ECPay Payment Gateway > Edit 页面中，是设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺移除密钥）。其下方是 Product: opencart-payment-ecpay 一行和链接 Manage licenses and domains in your account，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随后台语言显示（包括英文和俄文）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带日期的 License expired on。在店铺地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用上次已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的店铺地址。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，ECPay 不会在结账时向顾客显示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍可在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，这样您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：店铺看不到管理员的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 会出现提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响：已经开始的付款仍会被确认。

许可证到期后，扩展仍会继续工作，但更新和支持需要续费。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 ECPay：请检查许可证是否有效，Enable/Disable 是否开启，顾客是否以新台币结账，以及在正式模式下 Merchant ID、Hash Key 和 Hash IV 是否已设置。设置页面会显示关于货币和正式凭据的消息。还要检查付款地址是否位于所选 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：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 查看原因。

通知 URL 显示 0|Method not allowed in the browser：这是正常现象。该 URL 只接受来自 ECPay 的请求。

顾客看到 This payment method is not available. Please reload the checkout page.：结账会话已与订单不匹配，或者付款方式在此期间已被关闭。顾客应重新加载结账页面。

顾客看到 The order total is too small for ECPay.：订单总额在四舍五入后低于 1 TWD，无法通过 ECPay 付款。

顾客看到 Too many payment attempts for this order：购物车已达到 30 次付款尝试。请让顾客重新开始一个购物车。

订单处于 on-hold 状态：请阅读 VibeFox ECPay Payment Gateway 标签页中的备注（参见订单状态），与 ECPay 商户后台核对，然后处理订单或在那里退款。

对于开发人员：在付款表单发送到 ECPay 之前，扩展会触发 OpenCart 事件 ecpay_p_request_params，并附带参数和订单；商户、交易编号和金额无法通过该事件修改。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox ECPay Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还会删除使通知能在维护模式下通过的启动操作）。如果 Delete Data on Uninstall 开启，其他设置（标题、描述、测试模式、凭据、付款选项、日志记录）和日志也会被删除；如果关闭，则会保留，以便日后重新安装时使用。ECPay 付款记录始终会保留，因此在重新安装后仍会核对迟到的旧付款通知。现有订单会保留其付款备注。

在 OpenCart 4 中，若还要删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox ECPay Payment Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

ECPay 是其各自所有者的商标。本扩展与 ECPay 无关联，也未获得 ECPay 的认可。