VibeFox Montonio for OpenCart — 帮助
要求
OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP：8.0 或更高版本。
货币：结账货币必须为 EUR 或 PLN。对于其他任何货币，结账时将隐藏该付款方式。
Montonio 账户：您需要 Montonio Partner System 中商店的访问密钥（access key）和密钥（secret key）。沙盒和正式环境的密钥不同，因此您使用的每个环境都需要一对密钥。除此之外，无需在 Montonio 中进行其他设置：每笔付款都会附带通知地址。
公开网站：您的商店必须可以从互联网访问，才能接收 Montonio 的通知。否则，客户返回商店时，订单仍会获得状态。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先解压到您的电脑上。其中包括 README.txt、OpenCart 3 安装包 wcp_montonio_payment-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_montonio_payment.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本的许可证密钥相同。
OpenCart 3
1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_montonio_payment-oc3-(version).ocmod.zip。该扩展不包含 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Montonio Payment，点击 Install（绿色的 + 按钮）。您的管理员用户需要有修改付款扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见许可证密钥）。
4. 在 Montonio Partner System 中打开 Stores > your store > API keys，复制沙盒访问密钥和密钥。将其粘贴到设置中，并保持 Sandbox mode 为开启状态。
5. 开启 Enable/Disable，点击 Save，然后使用一笔 EUR 订单在沙盒中测试付款。之后，输入正式环境的密钥并关闭 Sandbox mode。
OpenCart 4
1. 在管理后台中进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_montonio_payment.ocmod.zip。请勿重命名该文件：OpenCart 4 从文件名获取扩展代码，重命名后的安装包将无法工作。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色的 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Montonio Payment，点击 Install（绿色的 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 Montonio 密钥。两个版本的设置页面及其字段相同。只有通知地址不同（参见 Notification URL）。
新安装时，付款方式默认关闭，沙盒模式默认开启。
配置
所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Montonio Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在当前环境的密钥缺失时（此时结账时会隐藏该付款方式）和商店的默认货币不是 EUR 或 PLN 时发出提醒；只要沙盒处于开启状态，页面还会显示 沙盒模式已开启：付款将被模拟，不会扣除任何真实款项。 如果您没有修改该扩展的权限，页面会显示设置，但无法保存。
保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，且地理区域和订单状态必须存在。如果任何值有误，则不会保存任何内容，页面会指出相应字段。
Montonio
Enable/Disable：Enable Montonio bank payments 用于开启或关闭该付款方式。默认：关闭。
Title：客户在结账时看到的付款方式名称。它也是保存在订单中的付款方式名称，并显示在 Montonio 页面上。默认：Bank payment (Montonio)。必填，最多 128 个字符。
Description：客户在 Confirm Order 步骤中、确认按钮上方看到的文字。默认：Pay directly from your bank account. You will be redirected to Montonio to choose your bank.
Sort Order：Montonio 在结账时的付款方式中的排列位置。留空或输入整数。
Geo Zone：仅向付款地址位于所选地理区域内的客户提供 Montonio。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total：订单必须达到的结账总额（以商店的默认货币计）之后才会提供 Montonio。留空则对任何金额都提供 Montonio。
API 密钥
请在 Montonio Partner System（页面中有链接）的 Stores > your store > API keys 下获取密钥。沙盒和正式环境的密钥不同。沙盒仅使用沙盒密钥，正式模式仅使用正式密钥。
Sandbox mode：使用 Montonio 沙盒（测试付款，不涉及真实资金）。它会同时切换 Montonio API 地址和密钥对。默认：开启。仅在输入正式密钥后才将其关闭。在另一环境中完成的付款，在确认和退款时仍使用其所属环境的密钥。开启期间，客户在 Confirm Order 步骤中会看到 沙盒模式：测试付款，不会扣除任何真实款项。
Sandbox access key：您的商店在 Montonio 沙盒中的访问密钥（UUID）。
Sandbox secret key：您的商店在 Montonio 沙盒中的密钥。
Live access key：您的商店在 Montonio 正式环境中的访问密钥（UUID）。
Live secret key：您的商店在 Montonio 正式环境中的密钥。
已保存的密钥不会再次显示。该字段保持为空，并显示 已保存——留空即可保留。 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。
Notification URL：Montonio 发送付款通知的地址。在 OpenCart 3 上其格式类似于 https://your-store/index.php?route=extension/payment/wcp_montonio_payment/notification，在 OpenCart 4 上类似于 https://your-store/index.php?route=extension/wcp_montonio_payment/payment/wcp_montonio_payment.notification，由您的 OpenCart 安装的商店前台地址生成。您无需在任何地方输入它：扩展会在每笔付款时将其发送给 Montonio。
订单
OpenCart 在 Confirm Order 步骤创建订单时没有状态（缺失订单）。只有在 Montonio 确认付款后，订单才会获得状态。下面的每个字段都会列出您的 OpenCart 订单状态。
Order Status After Payment：经验证的 Montonio 付款之后设置的状态。默认：处理中。
Payment On Hold Status：付款需要关注（参见订单状态）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择它。
Payment Failed Status：当银行拒绝一笔已被暂存为已授权的付款时设置。默认：失败。
Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。
高级
Debug log：将付款事件写入 OpenCart 日志文件夹（storage/logs）中的 wc_mnt_debug.log.php。该文件无法通过网页打开，达到 5 MB 时会被移至 wc_mnt_debug.old.log.php。即使此选项关闭，错误和警告仍会始终记录。密钥、令牌和客户数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data：开启后，卸载扩展会删除网关设置及其日志。禁用扩展不会删除任何内容。订单数据（Montonio UUID、备注）始终保留。默认：关闭。
导入 / 导出
Export：Download JSON 会将设置保存为 JSON 文件。访问密钥和密钥不会被导出。
Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的访问密钥和密钥将被保留。
付款通知
Montonio 通过带签名的令牌告知您的商店每笔付款的情况。令牌通过两种方式送达：一是通过服务器到服务器的通知发送到通知地址，二是在客户返回商店时随客户一起送达。两者都会进行校验：使用创建该付款所在环境的密钥进行签名验证、有效期、您的访问密钥，以及该付款是否为您的商店为该订单所创建。使用另一环境密钥签名的令牌会被拒绝。每个状态只应用一次，因此重复的通知不会添加备注、电子邮件或库存变动。即使商店处于维护模式，通知地址仍然有效，因为 OpenCart 3 允许付款扩展的请求通过；在 OpenCart 4 上，扩展还会为此添加一个启动操作，它同样允许客户从 Montonio 返回。
结账
在 Payment Method 步骤中，客户选择付款方式（默认为 Bank payment (Montonio)）。在 Confirm Order 步骤中，客户会看到 Montonio 图标和您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。当客户点击 Confirm Order 时，扩展会以订单货币为订单总额创建一笔 Montonio 付款，并将客户转到 Montonio 付款页面。在那里，客户选择银行并付款。在 OpenCart 4 上，客户通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。客户账单国家的银行会优先显示（PLN 订单则为波兰）。该付款会显示为 Order 和订单号。如果商店语言为德语、英语、爱沙尼亚语、芬兰语、立陶宛语、拉脱维亚语、波兰语或俄语，Montonio 页面将以该语言打开；否则以英语打开。
只有在 Montonio 确认付款之后（通过通知或客户返回时），订单才会被标记为已付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规的订单电子邮件、更新库存；客户会看到 OpenCart 的订单成功页面，显示 Your Montonio bank payment has been received. 如果银行尚未确认付款，或订单处于暂停状态，页面会显示 We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. 如果银行之后拒绝了已授权的付款，页面会显示 Your Montonio payment was not completed. Please contact us about this order.
如果客户返回时 Montonio 报告付款仍处于待处理状态，则会显示一个 Payment confirmation 页面，内容相同，并附带一个 Check again 按钮和一个 Back to checkout 按钮。Check again 会向 Montonio 查询付款的当前状态。通知一旦到达，便会设置订单状态。
如果付款被取消或被拒绝，客户将返回结账页面，并看到以下信息之一：The payment was cancelled or rejected by the bank. You can try again or choose another payment method.、The payment was not completed. You can try again or choose another payment method. 或 Montonio could not complete the payment. Please try again or choose another payment method. 在 OpenCart 4 上，这些消息显示在结账页面上方。购物车会被保留。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则为结账保留一个订单，并通过新的 Montonio 付款对同一订单再次付款。在创建新付款之前，扩展会向 Montonio 查询同一购物车之前的尝试。如果该尝试已付款，则确认该付款，客户将进入成功页面，不会再进行第二次付款。
OpenCart 4 会在显示订单成功页面之前，将订单保留在结账流程中。若该订单在此期间未付款即被关闭（例如您取消了它），客户会被送回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，从 Montonio 返回时同样如此；下一次点击 Confirm Order 将为新订单付款。在 OpenCart 3 上，此类订单返回时会显示成功页面，并注明付款未完成。若结账的订单已经下单且购物车此后有变化，提示为：Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. 购物车的任何变化（包括数量变化）都视为需要单独付款的新购物车。已付款后又被取消或退款的订单不再占用该购物车。
如果 Montonio 无法启动付款，客户会停留在 Confirm Order 步骤，并在按钮上方看到一条简短提示，例如 Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. 技术原因会写入日志。
该扩展仅接受银行付款（付款发起）。它不支持银行卡付款、BLIK、Apple Pay 或 Google Pay、Pay Later 或分期融资、Montonio 配送、订阅、已保存的付款方式，也不支持在您自己的网站上选择银行。
订单与退款
订单状态
无状态（缺失订单）：客户已被转到 Montonio 但未付款，或 Montonio 报告付款待处理，或付款被取消或未完成。在 Sales > Orders 中，此类订单仅在 Order Status 筛选器设置为 Missing Orders 时显示。
Order Status After Payment（默认 处理中）：Montonio 已确认付款（PAID），且金额和货币与订单完全一致。备注中会显示银行、Montonio 订单 UUID、金额和环境。
Payment On Hold Status（默认 待处理）：银行尚未确认付款（AUTHORIZED）；当 Montonio 报告 PAID 时，订单将转为 Order Status After Payment。当 Montonio 报告的金额或货币与订单总额不符时、当商店处于正式模式时收到沙盒付款（未收到真实款项）时，或当付款在订单已被设置为其他状态（例如已取消）之后才到达时，订单也会被置于暂停状态。备注会对此作出说明。请在 Montonio Partner System 中检查该付款，然后履行订单或退款。
Payment Failed Status（默认 失败）：银行拒绝了一笔已被暂存为已授权的付款。只有订单的最近一次付款尝试才能改变此状态。
Refunded Status（默认 已退款）：付款已通过该扩展全额退款。
已付款或已退款的订单不会因后续通知而被重新打开。如果已付款的订单又收到第二笔付款，订单不会被更改。备注会提醒您在 Montonio Partner System 中对第二笔付款进行退款。
备注是订单 History 中的条目，客户看不到。
VibeFox Montonio Payment 选项卡
在 Sales > Orders 中，打开一笔通过 Montonio 付款的订单。在订单页面底部，紧挨 History 和 Additional 的位置，VibeFox Montonio Payment 选项卡会列出该订单的付款尝试，包括日期、Montonio order UUID（测试付款会带有 Sandbox 标签）、金额、银行、Montonio status 和结果。下方显示 Paid / refunded 金额、退款表单、退款历史以及该订单的 Montonio notes。该选项卡对有权访问该扩展的用户可见。
退款
在 VibeFox Montonio Payment 选项卡中输入金额（会自动填入尚未退款的金额），可选填写原因（仅保存在订单备注中），然后点击 Refund via Montonio。确认提示 通过 Montonio 退还此金额？此操作无法撤销。 支持全额退款和部分退款。您需要拥有修改该扩展的权限（在 System > Users > User Groups 中设置）。退款金额以 Montonio 实际扣款的金额为上限，因此在金额不一致的情况下，您最多只能退还客户实际支付的金额，而不是订单总额。退款会发送到付款所在的环境（沙盒或正式），因此必须设置该环境的密钥。如果 Montonio 不接受退款，选项卡会显示错误，且不会记录任何退款。已发送的退款会连同其状态和 Montonio 退款 ID 一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态的效果相同。部分退款不会更改状态。只有在 Montonio 报告付款已完成后，退款才可用。
Montonio 之后会通过通知确认或拒绝每笔退款。确认结果会添加到备注中。如果 Montonio 拒绝了退款，备注会说明款项未退还给客户；请在 Montonio Partner System 中核实，并在 OpenCart 中更正退款。
Sales > Returns 中的商品退货不会通过 Montonio 退还款项。在 Montonio Partner System 中完成的退款，会在 Montonio 报告后添加到备注中。订单状态不会自动更改；如有需要，请手动更新。
许可证密钥
该扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Montonio Payment 是 Extensions > Extensions > Payments > VibeFox Montonio Payment > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方是 Product: opencart-payment-montonio 一行，以及打开您的 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。如果无法连接许可证服务器，扩展将基于最后已知的状态继续运行。
一个密钥只能用于一个域名。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向客户显示 Montonio。如果仍然发起了付款，客户会看到 This payment method is not available. Please choose another one. 以同一浏览器登录管理后台的管理员用户，仍会在商店中看到该付款方式，并标记为 (unlicensed — visible to admins only)，这样您可以在购买密钥之前设置和测试该扩展。在 OpenCart 4 上没有此预览：商店无法看到管理员的登录状态，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，管理后台的 Dashboard 上会出现一条提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也仍然可用。
当许可证过期时，扩展仍会继续工作，但更新和支持需要续期。打开管理后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：在输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
Montonio 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否开启，以及当前环境的两个密钥是否都已设置：沙盒模式下为 Sandbox access key 和 Sandbox secret key，正式模式下为 Live access key 和 Live secret key。缺少密钥时，设置页面会显示警告。客户必须使用 EUR 或 PLN 付款（即商店中选择的货币）。另外，请检查付款地址是否位于所选的 Geo Zone 内，以及订单是否达到设置中的 Total。
付款已完成，但订单仍无状态：通知未能到达您的商店。请检查商店是否可以从互联网访问，以及设置中的密钥是否属于该付款所在的环境。当客户付款后返回商店、点击 Check again 以及尝试再次支付同一购物车时，订单也会获得状态。
通知返回 Invalid token：令牌的签名、有效期或访问密钥不匹配。请检查访问密钥和密钥是否复制正确，是否属于正确的环境，以及服务器时间是否正确。使用另一环境密钥签名的令牌同样会被拒绝。
通知返回 Payment does not belong to this order：该付款不是由本商店为此订单创建的。当两个商店使用同一个 Montonio 账户和相同的订单号时，就会出现这种情况。
通知返回 Gateway not configured：未设置任何 Montonio 密钥，或缺少该付款所在环境的密钥。请输入密钥；Montonio 会重新发送通知。
通知返回 Temporarily unavailable：购物车在同一时刻正被另一个请求确认，或无法设置订单状态。Montonio 会重新发送通知。请查看 Log 字段以了解原因。
客户在 Confirm Order 之后看到错误：请查看扩展页面上的 Log 字段。This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不匹配，或付款方式在此期间已被关闭：客户需要重新加载结账页面。This payment method is temporarily unavailable. Please choose another payment method. 通常表示密钥错误或缺失。Montonio could not start the payment. Please check your order details or choose another payment method. 表示 Montonio 拒绝了付款数据；日志中会有原因。
订单在付款后处于暂停状态：请阅读 VibeFox Montonio Payment 选项卡中的备注（参见订单状态），然后履行订单或为付款退款。
沙盒付款无法确认正式订单：当商店处于正式模式时，沙盒付款永远不会确认订单；订单会被改为暂停状态。请将 Sandbox mode 切换到您想要的环境，并使用该环境的密钥。
选项卡中没有退款表单：选项卡会说明原因：付款尚未确认、已全额退款，或您的用户组没有修改该扩展的权限。
退款失败，提示与环境有关：付款是在沙盒或正式环境中进行的，而该环境的密钥未设置。请输入密钥后重试。The order is being updated by a payment notification, try again in a moment. 表示同一订单的通知正在处理中。
对于开发人员：扩展会触发 OpenCart 事件 wc_mnt_supported_currencies、wc_mnt_order_data 和 wc_mnt_locale，以更改支持的货币、付款数据以及 Montonio 页面的语言。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Montonio Payment 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态（重新安装时恢复为默认值）。该扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上还包括其事件以及在维护模式下允许通知通过的启动操作）。如果开启了 Delete data，其余网关设置（标题、描述、沙盒模式、密钥、调试日志）和日志也会被删除。如果关闭，它们会被保留，以便日后重新安装时使用。Montonio 的付款和退款记录始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 上，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Montonio Payment 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
Montonio 是其各自所有者的商标。本扩展与 Montonio 无关联，也未获得 Montonio 的认可。