VibeFox eWAY for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在更旧的 PHP 版本上安装。
店铺币种：AUD、NZD、SGD、HKD 或 MYR。对于其他购物车币种，结账时会隐藏该付款方式。付款以购物车币种扣款。
eWAY 账户：您需要一个开通了 Rapid API 权限的 eWAY 商户账户，以及其 Rapid API 密钥和密码，可在 MyeWAY 的 Settings, API Key 中获取。测试时，您需要一个拥有独立密钥和密码的 eWAY 沙盒账户。沙盒密钥与正式环境密钥是不同的。无需在 eWAY 中进行任何设置：每笔付款都会附带返回 URL。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module，选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox eWAY Payment Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key，然后点击 Activate（参见「许可证密钥」）。
4. 输入您的沙盒 API 密钥和密码，保持 Sandbox Mode 为开启状态，打开 Enable/Disable，点击 Save，然后下一笔测试订单。
5. 输入您的正式环境 API 密钥和密码，关闭 Sandbox Mode，然后点击 Save。
6. 可选：将 Configure 页面上显示的 cron URL 添加到服务器的 cron 任务中（参见配置）。
安装时，模块会创建订单状态 eWAY payment on hold。PrestaShop 会为所有币种、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure。每个部分都有各自的 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 支持时，页面都会向您发出警告。
eWAY
Enable/Disable: Enable eWAY Payment Gateway 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Credit Card (eWAY)。必填。
Description: 结账时显示在付款方式下方的文字。默认：Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.
API 凭据
Rapid API 密钥和密码位于 MyeWAY 的 Settings, API Key 中。eWAY 提供了正式环境密钥和沙盒密钥的指南，本部分中已附上链接。沙盒和正式环境使用不同的密钥。
Sandbox Mode: 付款会使用沙盒密钥和密码，发送到 eWAY 沙盒。不会扣除真实款项。默认：开启。关闭后，将使用正式环境密钥接收真实付款。开启期间，顾客会在付款方式下方看到 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 saved credentials: 勾选某个密钥或密码，然后点击 Save 即可将其删除。字段留空则保留已保存的值。
Return URL / re-checks: 无需在 eWAY 中配置任何 webhook 或返回 URL，因为每笔付款都会附带返回 URL。此字段显示一个可选的 cron URL。请在服务器的 cron 任务中调用它，例如每 15 分钟一次。如果顾客付款后在返回店铺之前关闭了浏览器，则会在约一小时后向 eWAY 查询该付款，并创建订单。如果无法连接 eWAY，检查最多会重复三次。请保密此 URL：其中包含一个令牌，使用错误令牌调用时会返回 Forbidden。
订单
Order Status on Success: eWAY 确认付款后的订单状态。
与订单不一致的已批准金额或币种，始终会转为 eWAY payment on hold。
高级
Debug log: 将 API 调用和付款结果写入模块文件夹中的 logs/eway_p_debug.log.php。该文件无法通过网页打开。银行卡数据、密钥、密码、顾客邮箱和访问代码都不会被记录。错误始终会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete all plugin data on uninstall: 开启后，卸载模块会删除网关设置和日志。订单中的 eWAY 付款数据和 eWAY payment on hold 订单状态始终会保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 Credit Card (eWAY)）并确认。模块会向 eWAY 请求一个付款页面，金额为购物车总额，使用购物车币种，并附上 PS- 加购物车编号作为发票参考，以及顾客的账单地址和邮箱，然后将顾客转到 eWAY Responsive Shared Page。顾客在该页面用银行卡付款。扣款是即时的。此时尚未生成任何订单。
付款后，顾客返回您的店铺。模块不信任浏览器：它会以服务器对服务器的方式向 eWAY 查询为该购物车创建的付款页面的结果。只有在 eWAY 确认、且已批准的金额和币种与购物车一致后，订单才会被标记为已付款。随后订单被创建，顾客会看到标准的订单确认页面，显示 Your payment with eWAY has been received. 对于处于保留状态的订单，页面会显示 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. 无论哪种情况，购物车都会被保留。
顾客可以重试。在创建新的付款页面之前，会向 eWAY 检查该购物车之前的页面。如果它已经付款，则会创建订单，而不是再次付款。如果 eWAY 无法创建付款页面，顾客会停留在结账页面，并看到简短提示，例如 Payment error: Unable to connect to eWAY. Please try again. 或 eWAY could not start the payment，并附带 eWAY 错误代码。
对于 Shared Page，eWAY 不会发送服务器对服务器的通知：结果会在顾客返回时以及通过 cron URL 获取。本模块在您的网站上没有银行卡输入框，不支持保存银行卡或订阅，不支持仅授权和扣款，也不评估 Beagle 欺诈评分（被 eWAY 欺诈规则拦截的交易由 eWAY 自行拒绝）。
订单与退款
订单状态
No order yet: 顾客已被转到 eWAY，但尚未付款、已取消、付款被拒绝，或尚无法获取结果。目前只存在购物车。
Payment accepted or Delivered: 付款已获批准。状态遵循 Order Status on Success。付款会以 eWAY 交易 ID 记录，备注中会显示交易 ID、授权码、响应以及模式（沙盒或正式环境）。
eWAY payment on hold: eWAY 批准的金额或币种与购物车不同（例如 Approved for partial amount，或顾客打开付款页面后购物车被修改），付款是在顾客于 eWAY 页面取消之后才获批准的，或者是在订单被取消之后才获批准的。付款会以 eWAY 实际扣款的金额记录，备注会说明原因。请检查订单，然后处理订单或退还付款。
Refunded: 付款已通过模块全额退款。
如果对一个已付款的购物车又批准了第二笔付款，订单不会改变。备注会要求您在 MyeWAY 中退还重复的付款。对于其他发票参考批准的付款，绝不会应用到该订单上。
eWAY 付款区块
订单页面会显示 eWAY payment 区块，包括交易 ID、授权码、eWAY 响应、状态、模式和发票参考、已付金额和已退金额、用于沙盒付款的 Sandbox 标识、退款记录以及订单的 eWAY notes。
退款
在 eWAY payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via eWAY。确认提示 Refund this amount through eWAY? This cannot be undone. 后即可退款。支持全额退款和部分退款。您需要具有编辑订单的权限；不需要访问模块页面。退款以 eWAY 实际扣款的金额和币种进行，因此在部分金额获批后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会在付款所用的环境（沙盒或正式环境）中发送，因此该环境的 API 密钥和密码必须已设置。如果 eWAY 拒绝退款，该区块会显示 eWAY refund failed: 以及 eWAY 错误代码，并且不会记录任何退款。成功的退款会添加到退款记录中，并在备注中记录 eWAY 退款交易 ID。全额退款会将订单设为 Refunded。部分退款不会改变状态。只有在 eWAY 批准付款后，才能进行退款。
模块不会创建信用单（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 eWAY 退款。在 MyeWAY 中所做的退款不会同步回 PrestaShop。如有需要，请手动更新订单。
许可证密钥
本模块需要一个在 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox eWAY Payment Gateway 是 Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure 页面中的第一个区块，位于设置上方。请将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中移除密钥）。其下方是 Product: presta-payment-eway 一行，以及 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 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 eWAY。如果仍然发起了付款，顾客会看到 此付款方式不可用，请选择其他付款方式。 PrestaShop 前台无法得知您已登录后台，因此付款方式对您同样隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响：已开始的付款仍会被确认，退款也仍可进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续订。在后台工作期间会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
eWAY does not appear at checkout: 请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 API 密钥和密码是否已设置（沙盒模式使用沙盒字段，正式模式使用正式字段），以及购物车币种是否为 AUD、NZD、SGD、HKD 或 MYR。缺少凭据时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于该购物车币种、顾客所在国家以及顾客所在群组。
The payment went through, but no order was created: 顾客没有从 eWAY 返回，或者当时无法查询 eWAY。eWAY 不会为 Shared Page 发送通知。请设置 Return URL / re-checks 中的 cron URL：它会在约一小时后获取该付款。请在 MyeWAY 中检查该交易，并查看模块页面上的 Log 字段。
The customer sees This payment method is temporarily unavailable: 当前模式的 API 密钥或密码缺失，或者 eWAY 拒绝了它们。请检查当前模式的凭据。
The customer sees eWAY could not start the payment: eWAY 返回了错误代码，并显示在消息中。通常是账单信息无效。
The customer sees We could not match this payment to an order: 返回链接不属于本店铺的任何购物车，或者 eWAY 为其他发票参考批准了一笔付款。如果顾客已被扣款，请在 MyeWAY 中找到该付款。
The customer sees We could not check the status of your previous payment attempt: 另一个请求正在处理同一个购物车。顾客可以稍后再试。
Order is eWAY payment on hold after payment: 请阅读 eWAY payment 区块中的 eWAY notes（参见订单状态），然后处理订单或退还付款。
Refund fails with a message about the sandbox or live mode: 该订单是在该环境中付款的，而该环境的 API 密钥和密码未设置。请输入后重试。
Refund fails with at most … can be refunded: 退款金额超过了 eWAY 扣款金额减去已完成退款后的余额。
对于开发者：模块的 README 中列出了 actionWcpEwaySupportedCurrencies 钩子，适用于您的 eWAY 账户已开通更多币种的情况。
卸载
进入 Modules > Module Manager，打开 VibeFox eWAY Payment Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete all plugin data on uninstall 已开启，则会删除网关设置和日志。如果已关闭，所有设置都会保留，以便日后重新安装。订单中的 eWAY 付款数据和 eWAY payment on hold 订单状态始终会保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。
eWAY 是其各自所有者的商标。本模块与 eWAY 无关联，也未获得 eWAY 的认可。