VibeFox MultiSafepay for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块会拒绝在较旧的 PHP 版本上安装。
货币：购物车货币必须是 MultiSafepay 接受的货币，例如 EUR、USD、GBP、PLN、CHF、SEK、DKK 或 NOK。对于其他货币，结账时不会显示该付款方式。
MultiSafepay 账户：您需要在 MultiSafepay Control 中获取您网站的 API 密钥。测试账户和正式账户的密钥不同。除此之外，无需在 MultiSafepay 中进行任何设置：每笔付款都会附带通知地址。
公开网站：MultiSafepay 必须能够访问您的店铺以发送通知。否则，顾客从 MultiSafepay 返回时仍会创建订单。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox MultiSafepay Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 粘贴来自 MultiSafepay Control 的测试和/或正式 API 密钥（参见配置）。
5. 开启 Enable/Disable 并点击 Save。在开启 Test mode 的情况下测试付款，然后关闭它以接受真实付款。
安装时，模块会创建订单状态 MultiSafepay payment on hold。PrestaShop 会为所有货币、国家/地区和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure。每个部分都有自己的 Save 按钮，该按钮会保存整个页面。在字段上方，页面会在测试模式开启时显示 Test mode: new payments use the MultiSafepay test environment (no real payments).，并在当前模式没有 API 密钥时发出警告（此时该付款方式不会在结账时显示），以及在 MultiSafepay 不接受您店铺默认货币时发出警告。没有 Title 时，页面无法保存。
结账
Enable/Disable：Enable MultiSafepay 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：MultiSafepay。必填。
Description：结账时显示在付款方式下方的文字。默认：Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.
API 密钥
API 密钥位于 MultiSafepay Control > Manage settings > Website settings。该部分链接到测试账户（testmerchant.multisafepay.com）和正式账户（merchant.multisafepay.com）。两者的密钥不同。测试模式仅使用测试密钥，正式模式仅使用正式密钥。
Test mode：Use the MultiSafepay test environment (no real payments). 同时切换 API 地址和 API 密钥。已完成的付款在状态查询和退款时仍使用其原始环境。默认：开启。开启时，顾客会在付款方式下方看到 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 saved keys：勾选一个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。
通知
无需配置。Notification URL 字段显示每笔付款时发送给 MultiSafepay 的地址。启用友好网址时，其形式如 https://your-shop/module/wcp_multisafepay_gateway/webhook，可能包含语言代码，例如 /en/。通知只会告诉模块哪笔付款发生了变化：状态、金额和货币始终会在创建或修改订单前，使用您的 API 密钥从 MultiSafepay API 读取。非在您店铺中发起的付款的通知会被忽略。店铺处于维护模式时通知仍然有效，且不受店铺国家限制的影响。
订单
Order status after payment：已付款订单的状态。状态会一次性设置，只进行一次状态变更并发送一封顾客邮件。
高级
Debug log：Log API calls and notifications 会记录到模块文件夹中的 logs/mspg_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。API 密钥和顾客数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启时，卸载模块会删除设置和日志。订单的 MultiSafepay 付款数据和订单状态始终保留，因此旧订单的退款仍然可以进行。停用模块从不删除任何内容。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为带有 MultiSafepay 标志的 MultiSafepay）并确认。模块会以购物车货币为购物车总额创建 MultiSafepay 付款，并将顾客引导至 MultiSafepay 付款页面。顾客在那里选择您 MultiSafepay 账户中启用的任意付款方式并付款。顾客的账单地址、电子邮件、电话和语言会传递给 MultiSafepay，付款显示为 Order #、购物车编号和您的店铺名称。此时尚不存在订单。
付款后，顾客返回您的店铺。只有在 MultiSafepay 确认后，订单才会被标记为已付款：通过通知，或在顾客返回时通过 MultiSafepay API 检查。随后订单被创建，顾客会看到标准订单确认页面，并显示 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.
在为同一购物车创建新付款之前，模块会在 MultiSafepay 上检查之前的付款。如果该付款已经完成或正在处理，则直接创建订单，而不是新建付款。如果仍处于开放状态且金额相同，则复用同一付款页面。如果金额已更改，则在 MultiSafepay 上取消旧付款，使其无法再被支付。
如果 MultiSafepay 无法发起付款，顾客会停留在结账页面并看到简短提示，例如 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 付款方式提供单独的 PrestaShop 付款选项，没有嵌入式银行卡输入框，没有 Apple Pay 或 Google Pay 快捷支付按钮，不支持订阅、定期付款或保存的银行卡，也无法在 PrestaShop 中执行扣款或撤销。由于不发送购物车数据，对于这些订单，MultiSafepay 不提供需要此类数据的先买后付方式（例如 Klarna、in3 或 Riverty）。
订单与退款
订单状态
尚无订单：顾客已被引导至 MultiSafepay 但尚未付款，或 MultiSafepay 尚未确认付款。目前只存在购物车。
Payment accepted 或 Delivered：MultiSafepay 已确认付款（已完成或已发货）。状态遵循 Order status after payment。付款以 MultiSafepay 订单 ID 作为交易 ID 记录，备注中显示付款、付款方式和环境。
MultiSafepay payment on hold before payment：付款尚未结清（正在 MultiSafepay 审核中）或已预授权（已授权）。请在 MultiSafepay Control 中对预授权付款进行扣款以收到款项。当 MultiSafepay 报告付款已完成时，订单会自动转为已付款状态。
MultiSafepay payment on hold after payment：MultiSafepay 确认的金额或货币与购物车总额不同（例如付款开始后购物车被修改），模块处于正式模式时完成了测试付款（未收到实际资金，未记录付款），或付款是在订单被取消之后完成的。备注会说明原因。请在 MultiSafepay Control 中检查该交易，然后发货或退款。
MultiSafepay payment on hold after a chargeback：MultiSafepay 报告某笔已付款订单发生拒付：资金已从您的账户中被扣回。
Payment error：尚未结清或已预授权的付款随后被拒绝、取消、过期或作废。
Refunded：付款已通过模块全额退款。
已付款或已退款的订单绝不会因迟到的通知而重新打开。如果已付款的购物车又完成了第二笔付款，订单不会被更改。备注会提醒您在 MultiSafepay Control 中退还重复付款。
MultiSafepay 付款区块
订单页面显示 MultiSafepay payment 区块，包括 MultiSafepay 订单 ID、付款方式、状态、已付金额和已退金额、测试付款的 Test mode 标识、退款记录以及订单的 MultiSafepay notes。
退款
在 MultiSafepay payment 区块中输入金额（未退款的金额会自动填入），可选填原因，然后点击 Refund via MultiSafepay。确认提问 Refund this amount through MultiSafepay? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面。退款以 MultiSafepay 收取的金额和货币进行，因此在金额不一致后，您最多可以退还顾客实际支付的金额，而不是订单总额。退款会发送到付款时所处的环境（测试或正式），因此必须设置该环境的 API 密钥。如果 MultiSafepay 不接受退款，区块会显示 MultiSafepay refund failed: 以及 MultiSafepay 的错误信息，且不会记录任何退款。成功的退款会添加到退款记录和备注中，并附上 MultiSafepay 退款 ID。全额退款会将订单设为 Refunded。部分退款不会更改状态。MultiSafepay 报告付款后即可进行退款。
模块不会创建退款单（credit slip）。订单页面标准的 PrestaShop 退款按钮不会通过 MultiSafepay 退回资金。
在 MultiSafepay Control 中进行的退款，在 MultiSafepay 报告后会添加到备注中。订单状态和退款单不会自动更改。如有需要，请手动更新。
许可证密钥
本模块需要一个来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox MultiSafepay Gateway 许可证区块是 Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥粘贴到 License key 字段中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从此店铺中移除密钥）。其下方有 Product: presta-payment-multisafepay 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有具有该模块 Configure 权限的员工才能更改密钥。该区块的文本遵循后台语言（包括英语和俄语）。
如果密钥未被接受，该区块会说明原因，例如 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. PrestaShop 前台无法识别您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常进行。
许可证过期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天内每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时未显示 MultiSafepay：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否有 API 密钥（测试模式为 Test API key，正式模式为 Live API key），以及购物车货币是否被 MultiSafepay 接受。当密钥缺失或店铺货币不被接受时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车货币、顾客所在国家和顾客所在群组。
付款已完成，但未创建订单：通知未能到达您的店铺。请检查店铺是否可从互联网访问，以及付款所在环境的 API 密钥是否已设置，因为模块是通过 MultiSafepay API 读取状态的。如果无法访问 API 或缺少密钥，通知会回复 ERROR，MultiSafepay 会重试。顾客返回店铺时，以及顾客再次尝试支付同一购物车时，也会创建订单。
通知回复 Invalid request：请求中没有有效的交易 ID。来自 MultiSafepay 的通知始终包含交易 ID。
顾客在选择 MultiSafepay 时看到错误：开启 Debug log，并查看模块页面上的 Log 字段。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 拒绝了该金额或货币。
订单处于 MultiSafepay payment on hold 状态：请阅读 MultiSafepay payment 区块中的备注。付款可能尚未结清或已预授权，付款金额或货币可能与购物车不符，测试付款可能在正式模式下到达，付款可能是在订单取消后到达的，或者发生了拒付。请在 MultiSafepay Control 中检查该交易。
测试付款不会确认正式订单：模块处于正式模式时，测试付款永远不会支付订单；订单会改为保留状态。切换到正式模式后，之前的测试付款仍会使用测试密钥进行检查和退款。
退款因环境相关消息而失败：付款是在测试或正式环境中完成的，而该环境的 API 密钥未设置。请输入该密钥后重试。
卸载
进入 Modules > Module Manager，打开 VibeFox MultiSafepay Gateway 旁边的菜单，然后选择 Uninstall。此模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单的 MultiSafepay 付款数据和订单状态 MultiSafepay payment on hold 始终保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
MultiSafepay 是其各自所有者的商标。本模块与 MultiSafepay 无关联，也未获得 MultiSafepay 的认可或背书。