VibeFox Autopay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Autopay 服务：您需要 Autopay 服务的 Service ID 和 Shared key（哈希密钥）。它们显示在 Autopay 商户门户中：正式环境使用 portal.autopay.eu，测试环境使用 testportal.autopay.eu。测试服务有各自的 Service ID 和 Shared key；请联系 Autopay 为您开通。服务的哈希函数必须为 SHA-256。

货币：订单货币必须是 PLN、EUR、GBP、USD 或 CZK，并且须被您的 Autopay 服务接受。

可访问的店铺：Autopay 必须能够向您的店铺发送通知，因此店铺必须可以从互联网访问，且不能启用基本身份验证，也不能有阻止 POST 请求的防火墙。维护模式不会阻止通知，因为 OpenCart 允许支付扩展的请求通过。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先将其解压到您的电脑上。压缩包中包括 README.txt、OpenCart 3 安装包 wcp_autopay_payment-oc3-(version).ocmod.zip，以及 OpenCart 4 安装包 wcp_autopay_payment.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

4. 输入 Service ID 和 Shared key（测试和正式），并选择您的服务所支持的货币。

5. 在 Autopay 门户中为您的服务设置 ITN URL、返回 URL 以及 SHA-256 哈希函数（参见配置）。

6. 开启 Enable/Disable，然后点击 Save。在测试模式下下一笔测试订单，然后关闭 Test mode 以接收真实付款。

OpenCart 4

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

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

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

4. 请按照 OpenCart 3 步骤 3 至 6 输入许可证密钥和设置。两个版本的设置页面及其字段完全相同，只有 ITN 和返回地址不同（参见 ITN 与返回地址）。

新安装时，付款方式默认关闭，测试模式默认开启，且仅启用 PLN 一种货币。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Autopay Payment > Edit。各设置区块列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当所选环境的 Service ID 或 Shared key 为空时（此时结账时会隐藏付款方式），以及当商店默认货币未在 Currencies 中选中时（此时在该货币下会隐藏付款方式），页面会给出提示。测试模式开启时，页面会显示 Test mode is on: payments go to the Autopay test environment (testpay.autopay.eu), no real money is taken. 如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须是整数，Total 必须是大于或等于 0 的数字，并且 Service ID 只能包含字母、数字、连字符和下划线。如果任一字段有误，则不会保存任何内容，页面会指出该字段。

Autopay

Enable/Disable：Enable Autopay payment gateway 用于开启或关闭该付款方式。默认：关闭。

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

Description：顾客在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay online by bank transfer, BLIK or card. You will be redirected to the secure Autopay payment page.

Sort Order：Autopay 在结账页面各付款方式中的位置。留空或输入整数。

Geo Zone：仅为所选地区内的付款地址显示 Autopay。默认：All zones。地区在 System > Localisation > Geo Zones 中设置。

Total：订单在结账时必须达到的金额（以商店默认货币计）才会提供 Autopay。留空则对任意金额都提供 Autopay。

Autopay 服务

Service ID 和 Shared key 显示在 Autopay 商户门户中（portal.autopay.eu 或 testportal.autopay.eu，本节提供链接）。

Test mode：使用 Autopay 测试环境（testpay.autopay.eu）及下方的测试凭据。默认：开启。关闭后，将使用正式凭据在 pay.autopay.eu 上接受真实付款。开启时，顾客在 Confirm Order 步骤中会看到 Test mode: no real payment is taken.

Service ID (production)：来自 portal.autopay.eu 的数字服务标识符。

Shared key (production)：正式服务的哈希密钥。请妥善保密。

Service ID (test)：来自 testportal.autopay.eu 的数字服务标识符。

Shared key (test)：测试服务的哈希密钥。

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

Currencies：您的 Autopay 服务接受的货币：PLN、EUR、GBP、USD、CZK。Autopay 通常会为每种货币单独开通一项服务。只有在此处选中结账货币时，才会提供该付款方式。默认：PLN。

ITN 与返回地址

请在 Autopay 门户中为您的服务（正式和测试环境）填写以下地址。具体地址显示在本节的 Addresses 字段中，并由您的 OpenCart 安装的店铺地址生成：

以下为 OpenCart 3 的地址。在 OpenCart 4 中，它们为：

请完全按照设置中显示的内容复制这些地址。如果没有 ITN URL，订单永远不会被确认：在 Autopay 确认付款之前，OpenCart 会让订单保持无状态。每条 ITN 都会使用通知中所指定服务的 Shared key 生成的 SHA-256 哈希进行校验。没有有效哈希或 Service ID 未知的通知会被拒绝。只有当某笔付款是使用同一 Autopay 服务发起的，通知才会应用到订单上，因此测试通知绝不会确认正式付款。在切换 Test mode 之前发起的付款，只要两套凭据仍保存着，其通知依然会使用正确的密钥进行校验。

扩展在 ITN 中处理以下付款状态：

Orders

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（缺失订单）。只有当 Autopay 确认付款（ITN SUCCESS）时，订单才会获得状态。付款失败或被放弃的，订单将保持无状态。在 OpenCart 4 中，未付款的结账订单可能会获得 Voided 状态，该状态由 OpenCart 4 在顾客返回 Confirm Order 步骤时设置；扩展会将这样的订单视为无状态订单，之后收到的 ITN SUCCESS 仍会将其标记为已付款。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：当 Autopay 以预期金额和货币确认付款时设置的状态。默认：Processing。

On Hold Status：付款金额或货币与订单不符，或者付款是在订单状态已被更改（例如已取消）之后到达的。订单不会被标记为已付款；备注会说明原因。默认：Pending，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Advanced

Logging：将付款事件写入 OpenCart 日志文件夹（storage/logs）中的 wc_ap_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 wc_ap_debug.old.log.php。密钥和顾客数据从不记录在日志中。默认：关闭。关闭时不会写入任何内容，包括错误。

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

Import / Export

Export：Download JSON 会将设置保存为 JSON 文件。Shared key 不会被导出。

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Autopay）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the secure Autopay payment page to complete the payment. OpenCart 在此步骤创建订单，但订单仍没有状态。顾客点击 Confirm Order 后，浏览器会向 Autopay 发送一份已签名的付款表单，其中包含以订单货币表示的订单总额、作为 OrderID 的 OpenCart 订单号、描述 Order 加订单号，以及顾客的电子邮件地址。在 Autopay 页面上，顾客选择付款方式并完成付款。

只有在 Autopay 通过已签名的 ITN 确认付款，并且金额和货币与订单一致后，订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存。付款后，顾客会返回您的店铺。返回地址是已签名的，但它绝不会更改订单。如果订单已经有状态，顾客会看到 OpenCart 订单成功页面。如果 ITN 尚未到达，Payment confirmation 页面会显示 Thank you. Your payment is being confirmed by Autopay — your order is confirmed as soon as Autopay reports the payment, and you will receive an e-mail. 并提供 Check again 和 Back to checkout 按钮。

如果 Autopay 报告付款失败，顾客会带着 The payment was not completed. You can try again or choose another payment method. 的提示返回结账页面。购物车会被保留。每次新的尝试都会创建一个新的 OpenCart 订单（在 OpenCart 4 中，顾客会以新的尝试、相同的 OrderID 再次为同一订单付款）。如果同一购物车（同一次访问中的相同商品）的另一个订单已付款，顾客会直接进入成功页面，而不会再次付款。完成一次购买后再次购买，属于新的购物车，会正常付款。如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 Autopay payments are not configured. Please choose another payment method or contact the store. 或者 Autopay 无法以该货币接受付款。

在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。付款未完成的提示会显示在结账页面上方。OpenCart 4 会为结账保留一个订单并更新它。如果该订单在此期间已被店铺关闭（例如您取消了它），顾客会被带回结账页面，并看到 The payment was not completed. You can try again or choose another payment method. 提示；如果该订单已通过 Autopay 付款，则会看到 Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. 如果结账的订单已为另一个购物车付款，提示为 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. 下一次点击 Confirm Order 将为新订单付款。购物车的任何变动（包括新的数量）都会被视为需要单独付款的新购物车。即使店铺处于维护模式，ITN 也能正常工作：在 OpenCart 4 中，扩展为此添加了一个 startup action（启动动作）。

该扩展不支持从 OpenCart 退款，不支持订阅或定期付款，不支持保存的银行卡，结账页面上没有 BLIK 代码或银行卡表单，结账页面上也不能选择银行或付款渠道，并且每个环境只使用一个 Service ID。

订单

Order statuses

No status (missing order)：顾客已被转到 Autopay 但尚未付款，付款失败，或者 Autopay 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order Status After Payment (default Processing)：Autopay 已确认付款，且金额和货币一致。备注会显示金额、Autopay 交易 ID（remoteID）和付款日期。

On Hold Status (default Pending)：Autopay 报告的金额或货币与订单总额不一致。订单不会被标记为已付款。请在 Autopay 门户中检查该交易，并手动完成或退款。之后针对该订单的正确通知会将其标记为已付款。当某个订单的状态已被您更改（例如已取消）后又收到付款时，也会使用同一状态：备注会提醒您检查库存并履行订单，或退还付款。

已付款的订单绝不会因之后的失败通知而被更改。如果 Autopay 对已付款订单报告了另一笔成功付款，或同一购物车的第二个订单已付款，备注会警告顾客可能重复付款。对于使用其他 Autopay 服务发起的付款，其通知不会被应用，备注会对此作出说明。备注是订单 History 中的条目，顾客看不到。

VibeFox Autopay Payment tab

在 Sales > Orders 中打开一笔通过 Autopay 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox Autopay Payment 选项卡会显示 OrderID at Autopay、Service ID 以及环境（测试付款会附带 Test mode 标签）、Amount、Payment attempt 状态、Autopay transaction ID 以及订单的 Autopay notes。该选项卡为只读，并且仅显示给有权访问该扩展的用户。

Refunds

不支持通过 Autopay 退款。请在 Autopay 门户中退还付款，然后在 OpenCart 中手动更新订单。

许可证密钥

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

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

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

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

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

故障排除

Autopay 没有出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启、所选环境是否有 Service ID 和 Shared key，以及结账货币是否已在 Currencies 中选中。缺少其中任何一项时，设置页面都会显示警告。另请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。

付款已完成，但订单仍没有状态：Autopay 未能送达 ITN，或者店铺拒绝了它。请检查设置中显示的 ITN URL 是否已在 Autopay 门户中为该服务（正式或测试）设置，哈希函数是否为 SHA-256，以及扩展中的 Shared key 是否与服务匹配。请检查店铺是否可以从互联网访问。开启 Logging，并查看扩展页面上的 Log 字段。

日志显示 ITN rejected: invalid hash：Shared key 与服务不匹配，或服务的哈希函数不是 SHA-256。

日志显示 service ID 未配置：该通知来自某个服务，而其 Service ID 没有在扩展中填写，或其 Shared key 为空。

日志显示 could not lock the order, Autopay will retry：订单在同一时刻正被另一条通知处理。店铺的响应会让 Autopay 再次发送该通知。

ITN URL 在浏览器中显示 METHOD_NOT_ALLOWED：这是正常现象。该 URL 只接受来自 Autopay 的 POST 请求。

订单处于带有不一致备注的 on-hold 状态：Autopay 报告的金额或货币与订单总额不符。请在 Autopay 门户中检查该交易，并手动完成或退款。

备注显示通知未被应用：该订单的付款并非使用此 Autopay 服务发起，例如正式订单收到了测试通知。请在 Autopay 门户中检查该交易。

付款后顾客落在首页：无法验证返回地址，例如因为 Service ID 未在扩展中填写。订单不受影响，它会依据 ITN 处理。

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

面向开发者：在对付款表单签名之前，扩展会触发 OpenCart 事件 wc_ap_payment_params，并传入表单参数和订单；该事件无法更改服务、订单号、金额和货币。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Autopay Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态。扩展始终会删除其他网关设置（包括 Service ID 和 Shared key）以及日志。没有保留设置的选项。在 OpenCart 4 中，扩展的事件以及在维护模式下让 ITN 通过的 startup action 也会被删除。Autopay 付款记录始终保留。现有订单会保留其付款备注。

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

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