VibeFox MultiSafepay for OpenCart — 帮助
系统要求
OpenCart: 3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。
PHP: 8.0 或更高版本。
货币: 结账货币必须是 MultiSafepay 支持的货币，例如 EUR、USD、GBP、PLN、CHF、SEK、DKK 或 NOK。对于其他货币，结账时将隐藏该付款方式。
MultiSafepay 账户: 您需要 MultiSafepay Control 中网站的 API 密钥。测试账户和正式账户的密钥不同。除此之外，MultiSafepay 中无需进行其他设置：每次付款时都会发送通知地址。
公网站点: MultiSafepay 必须能够访问您的店铺，才能发送通知。否则，订单在顾客从 MultiSafepay 返回时仍会获得状态。
VibeFox 许可证密钥: 在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
下载文件是一个 zip 压缩包，包含适用于两个 OpenCart 版本的安装包。请将其解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_multisafepay_gateway-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_multisafepay_gateway.ocmod.zip。只需安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。
OpenCart 3
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_multisafepay_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将本安装包中 upload 文件夹的内容复制到店铺的根目录。
2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox MultiSafepay Gateway，点击 Install（绿色 + 按钮）。您的管理员用户需要具有修改支付扩展列表的权限。
3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key 中，然后点击 Activate（参见 License key）。
4. 粘贴来自 MultiSafepay Control 的测试和/或正式 API 密钥（参见 Configuration）。
5. 开启 Enable/Disable，然后点击 Save。在开启 Test mode 的情况下测试一笔付款，然后关闭它以接受真实付款。
OpenCart 4
1. 在管理后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_multisafepay_gateway.ocmod.zip。请勿重命名该文件：OpenCart 4 通过文件名获取扩展代码，重命名后的安装包将无法使用。
2. 该安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。
3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox MultiSafepay Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。
4. 按 OpenCart 3 第 3 至 5 步的方法输入许可证密钥和 API 密钥。两个版本的设置页面及其字段相同。只有通知 URL 不同（参见 Notification URL）。
新安装时，该付款方式默认关闭，测试模式默认开启。
配置
所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox MultiSafepay Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会在测试模式开启时显示 Test mode: new payments use the MultiSafepay test environment (no real payments).；当付款方式已启用但当前模式没有 API 密钥时发出警告（此时该付款方式不会在结账时显示）；当 MultiSafepay 不接受店铺默认货币时也会发出警告。如果没有修改扩展的权限，页面会显示设置，但无法保存。
保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数（允许负数），Total 必须为大于或等于 0 的数字，并且地理区域和订单状态必须存在；否则不会保存任何内容，页面会指出问题。如果在没有当前模式 API 密钥的情况下启用了该付款方式，设置会带着警告保存。
Checkout
Enable/Disable: Enable MultiSafepay 用于开启或关闭该付款方式。默认：关闭。
Title: 顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：MultiSafepay。必填，最多 128 个字符。
Description: 在 Confirm Order 步骤中、确认按钮上方显示给顾客的文字。默认：Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.
Sort Order: MultiSafepay 在结账付款方式中的位置。留空或输入整数。
Geo Zone: 仅对所选地理区域内的付款地址提供 MultiSafepay。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。
Total: 订单须达到的、以店铺默认货币计算的总金额，达到后才会提供 MultiSafepay。留空则对任何金额都提供 MultiSafepay。
API 密钥
API 密钥位于 MultiSafepay Control > Manage settings > Website settings。该部分提供测试账户（testmerchant.multisafepay.com）和正式账户（merchant.multisafepay.com）的链接。两者的密钥不同。测试模式只使用测试密钥，正式模式只使用正式密钥。
Test mode: 使用 MultiSafepay 测试环境（不产生真实付款）。它会同时切换 API 地址和 API 密钥。已完成的付款在进行状态检查和退款时，仍会使用其付款时所在的环境。默认：开启。开启期间，顾客在 Confirm Order 步骤会看到 Test mode: no real payment will be made.
Test API key: 您的 MultiSafepay 测试账户的 API 密钥。
Live API key: 您的 MultiSafepay 正式账户的 API 密钥。
已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。
通知
无需进行任何配置。Notification URL 字段显示每次付款时发送给 MultiSafepay 的地址。在 OpenCart 3 中，其格式类似 https://your-store/index.php?route=extension/payment/wcp_multisafepay_gateway/webhook；在 OpenCart 4 中，格式类似 https://your-store/index.php?route=extension/wcp_multisafepay_gateway/payment/wcp_multisafepay_gateway.webhook。该地址由您的 OpenCart 安装的店铺前台地址生成。通知只会告诉扩展哪笔付款发生了变化：状态、金额和货币始终在修改订单之前，使用该付款所在环境的 API 密钥，从 MultiSafepay API 读取。对于并非在您的店铺中发起的付款，通知会被忽略。即使店铺处于维护模式，通知也能正常工作：OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展为此添加了一个启动操作（startup action），该操作同样使顾客能够从 MultiSafepay 返回。
订单
OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 MultiSafepay 报告付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。
Order status after payment: 已付款订单的状态。默认：处理中。选择 Complete 可立即完成已付款的订单。
MultiSafepay payment on hold status: 该付款需要您关注（参见 Order statuses）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。
Payment error status: 未结算或已预授权的付款随后被拒绝、过期或取消。默认：失败。
Refunded status: 在订单页面对付款进行全额退款后设置。默认：已退款。
高级
Debug log: 将 API 调用和通知记录到 OpenCart 日志文件夹（storage/logs）中的 mspg_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。API 密钥和顾客数据永远不会被记录。默认：关闭。
Log: 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall: 开启时，卸载扩展会删除网关设置和日志。订单的 MultiSafepay 付款数据始终保留，以便旧订单仍可退款。禁用扩展不会删除任何内容。默认：关闭。
导入 / 导出
Export: Download JSON 将设置保存为 JSON 文件。API 密钥不会被导出。
Import: 粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 API 密钥会被保留。
结账
在 Payment Method 步骤中，顾客选择付款方式（默认为 MultiSafepay）。在 Confirm Order 步骤中，顾客会看到您的描述以及说明 You will be redirected to MultiSafepay to choose a payment method and pay. OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一笔 MultiSafepay 付款，并将顾客带到 MultiSafepay 付款页面。顾客在那里选择您 MultiSafepay 账户中启用的任一付款方式并完成付款。在 OpenCart 4 中，顾客通过付款方式选项区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。顾客的账单地址、电子邮件、电话和语言会传递给 MultiSafepay，付款显示为 Order #、订单号以及您的店铺名称。
付款后，顾客返回您的店铺。只有在 MultiSafepay 确认后，订单才会被标记为已付款：通过通知确认，或在顾客返回时通过 MultiSafepay API 检查确认。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面，显示 Your payment with MultiSafepay has been received. 对于处于暂停状态的订单，页面会显示 We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. 如果付款稍后失败，页面会显示 Your MultiSafepay payment was not completed. Please contact us about this order. 如果顾客返回时 MultiSafepay 尚未确认付款（例如正在等待银行转账），Payment confirmation 页面会显示相同的“正在确认”文字以及 Check again 按钮；一旦 MultiSafepay 报告付款，通知就会设置订单状态。
如果顾客在 MultiSafepay 页面上取消，或付款被拒绝或过期，顾客会返回结账页面，购物车保持不变，并看到以下消息之一：The MultiSafepay payment was cancelled. You can try again or choose another payment method.、The payment was declined. Please try again or choose another payment method. 或 The payment session has expired. Please try again. 在 OpenCart 4 中，这些消息会显示在结账页面上方。
OpenCart 3 会在每次显示 Confirm Order 步骤时创建一个新订单，而 OpenCart 4 则为结账保留同一个订单，并对该订单重新付款。在创建新付款之前，扩展会在 MultiSafepay 上检查同一购物车的之前付款。如果其中一笔已付款或正在处理中，则确认该笔付款，顾客将进入成功页面，而不会再次付款。如果该订单的付款仍处于开启状态，且环境、金额和货币相同，则会复用同一付款页面。否则，旧付款会在 MultiSafepay 上被取消，从而无法再付款。
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) was closed by the store. Please confirm the order again to pay with a new order. 如果结账中的订单已下达，且之后购物车发生了变化，提示为 Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. 购物车的任何变化（包括数量变化）都被视为需要单独付款的新购物车。已付款后被取消或退款的订单不再占用该购物车。
如果 MultiSafepay 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息，例如 Could not connect to MultiSafepay. Please try again in a moment. 或 MultiSafepay cannot accept this order amount or currency. Please choose another payment method. 技术原因会写入日志。
该扩展仅提供一个通往 MultiSafepay 页面的付款方式。它不会为每种 MultiSafepay 付款方式分别提供 OpenCart 付款方式，没有嵌入式银行卡输入框，没有 Apple Pay 或 Google Pay 快捷按钮，也不支持订阅、定期付款或保存的银行卡，并且不能在 OpenCart 中进行捕获或作废。不会发送购物车数据，因此需要此类数据的先享后付方式（例如 Klarna、in3 或 Riverty）不会由 MultiSafepay 为这些订单提供。
订单和退款
Order statuses
No status (missing order): 顾客已被转到 MultiSafepay 但尚未付款，MultiSafepay 尚未确认付款，或付款已被取消、拒绝或过期。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时，才会显示此类订单。
Order status after payment (default Processing): MultiSafepay 已按订单的准确金额和货币确认付款（已完成或已发货）。备注中会显示付款、付款方式和环境。
MultiSafepay payment on hold status (default Pending), before payment: 付款尚未结算（正在由 MultiSafepay 审核）或已预授权（已授权）。请在 MultiSafepay Control 中对预授权付款进行捕获，以收到款项。当 MultiSafepay 报告付款已完成时，订单会自动转为 Order status after payment；当付款被拒绝、取消、过期或作废时，则转为 Payment error status。
MultiSafepay payment on hold status, after payment: MultiSafepay 确认的金额或货币与订单总额不同；在扩展处于正式模式时完成了测试付款（未收到真实资金）；或者付款是在订单已被设置为其他状态（例如已取消）之后才完成的。备注会对此进行说明。请在 MultiSafepay Control 中检查该交易，然后处理或退款该订单。
MultiSafepay payment on hold status, after a chargeback: MultiSafepay 报告了已付款订单的付款被拒付（chargeback）：资金已从您的账户中扣回。
Payment error status (default Failed): 未结算或已预授权的付款随后被拒绝、取消、过期或作废。
Refunded status (default Refunded): 该付款已通过扩展全额退款。
已付款或已退款的订单绝不会因迟到的通知而重新打开。如果同一购物车已付款后又完成了第二笔付款，则已付款订单不会被更改。备注会提示您在 MultiSafepay Control 中退还该重复付款。
备注是订单 History 中的条目，顾客看不到。
VibeFox MultiSafepay Gateway 选项卡
在 Sales > Orders 中打开一个通过 MultiSafepay 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox MultiSafepay Gateway 选项卡会显示 MultiSafepay order（测试付款会带有 Test environment 标签）、Method、Status、Paid / refunded 金额、退款表单、退款历史以及该订单的 MultiSafepay notes。该选项卡会显示给有权访问该扩展的用户。
退款
在 VibeFox MultiSafepay Gateway 选项卡中输入 Amount（会预先填入尚未退还的金额），可选填写 Reason (optional)，然后点击 Refund via MultiSafepay。确认提示 Refund this amount through MultiSafepay? This cannot be undone. 支持全额退款和部分退款。您需要有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 MultiSafepay 收取的金额和货币进行，因此在金额不一致之后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所在的环境（测试或正式），因此该环境的 API 密钥必须已设置。如果 MultiSafepay 不接受退款，选项卡会显示 MultiSafepay refund failed: 以及 MultiSafepay 的错误信息，并且不会记录退款。退款成功后，会在退款历史和备注中添加一条记录，并附上 MultiSafepay 退款 ID。全额退款会将订单设为 Refunded status，且不会通知顾客，也不会将商品退回库存，与手动更改状态一样。部分退款不会更改状态。只有在 MultiSafepay 报告付款后，退款才可用。
在 Sales > Returns 中的商品退货不会通过 MultiSafepay 退款。
在 MultiSafepay Control 中进行的退款，会在 MultiSafepay 报告后添加到备注中。订单状态不会自动更改。如有需要，请手动更新。
许可证密钥
该扩展需要一个来自 vibefox.net 的 VibeFox 许可证密钥才能运行。License — VibeFox MultiSafepay Gateway 许可证区块位于 Extensions > Extensions > Payments > VibeFox MultiSafepay Gateway > Edit 的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会显示被遮蔽的密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（再次检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除该密钥）。其下方有一行 Product: opencart-payment-multisafepay，以及打开您 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 账户中释放该名额。
如果没有有效的密钥，结账时不会向顾客显示 MultiSafepay。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户，仍会在店铺中看到该付款方式，并标记为 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中此预览不可用：店铺无法看到管理员是否已登录，因此没有有效密钥时，该付款方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 会出现提醒。点击 × 可将其隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。
许可证过期后，扩展仍会继续运行，但更新和支持需要续期。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。
故障排除
MultiSafepay does not appear at checkout: 检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否设置了 API 密钥：测试模式下为 Test API key，正式模式下为 Live API key。如果缺少密钥，设置页面会显示警告。顾客必须使用 MultiSafepay 支持的货币付款（即店铺中选择的货币）。还需检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。
The payment went through, but the order stays without a status: 通知未能到达您的店铺。请检查店铺是否可以从互联网访问，以及付款所在环境的 API 密钥是否已设置，因为扩展通过 MultiSafepay API 读取状态。如果无法访问 API 或缺少密钥，通知会回复 ERROR，MultiSafepay 将重试。订单也会在顾客返回店铺以及顾客尝试再次支付同一购物车时获得状态。
Notification answers Invalid request: 请求中没有有效的交易 ID。MultiSafepay 的通知始终包含交易 ID。
The customer sees an error after Confirm Order: 开启 Debug log，并查看扩展页面上的 Log 字段。This payment method is not available. 表示结账会话已与订单不再匹配，或期间该付款方式已被关闭：顾客需要重新加载结账页面。This payment method is temporarily unavailable. Please choose another payment method. 通常表示 API 密钥错误或缺失。MultiSafepay cannot accept this order amount or currency. Please choose another payment method. 表示 MultiSafepay 拒绝了该金额或货币。
The customer comes back and sees Payment verification failed.: 返回地址与本店铺的任何付款都不匹配，例如使用了旧的或被修改过的链接。顾客可以从结账页面重新付款。
Order is in the on hold status: 阅读 VibeFox MultiSafepay Gateway 选项卡中的备注。付款可能尚未结算或已预授权，已付金额或货币可能与订单不同，正式模式下可能收到了测试付款，付款可能在订单取消之后到达，或者发生了拒付（chargeback）。请在 MultiSafepay Control 中检查该交易。
Test payments do not confirm a live order: 扩展处于正式模式时，测试付款绝不会支付订单；订单会改为暂停状态。切换到正式模式后，之前的测试付款仍会使用测试密钥进行检查和退款。
No refund form in the tab: 选项卡会说明原因：付款尚未报告、已全额退款，或您的用户组没有修改扩展的权限。
Refund fails with a message about the environment: 付款是在测试或正式环境中进行的，而该环境的 API 密钥未设置。请输入密钥后重试。
面向开发者：扩展会触发 OpenCart 事件 mspg_supported_currencies 和 mspg_order_request，以更改支持的货币以及发送给 MultiSafepay 的付款数据。
卸载
进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox MultiSafepay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件以及在维护模式下放行通知的启动操作，即 startup action）。如果 Delete data on uninstall 已开启，则其余网关设置（标题、描述、测试模式、API 密钥、调试日志）和日志都会被删除。如果未开启，这些内容将被保留，以供日后重新安装使用。MultiSafepay 的付款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。
在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox MultiSafepay Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）删除已上传的安装包。
MultiSafepay 是其各自所有者的商标。本扩展与 MultiSafepay 没有关联，也未获得 MultiSafepay 的认可。