VibeFox eWAY for OpenCart — 帮助

要求

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

PHP: 8.0 或更高版本，并带有 cURL 扩展。

货币：AUD、NZD、SGD、HKD 或 MYR。对于其他结账货币，付款方式会在结账时隐藏。付款以订单货币收取。

eWAY 账户：您需要一个具有 Rapid API 访问权限的 eWAY 商户账户，以及其 Rapid API 密钥和密码，可在 MyeWAY 的 Settings，API Key 下查看。进行测试时，您需要一个 eWAY 测试环境（sandbox）账户，并有其自己的密钥和密码。测试环境与正式环境的密钥不同。无需在 MyeWAY 中进行任何设置：每笔付款都会发送返回 URL。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请解压到您的计算机上。压缩包中包含 README.txt、OpenCart 3 安装包 wcp_eway_payment_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_eway_payment_gateway.ocmod.zip。请仅安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 输入测试环境（sandbox）的 API 密钥和密码，保持 Sandbox Mode 开启，开启 Enable/Disable，点击 Save，然后下一笔测试订单。

5. 输入正式环境的 API 密钥和密码，关闭 Sandbox Mode，然后点击 Save。

6. 可选：将设置页面显示的 cron URL 添加到服务器的定时任务中（参见配置）。

OpenCart 4

1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_eway_payment_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法使用。

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

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

4. 按 OpenCart 3 的第 3 至 6 步输入许可证密钥、eWAY 密钥和 cron URL。两个版本的设置页面及其字段相同。仅 cron URL 不同（参见 Re-check of lost returns (cron)）。

新安装默认关闭付款方式并开启测试环境模式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，一个标签会显示模式：SANDBOX — payments go to the eWAY sandbox, no real money is charged. 或 LIVE — real payments are taken with the live API key. 如果当前模式的 API 密钥或密码缺失（此时付款方式不会在结账时显示），或者 eWAY 不支持店铺的默认货币，页面会发出警告。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为整数，Total 必须为不小于零的数字，所选地理区域和订单状态必须存在。否则不会保存任何内容，页面会提示需要更正的内容。

eWAY

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

Title: 顾客在结账时看到的付款方式名称，也是订单中保存的付款方式名称。默认：Credit Card (eWAY)。必填，最多 128 个字符。

Description: 在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

Sort Order: eWAY 在结账时付款方式中的排列位置。留空或输入整数。

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

Total: 订单必须达到的结账总额（以店铺默认货币计算），才会提供 eWAY。留空则对任何金额都提供 eWAY。

API 凭据

Rapid API 密钥和密码位于 MyeWAY 的 Settings，API Key 下。eWAY 提供了正式环境和测试环境密钥的指南，本节中有相关链接。测试环境与正式环境的密钥不同。测试环境模式只使用测试环境凭据，正式模式只使用正式凭据。

Sandbox Mode: 付款会使用测试环境的密钥和密码发送到 eWAY 测试环境；不会收取真实款项。默认：开启。关闭后，将使用正式密钥接收正式付款。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real payment is taken.

Live API Key: 您的 eWAY 正式账户的 Rapid API 密钥。

Live API Password: 您的 eWAY 正式账户的 Rapid API 密码。

Sandbox API Key: 您的 eWAY 测试环境（合作伙伴/开发者）账户的 Rapid API 密钥。

Sandbox API Password: 您的 eWAY 测试环境账户的 Rapid API 密码。

已保存的密钥和密码不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

Return URL: 显示扩展的返回地址。每笔付款都会自动将其与订单及付款尝试的随机密钥一起发送给 eWAY，因此无需在 MyeWAY 中进行设置。付款结果始终由 eWAY 以服务器对服务器的方式读取。

Re-check of lost returns (cron): 可选的 cron URL，显示在返回 URL 下方。请通过服务器的定时任务每 15 分钟调用一次，例如使用 curl。如果顾客付款后在返回店铺前关闭了浏览器，则在顾客被引导至 eWAY 约 60 分钟后，会向 eWAY 查询该付款，并更新订单。如果无法连接 eWAY，检查最多重复三次。请妥善保管此 URL：它包含安装时生成的私密令牌，使用错误令牌调用会返回 Forbidden。在 OpenCart 4 中，该 URL 的格式为 https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token)。

订单

OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单）。只有在 eWAY 确认付款后，订单才会获得状态。下面每个字段都会列出您的 OpenCart 订单状态。

Order Status on Success: eWAY 确认付款后设置的状态。默认：处理中。

eWAY payment on hold status: 已批准但需要您审核的付款所使用的状态：金额或货币与订单不符，付款是在顾客于 eWAY 页面点击 Cancel 之后获得批准的，或者订单已有其他状态。订单历史中的备注会说明原因。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Refunded order status: 在订单页面将付款全额退款后设置的状态。默认：已退款。

高级

Debug log: 将 API 调用和付款结果写入 OpenCart 日志文件夹（storage/logs）中的 eway_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会移动到 eway_p_debug.old.log.php。银行卡数据、密钥、密码、顾客电子邮件和访问代码绝不会被记录。错误始终会被记录。默认：关闭。

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

Delete all extension data on uninstall: 开启后，卸载扩展时会删除网关设置和日志。订单的 eWAY 付款和退款记录始终保留。默认：关闭。

导入 / 导出

Export: Download JSON 将设置保存为 JSON 文件。API 密钥和密码不会被导出。

Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 API 密钥和密码会被保留。

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Credit Card (eWAY)）。在 Confirm Order 步骤，顾客会看到您的说明以及 You will be redirected to the secure eWAY payment page to pay by card. 的提示。OpenCart 在此步骤创建订单，仍不带状态。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币向 eWAY 申请该订单金额的付款页面，并将 OC- 加订单号作为发票参考，同时附上顾客的付款地址和电子邮件，然后将顾客引导至 eWAY 的安全付款页面（Responsive Shared Page）。顾客在该页面使用银行卡付款。付款会立即扣款。

付款后，顾客会返回您的店铺。扩展不信任浏览器：它会以服务器对服务器的方式向 eWAY 查询为该订单创建的付款页面的结果。只有在 eWAY 确认、且批准的金额和货币与订单一致后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客则会看到 OpenCart 的订单成功页面。对于处于保留状态的订单，页面还会显示 Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

如果此时无法向 eWAY 查询，则会显示 Payment confirmation 页面，内容为 We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. 并提供 Check again 按钮和 Back to checkout 按钮。顾客再次检查时，或 cron URL 运行时，订单会获得状态。

如果付款被拒绝，顾客会返回结账页面并看到原因，例如 Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. 订单仍然没有状态。如果顾客在 eWAY 页面点击 Cancel，扩展会先向 eWAY 确认是否有任何款项已支付（例如在另一个标签页中支付）。随后，顾客会看到 You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. 如果付款未完成，提示为 The payment was not completed. Please try again. 无论哪种情况，购物车都会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。

顾客可以再次尝试。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则会更新结账中的订单，因此新的尝试会为同一订单打开新的 eWAY 付款页面。因此，在创建新的付款页面之前，会向 eWAY 检查本订单及同一购物车中其他订单的先前付款页面。如果其中某个已付款，则确认该笔付款，而不是再收取第二次。如果无法向 eWAY 查询这些页面，顾客会看到 We could not check the status of your previous payment attempt. Please try again in a moment. 如果 eWAY 无法创建付款页面，顾客会停留在 Confirm Order 步骤，并看到一条简短消息，例如 Payment error: Unable to connect to eWAY. Please try again.，或 eWAY could not start the payment 以及 eWAY 的错误代码。

OpenCart 4 会在显示成功页面之前将订单保留在结账中。如果该订单在此期间未付款即被关闭（例如您取消了它），顾客会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 将为购物车支付一个新订单。如果该订单已付款，但之后购物车发生了变化（包括数量变化），提示为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 已付款的订单绝不会被显示为另一购物车的已付款订单。

返回 URL 和 cron URL 在店铺处于维护模式时同样有效，因为 OpenCart 3 会放行付款扩展的请求，并且扩展在 OpenCart 4 上为它们添加了一个启动操作（startup action）。

eWAY 不会为 Shared Page 发送服务器对服务器的通知：结果会在顾客返回时获取，并通过 cron URL 获取。该扩展在您的网站上没有银行卡输入框，不支持保存银行卡或订阅，不支持仅授权及后续扣款（capture），也不评估 Beagle 欺诈评分（被 eWAY 欺诈规则拦截的交易会由 eWAY 自身拒绝）。

订单与退款

订单状态

No status (missing order): 顾客已被引导至 eWAY，但尚未付款、已取消、付款被拒绝，或尚无法获取结果。在 Sales > Orders 中，这类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status on Success (default Processing): 付款已获批准。备注会显示 eWAY 交易 ID、授权码、响应以及模式（测试环境或正式环境）。

eWAY payment on hold status (default Pending): eWAY 批准的金额或货币与订单不同（例如 Approved for partial amount），付款是在顾客于 eWAY 页面取消之后获得批准的，或者它是针对您已设置状态的订单获得批准的，例如 Canceled。eWAY 实际扣取的金额会被记录，备注会对此加以说明。请检查订单，然后处理订单或对付款退款。

Refunded order status (default Refunded): 付款已通过扩展全额退款。

如果对已付款的订单，或同一购物车中的另一笔订单，又批准了第二笔付款，已付款的订单不会改变。备注会要求您在 MyeWAY 中退还重复付款。针对其他发票参考的已批准付款，绝不会应用到该订单上。

备注是订单 History 中的条目，顾客看不到。

VibeFox eWAY Payment Gateway 选项卡

在 Sales > Orders 中打开一笔使用 eWAY 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的 VibeFox eWAY Payment Gateway 选项卡会显示 eWAY transaction ID，并带有 Sandbox 或 Live 标签，以及 Auth code、eWAY 的 Response、Invoice reference、付款的 Status、Paid / refunded 金额、退款表单、退款历史，以及该订单的 eWAY notes。只有有权访问该扩展的用户才能看到此选项卡。

退款

在选项卡中输入金额（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via eWAY。确认提示 Refund this amount through eWAY? This cannot be undone. 支持全额退款和部分退款。您需要修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 eWAY 实际收取的金额和货币进行：因此，在部分金额获批之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款所在的环境（测试环境或正式环境）中发出，因此必须设置该环境的 API 密钥和密码。如果 eWAY 拒绝退款，选项卡会显示 eWAY refund failed: 以及 eWAY 的代码，且不会记录任何退款。退款成功后，会将其添加到退款历史和备注中，并附上 eWAY 的退款交易 ID。全额退款会将订单设置为 Refunded order status，不会通知顾客，也不会将商品退回库存，其效果与手动修改状态相同。部分退款不会改变状态。eWAY 批准付款后即可进行退款。

Sales > Returns 中的商品退货不会通过 eWAY 退还款项。在 MyeWAY 中进行的退款不会同步回 OpenCart。如有需要，请手动更新订单。

许可证密钥

该扩展需要使用从 vibefox.net 获得的 VibeFox 许可证密钥。许可证区块 License — VibeFox eWAY Payment Gateway 位于 Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至何时以及您的域名），并提供以下按钮：Check now 重新检查状态，Change key 输入另一个密钥，Remove key 从本店铺移除该密钥。其下方是 Product: opencart-payment-eway 一行，以及一个链接 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 账户中释放名额。

没有有效密钥时，eWAY 不会在结账时向顾客显示。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍然会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成扩展的设置和测试。在 OpenCart 4 中没有此预览功能：商店看不到后台登录状态，因此没有有效密钥时，付款方式会对所有人隐藏。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已开始的付款仍会被确认，退款也照常工作。

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

故障排除

eWAY does not appear at checkout: 请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 API 密钥和密码是否已填写（测试环境模式填写 sandbox 字段，正式模式填写 live 字段），以及结账货币是否为 AUD、NZD、SGD、HKD 或 MYR。凭据缺失时，设置页面会显示警告。还应检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

The payment went through, but the order stays without a status: 顾客没有从 eWAY 返回，或当时无法向 eWAY 查询。eWAY 不会为 Shared Page 发送通知。请设置 Re-check of lost returns (cron) 中的 cron URL：它会在约一小时后获取该付款。请在 MyeWAY 中检查交易，并查看扩展页面中的 Log 字段。

The cron URL answers Forbidden: URL 中的令牌有误。请完整复制设置页面中显示的 URL。

The customer sees This payment method is temporarily unavailable: 当前模式的 API 密钥或密码缺失，或者 eWAY 拒绝了它们。请检查当前模式的凭据。

The customer sees eWAY could not start the payment: eWAY 返回了错误代码，并显示在消息中。通常是账单信息无效。

The customer sees eWAY cannot take payments in a currency: 订单货币不是 eWAY 支持的货币之一。请使用 AUD、NZD、SGD、HKD 或 MYR。

The customer sees We could not match this payment to an order: 返回链接不属于本店铺的任何订单，或者 eWAY 批准了一笔针对其他发票参考的付款。如果顾客已被扣款，请在 MyeWAY 中查找该笔付款。

The customer sees This payment method is not available: 结账会话已不再与订单匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

Order is in the on hold status after payment: 请阅读 VibeFox eWAY Payment Gateway 选项卡中的 eWAY notes（参见订单状态），然后处理订单或对付款退款。

No refund form in the tab: 选项卡会说明原因：未找到该订单的 eWAY 交易 ID，订单已全额退款，您的用户组没有修改扩展的权限，或该付款所在模式的 API 凭据未设置。

Refund fails with a message about the sandbox or live mode: 订单是在该环境中付款的，而该环境的 API 密钥和密码未设置。请输入后重试。

Refund fails with at most … can be refunded: 退款金额超过了 eWAY 收取的金额减去已退款金额。

对于开发人员：扩展会触发 OpenCart 事件 wcp_eway_payment_gateway_supported_currencies（如果您的 eWAY 账户已启用更多货币）和 wcp_eway_payment_gateway_create_access_code_request（创建付款页面之前的请求正文）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox eWAY Payment Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装时这些设置会恢复为默认值。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上还包括其事件和启动操作，该操作会在维护模式下放行返回和 cron URL）。如果 Delete all plugin data on uninstall 已开启，则其余网关设置（标题、说明、测试环境模式、API 密钥和密码、调试日志开关、cron 令牌）和日志都会被删除。如果该开关关闭，这些内容会被保留，以便日后重新安装时使用。eWAY 的付款和退款记录始终保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注。

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

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