VibeFox EveryPay for OpenCart — 帮助
要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本。
EveryPay 账户：您需要店铺的 API 用户名、API 密钥（secret）和收单账户（processing account）名称。这些信息显示在 EveryPay Merchant Portal 的店铺设置中。演示门户（测试模式）与正式门户的凭据是分开的。顾客可以使用的付款方式（银行卡、Apple Pay、Google Pay、银行链接）是您的 EveryPay 账户已启用的那些。
货币：一个收单账户只结算一种货币。账户名称以其货币代码开头，例如 EUR3D1 以欧元结算。只有顾客以该货币付款时，才会提供 EveryPay。
公共网站：您店铺的回调 URL 必须可以从互联网访问，不能被基本认证或防火墙拦截。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载的是一个 zip 文件，内含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_everypay_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_everypay_payment.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_everypay_payment-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装器，而是将此安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox EveryPay Payment，点击 Install（绿色 + 按钮）。您的管理员用户需要具有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key，然后点击 Activate（参见许可证密钥）。
4. 输入演示门户中的测试 API 用户名、测试 API 密钥和收单账户名称。将 Callback notification URL 复制到 Merchant Portal 中（参见配置）。
5. 开启 Enable/Disable 并点击 Save。在测试模式下下一笔测试订单，然后输入正式凭据并关闭 Test Mode。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_everypay_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 会从文件名获取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox EveryPay Payment，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 步骤 3 至 5 的方式输入许可证密钥、EveryPay 凭据和回调。设置页面及其字段在两个版本中相同。仅回调 URL 不同（参见付款通知（callback））。
新安装默认关闭付款方式并开启测试模式。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox EveryPay Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当测试模式开启时，页面会显示 Test mode is on: payments go to the EveryPay demo environment, no real money is charged. 如果已启用付款方式，但当前模式的 API 用户名、API 密钥或收单账户缺失（此时付款方式会在结账时隐藏），或者收单账户的货币与店铺默认货币不同，页面也会发出提醒。如果没有修改扩展的权限，页面可以显示设置，但无法保存。
保存时，Title 最多 128 个字符，Sort Order 必须为整数，Total 必须为不小于零的数字，所选地理区域和订单状态必须存在。否则会显示错误并指出具体字段，且不会保存任何内容。用户名、密钥和账户名称中的空格和换行会被自动删除。
EveryPay
Enable/Disable: Enable EveryPay payment gateway 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称，也是订单中保存的付款方式名称。最多 128 个字符；如果留空，顾客会看到 EveryPay。默认：EveryPay。
Description: 在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely by card or bank link on the EveryPay payment page.
Sort Order: EveryPay 在结账时付款方式中的排列位置。留空或输入整数。
Geo Zone: 仅对所选地理区域内的付款地址提供 EveryPay。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total: 订单必须达到的结账总额（以店铺默认货币计算），才会提供 EveryPay。留空则对任何金额都提供 EveryPay。
EveryPay 账户
API 用户名、API 密钥和收单账户名称显示在 EveryPay Merchant Portal（店铺设置）中：测试模式使用演示门户，正式付款使用正式门户（本节包含两者的链接）。测试和正式环境的凭据是分开的。
Test Mode: 付款会使用测试凭据发送到 EveryPay 演示环境；不会收取真实款项。默认：开启。关闭后，将使用正式凭据接收真实付款。开启期间，顾客在 Confirm Order 步骤会看到 TEST MODE: EveryPay demo environment, no real money is charged.
Test API Username: 演示环境的 API 用户名。
Test API Secret: 演示环境的 API 密钥。
Live API Username: 正式环境的 API 用户名。
Live API Secret: 正式环境的 API 密钥。
Processing Account Name: 您的 EveryPay 收单账户，例如 EUR3D1。该账户决定结算货币：付款方式仅对该货币的订单提供。
已保存的 API 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved API secret on save，然后点击 Save。
付款通知（callback）
回调会告知您的店铺某笔付款已完成，因此即使顾客关闭了浏览器，订单也会得到确认。请将 Callback notification URL 中显示的 URL 复制到 EveryPay Merchant Portal 中您店铺的回调通知 URL 字段，演示门户和正式门户都需要设置。OpenCart 3 的 URL 形如 https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback，OpenCart 4 的 URL 形如 https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback，均由您的 OpenCart 安装的店铺前台地址生成。请按设置中显示的内容完整复制该 URL。
回调只包含付款参考信息。扩展绝不会仅凭回调就信任它：它会使用付款所在模式的凭据向 EveryPay API 查询付款状态。对于本店铺未创建的付款，回调会被直接拒绝，不会向 EveryPay 发出任何请求。即使店铺处于维护模式，回调仍然有效，因为 OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 上扩展会为此添加一个 startup action（顾客返回时也适用）。没有回调时，订单会在顾客返回店铺时，或您在订单页面点击 Check EveryPay payment status 时获得状态。
订单
OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单）。只有在 EveryPay 通过其 API 确认付款后，订单才会获得状态。下面每个字段都会列出您的 OpenCart 订单状态。
Order Status After Payment: 经核实为已结算或已授权的付款之后设置的订单状态。默认：处理中。
Manual Review Status: 已付款，但金额或货币与订单不符，订单在此期间已被取消，或订单当前使用其他付款方式。备注会说明原因，订单不会被标记为已付款。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Cancelled Order Status: 对于处于此状态的订单，如果收到付款，该付款会被转入人工审核，而不是为订单付款。默认：已取消。
高级
Debug log: 将付款事件记录到 OpenCart 日志文件夹（storage/logs）中的 wc_evp_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会移动到 wc_evp_debug.old.log.php。错误和警告始终会被记录。API 密钥、电子邮件和银行卡数据绝不会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall: 开启后，卸载扩展时会删除网关设置和日志。订单的 EveryPay 付款数据始终保留。默认：关闭。
导入 / 导出
Export: Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 API 密钥会被保留。
结账
在 Payment Method 步骤，顾客选择付款方式（默认为 EveryPay）。在 Confirm Order 步骤，顾客会看到您的说明以及 You will be redirected to the secure EveryPay payment page. 的提示。OpenCart 在此步骤创建订单，仍不带状态。在 OpenCart 4 上，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币为订单金额创建一笔一次性 EveryPay 付款，并附上顾客的电子邮件和付款地址，然后将顾客引导至 EveryPay 付款页面。付款页面的语言跟随顾客的店铺语言（英语、爱沙尼亚语、俄语、拉脱维亚语、立陶宛语、芬兰语或德语；其他语言则为英语）。顾客在该页面上使用您 EveryPay 账户中已启用的付款方式之一付款。
付款后，顾客会返回您的店铺。只有 EveryPay 确认付款后，订单才会被标记为已付款：扩展会在顾客返回时以及收到回调时，向 EveryPay API 查询付款状态。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客则会看到 OpenCart 的订单成功页面。如果 EveryPay 仍在处理付款，或者此时无法访问其 API，则会显示 Payment confirmation 页面，内容为 Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. 以及 Check again 按钮；一旦 EveryPay 确认付款，回调就会设置订单状态。
如果付款失败，顾客会返回结账页面，并显示 Your EveryPay payment was not successful. Please try again or choose another payment method. 如果顾客未付款就离开了付款页面，提示为 The EveryPay payment was not completed. You can try again or choose another payment method. 购物车会被保留，订单仍然没有状态。在 OpenCart 4 上，这些消息会显示在结账页面上方。
OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则更新结账中的订单，因此新的尝试会以新的 EveryPay 付款来支付同一订单。EveryPay 在付款创建后无法取消。因此，在新付款之前，扩展会通过 EveryPay API 检查本订单以及同一购物车中其他订单的未完成付款尝试。如果其中某笔已付款，或同一购物车中的另一笔订单已付款，顾客将直接进入成功页面，无需再次付款。每次尝试都会被记录，因此即使顾客使用旧链接完成付款，也能被识别。如果顾客仍然为同一购物车中的第二笔订单付款（例如从两个打开的浏览器标签页付款），该订单不会获得状态，顾客会看到订单成功页面，已付款的订单会收到一条备注，提醒您在 EveryPay Merchant Portal 中退还第二笔付款。
OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即已关闭（例如您取消了它），顾客会被送回结账页面，并显示 Your previous order was cancelled. Please confirm the order again.，下一次 Confirm Order 会为购物车支付一笔新订单。如果该订单已付款，但购物车此后发生了变化（包括数量改变），则显示 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. 已付款的订单绝不会对不同的购物车显示为已付款。
如果 EveryPay 无法发起付款，顾客会停留在 Confirm Order 步骤，按钮上方显示一条简短消息，例如 EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. 详细信息记录在日志中。
该扩展仅支持一次性付款。店铺端不支持退款或扣款（capture），不支持保存银行卡或一键付款，不支持订阅或定期付款，不支持嵌入式银行卡输入框，也不支持多币种。
订单
订单状态
No status (missing order): 顾客已被引导至 EveryPay，但尚未付款、付款失败或被放弃，或者 EveryPay 尚未确认付款。在 Sales > Orders 中，这类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。
Order Status After Payment (default Processing): EveryPay 报告付款已结算或已授权。备注会显示金额、货币和付款参考号。对于已授权的付款，备注会说明资金已被预留：如果您的账户不会自动扣款，请在 EveryPay Merchant Portal 中扣款（capture）。付款之后结算时，会有一条备注说明这一点。
Manual Review Status (default Pending): 付款需要人工审核。已付金额或货币与订单不符，订单在付款到达前已设置 Cancelled Order Status，或者订单现在使用其他付款方式。备注会说明这一点，并注明订单未被标记为已付款。请在 Merchant Portal 中核实付款，然后手动处理订单或退款。此后该付款的回调不会自动完成订单；但同一订单的另一次尝试如果付款正确，仍会使订单付款完成。
如果为已付款的订单又完成了第二笔付款，订单不会改变。备注会提醒您在 EveryPay Merchant Portal 中退还重复付款。备注是订单 History 中的条目，顾客看不到。
VibeFox EveryPay Payment 选项卡
在 Sales > Orders 中打开一笔使用 EveryPay 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的 VibeFox EveryPay Payment 选项卡会显示该订单的 EveryPay payments of this order：每次尝试的 Payment reference、Order reference、Mode（测试或正式）、Amount、EveryPay state、Result 和 Date。下方是该订单的 EveryPay notes。只有有权访问该扩展的用户才能看到此选项卡。
Check EveryPay payment status: 选项卡中的按钮会按从新到旧的顺序，使用各付款所属模式的凭据，从 API 读取该订单每笔 EveryPay 付款的状态，按上文所述应用结果，并添加一条备注，列出每笔付款的状态。之后选项卡会重新加载。您需要修改订单的权限（System > Users > User Groups）；不需要修改扩展的权限。当回调从未到达时使用此功能，例如查看之后的扣款或退款。通过此按钮设置的状态会像后台手动修改状态一样记录，不会发送结账时的订单邮件，也不会更新库存。
退款
不支持在店铺中进行退款和扣款（capture）。请在 EveryPay Merchant Portal 中退款，然后在 OpenCart 中更新订单状态。当 EveryPay 报告某笔付款已退款或被拒付（chargeback）时，扩展只会在订单中添加一条备注，订单状态不会改变。Sales > Returns 中的商品退货不会通过 EveryPay 退还款项。
许可证密钥
该扩展需要使用从 vibefox.net 获得的 VibeFox 许可证密钥。许可证区块 License — VibeFox EveryPay Payment 位于 Extensions > Extensions > Payments > VibeFox EveryPay Payment > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期至何时以及您的域名），并提供以下按钮：Check now 重新检查状态，Change key 输入另一个密钥，Remove key 从本店铺移除该密钥。其下方是 Product: opencart-payment-everypay 一行，以及一个链接 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 账户中释放名额。
没有有效密钥时，EveryPay 不会在结账时向顾客显示。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍然会在店铺中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前完成扩展的设置和测试。在 OpenCart 4 上没有此预览：商店看不到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台 Dashboard 上会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已开始的付款仍会被确认。
许可证过期后，扩展仍会继续工作，但更新和支持需要续期。打开后台 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，许可证密钥和许可证状态始终会被删除。
故障排除
EveryPay does not appear at checkout: 请检查许可证是否有效、Enable/Disable 是否开启、当前模式的 API 用户名、API 密钥和 Processing Account Name 是否已填写，以及顾客是否使用收单账户的货币付款。在这些情况下，设置页面会显示警告。还应检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。
The payment went through, but the order stays without a status: 回调没有正常工作。请检查您所用模式（演示或正式）的 Merchant Portal 中是否已设置 Callback notification URL 中的 URL，并且该 URL 可以从互联网打开。顾客付款后返回店铺时，订单也会获得状态。请查看扩展页面中的 Log 字段：错误始终会被记录。
Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: 该付款不是由本店铺创建的，或不是为此订单创建的，或 EveryPay 的应答与之不匹配。不会做任何更改。
Callback answers Missing or invalid payment_reference: 请求中没有有效的付款参考号，例如在浏览器中直接打开该 URL 时。
Callback answers Not configured: 创建付款所在环境的凭据缺失，例如删除测试凭据后进行的测试付款。请重新输入凭据；EveryPay 会重试回调。
Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: 无法连接 EveryPay API，订单在同一时刻正被另一个请求处理，或处理失败。原因记录在日志中。EveryPay 会重试回调。
The customer sees This payment method is not available right now: 当前模式的凭据或收单账户缺失。
The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: EveryPay 拒绝了凭据，或无法连接。请检查当前模式的 API 用户名和 API 密钥。
The customer sees This payment method does not support the order currency: 订单货币与收单账户的货币不同。
The customer stays on the Payment confirmation page: EveryPay 尚未完成付款。订单将通过回调获得状态，或在 EveryPay 确认付款后由顾客点击 Check again 获得状态。
Order is in the review status: 请阅读 VibeFox EveryPay Payment 选项卡中的 EveryPay notes。金额或货币不符，订单在付款到达前已被取消，或订单使用了其他付款方式。请在 Merchant Portal 中核实付款，然后手动处理订单或退款。
对于开发人员：在创建付款之前，扩展会触发 OpenCart 事件 wc_evp_oneoff_request（修改付款请求）和 wc_evp_locale（修改付款页面语言）。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox EveryPay Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态；重新安装时这些设置会恢复为默认值。在 OpenCart 4 上，扩展的事件（结账消息）及其 startup action（在维护模式下允许回调和顾客返回）也会被删除。如果 Advanced 中的 Uninstall 开关已开启，则其余网关设置（标题、说明、测试模式、凭据、收单账户、调试日志）和日志都会被删除。如果该开关关闭，这些内容会被保留，以便日后重新安装时使用。订单的 EveryPay 付款数据始终保留，因此重新安装后，旧订单的延迟回调仍然有效。现有订单会保留其付款备注。
在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox EveryPay Payment 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
EveryPay 是其各自所有者的商标。本扩展与 EveryPay 没有关联，也未获得 EveryPay 的认可。