VibeFox Mollie for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝在较旧的 PHP 版本上安装。
商店币种：购物车币种必须是 Mollie 支持的币种之一：AED、AUD、BGN、BRL、CAD、CHF、CZK、DKK、EUR、GBP、HKD、HUF、ILS、ISK、JPY、MXN、MYR、NOK、NZD、PHP、PLN、RON、SEK、SGD、THB、TWD、USD、ZAR。对于其他币种，结账时会隐藏该付款选项。Mollie 提供哪些付款方式取决于币种和您的账户。
商店的互联网访问：Mollie 会向您的商店发送 Webhook，因此网站必须能被互联网访问。即使没有 Webhook，顾客从 Mollie 返回时也会创建订单。
Mollie 账户：您需要 Mollie Dashboard > Developers > API keys 中的 API 密钥。测试密钥以 test_ 开头，正式密钥以 live_ 开头。不需要其他密钥或机密信息。付款方式需在您的 Mollie 账户中启用。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox Mollie Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 输入您的测试和正式 API 密钥（参见配置）。无需在 Mollie 中设置任何 Webhook。
5. 开启 Enable/Disable 并点击 Save。在完成一次测试付款之前，请保持 Test Mode 开启，然后再关闭。
安装时，模块会创建两个订单状态：Awaiting Mollie payment 和 Mollie payment on hold。PrestaShop 会为所有币种、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中对其加以限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Mollie Gateway > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，如果已启用 Mollie 但当前模式的 API 密钥为空，或者 Mollie 不支持商店的默认币种，页面会发出警告。在这两种情况下，结账时都会隐藏该付款选项。
保存时，如果 API 密钥不是以 test_ 或 live_ 开头并且后面没有至少 30 个字母和数字，则不会保存：会显示错误，并保留之前保存的密钥。
结账
Enable/Disable：Enable Mollie Gateway 用于开启或关闭该付款选项。默认：off。
Title：结账时显示给顾客的付款方式标题。它也是订单中保存的付款方式名称。默认：Mollie。必填。
Description：结账时显示给顾客的付款方式描述。默认：Pay securely via Mollie。
API 密钥
您可以在 Mollie Dashboard 的 Developers > API keys 下找到 API 密钥；该部分提供了该页面的链接。测试密钥和正式密钥是分开的。
Test Mode：新付款使用测试 API 密钥。不会处理任何真实付款。在 Mollie 的测试结账页面上，您可以选择付款结果。顾客会在付款选项下方看到 Test mode: no real payment will be made. 以另一模式完成的付款，在状态检查和退款时仍使用其所属模式的密钥。默认：on。
Test API Key：您的 Mollie 测试 API 密钥（以 test_ 开头）。
Live API Key：您的 Mollie 正式 API 密钥（以 live_ 开头）。
已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved keys：勾选某个密钥并点击 Save 即可将其删除。字段留空则保留已保存的值。
Webhook：显示 Webhook URL。无需进行任何设置：模块会在每笔付款时将此 URL 发送给 Mollie。使用友好 URL 时，它类似于 https://your-shop/module/wcp_mollie_gateway/webhook，前面可能带有语言代码。该 URL 必须能被互联网访问，否则只有在顾客从 Mollie 返回时才会创建订单。
订单
Order Status After Payment：付款成功后设置的订单状态。状态在一步内设置完成。
银行转账订单会在 Awaiting Mollie payment 中等待。已授权付款以及金额或币种不一致的订单会进入 Mollie payment on hold。
高级
Logging：将 API 调用和 Webhook 写入模块文件夹中的 logs/molg_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。API 密钥和顾客数据绝不会被记录。默认：off。
Log：显示日志的大小和最新条目。点击 Clear log 可将其清空。
Delete Data on Uninstall：开启时，卸载模块会删除模块设置及其日志。订单中保存的 Mollie 付款 ID、退款记录以及模块的订单状态始终会被保留。默认：off。
结账
在付款步骤，顾客选择付款选项（默认为 Mollie）并确认。模块会以购物车币种为购物车总额（JPY 和 ISK 无小数位）创建一笔 Mollie 付款，描述为 Order # 和购物车编号，并将顾客转到 Mollie 托管结账页面。在那里，顾客会从您 Mollie 账户中已启用的付款方式中选择一种并付款。此时尚不存在订单。
Mollie 的 Webhook 不带签名，只包含付款 ID。因此，模块从不单独信任 Webhook：它只接受自己创建的付款 ID，使用付款所在模式的密钥从 Mollie API 读取付款信息，检查该付款是否属于购物车，并将已付金额和币种与购物车总额进行比较。只有 Mollie 以这种方式确认后，订单才会被标记为已付款。模块会处理以下 Mollie 付款状态：
顾客返回时，模块会以相同方式通过 Mollie API 核对购物车的最新付款。已付款的付款会进入标准订单确认页面，并显示 Your payment with Mollie has been received. 对于银行转账，页面显示 Your order will be processed as soon as Mollie receives your bank transfer. 如果订单处于保留状态，页面显示 We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. 如果现有订单的付款失败或订单已取消，页面显示 Your Mollie payment was not completed. Please contact us about this order.
如果付款已取消、失败、过期或未完成，顾客会回到结账页面，并看到类似这样的提示：You cancelled the Mollie payment. You can try again or choose another payment method. 或 The Mollie payment has expired. Please try again or choose another payment method. 购物车会被保留。如果无法连接 Mollie 或 Mollie 尚未作出决定，则会出现 Payment confirmation 页面，请顾客不要重复付款，并提供 Check again 按钮；Webhook 一到达就会创建订单。
顾客再次付款时，会复用相同金额且仍处于打开状态的 Mollie 付款，而不是创建第二笔可付款的付款。如果购物车总额已变更，则在 Mollie 允许的情况下，旧的打开付款会在 Mollie 中被取消。如果旧付款在此期间已完成，则直接创建订单，无需新的付款。
如果 Mollie 无法启动付款，顾客会停留在结账页面并看到简短提示，例如 The payment provider could not be reached. Please try again in a moment.、This payment method is temporarily unavailable. Please choose another payment method.（API 密钥错误）或 Mollie cannot accept a payment of this amount or currency. Please choose another payment method. 技术原因会写入日志。
即使商店处于维护模式，Webhook 也能正常工作，并且不受商店国家限制的影响。
顾客在 Mollie 页面而不是您的结账页面中选择 Mollie 付款方式。模块不支持订阅或定期付款、已保存的银行卡或授权书（mandate）、您网站上的银行卡输入框、Apple Pay 或 PayPal 快捷按钮，也不使用 Orders API，因此对于这些付款，Mollie 不会提供需要订单行的付款方式（例如某些 Klarna、Billie 或 in3 变体）。已授权的付款需在 Mollie Dashboard 中扣款或撤销，而不是在 PrestaShop 中操作。
订单与退款
订单状态
尚无订单：顾客已被转到 Mollie 但尚未付款，或 Mollie 尚未确认付款。此时只存在购物车。
Payment accepted 或 Delivered：付款已确认。状态跟随 Order Status After Payment。付款会以 Mollie 付款 ID（tr_...）作为交易 ID 记录，并且备注中会显示 Mollie 付款、付款方式和模式。
Awaiting Mollie payment：顾客在 Mollie 页面中选择了银行转账。Mollie 收到款项后，订单会转为已付款状态。
Mollie payment on hold：已授权付款等待扣款；Mollie 报告了拒付；已付金额或币种与购物车不一致（例如付款开始后购物车被修改）；商店处于正式模式时完成了测试付款（未收到款项）；或者付款是在订单取消后到达的。备注会说明原因。请在 Mollie Dashboard 中核对付款，然后处理订单或退还付款。
Payment error：现有订单的银行转账或授权失败、过期或被取消。已付款的订单绝不会被更改。
Refunded：付款已通过模块全额退款。
如果同一购物车的第二笔付款已完成，订单不会改变。备注会提示您在 Mollie Dashboard 中退还这笔重复付款。
Mollie payment 区块
订单页面会显示一个 Mollie payment 区块，其中包括 Mollie 付款 ID、付款方式、付款状态、已付金额和已退款金额、测试付款的 Test mode 标记、退款记录，以及订单的 Mollie notes。备注仅在后台可见。
退款
在 Mollie payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Mollie。确认提示 Refund this amount through Mollie? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面。退款按 Mollie 实际收取的金额和币种进行，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会针对实际支付订单的那笔付款进行，并使用该付款所在模式的 API 密钥，因此必须已设置该模式的密钥。如果 Mollie 拒绝退款，该区块会显示 Mollie 的错误信息，并且不会记录任何退款。成功的退款会添加到退款记录和备注中，并附带 Mollie 退款 ID。全额退款会将订单设为 Refunded。部分退款不会改变状态。只有在 Mollie 报告付款已完成后，才能进行退款。
模块不会创建退款单（credit slips）。订单页面上 PrestaShop 的标准退款按钮不会通过 Mollie 退款。在 Mollie Dashboard 中创建的退款不会显示在订单上；拒付会添加备注。
许可证密钥
模块需要使用 vibefox.net 提供的 VibeFox 许可证密钥。License — VibeFox Mollie Gateway 许可证区块位于 Modules > Module Manager > VibeFox Mollie Gateway > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中删除该密钥）。其下方有一行 Product: presta-payment-mollie 和链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文本遵循后台语言（包括英文和俄文）。
如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或带日期的 License expired on。商店地址变更后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块会继续使用最后一次已知的状态运行。
一个密钥只能用于一个域名：即主商店的域名，在多店铺设置中同样如此。从商店中删除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。
没有有效的密钥时，结账时不会向顾客显示 Mollie。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会出现提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。
许可证过期时，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
Mollie 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否有 API 密钥：测试模式需要 Test API Key，正式模式需要 Live API Key。请检查购物车币种是否受 Mollie 支持。如果缺少密钥或商店币种不受支持，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车币种、顾客所在国家和顾客所在客户组。
付款已完成，但未创建订单：Webhook 无法访问您的商店。Webhook 中显示的 URL 必须能被互联网访问（不能有基本身份验证或阻止访问的防火墙）。顾客付款后返回商店，或点击 Check again 时，也会创建订单。
Webhook 返回 Unknown payment.：该付款不是由本商店创建的，或者 Mollie 无法用其模式的 API 密钥识别该付款，例如来自其他 Mollie 账户的付款。
Webhook 返回 Payment ID mismatch.：该付款不属于其创建时所对应的购物车。不会做任何更改。
Webhook 返回 Failed to fetch payment.：无法连接 Mollie API，或者付款所在模式的 API 密钥未设置。Mollie 之后会重试 Webhook。
Webhook 返回 Temporarily unavailable.：购物车在同一时刻正被另一个请求处理，或者无法创建订单（例如模块已禁用）。Mollie 会重试 Webhook。请开启 Logging 查看原因。
Webhook URL 在浏览器中显示 Method not allowed.：这是正常现象。该 URL 只接受来自 Mollie 的请求。
API 密钥未能保存：密钥必须以 test_ 或 live_ 开头，后面至少跟 30 个字母和数字。请从 Mollie Dashboard 重新复制。
顾客在选择 Mollie 时看到错误：请查看模块页面上的 Log 字段。它会显示 HTTP 代码和 Mollie 的消息。401 表示 API 密钥错误；422 表示请求中的某个字段有问题，例如 Mollie 不接受的金额或币种。
订单处于 Mollie payment on hold：请阅读订单备注（参见订单状态），然后处理订单或退还付款。
退款失败并提示与模式有关的消息：付款是在测试或正式模式下完成的，而该模式的 API 密钥未设置。请输入该密钥后重试。
其他币种或付款数据：开发人员可以使用 actionWcpMollieSupportedCurrencies 钩子更改币种列表，并使用 actionWcpMolliePaymentData 钩子更改付款请求。
卸载
进入 Modules > Module Manager，打开 VibeFox Mollie Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Mollie 付款 ID 和退款记录，以及订单状态 Awaiting Mollie payment 和 Mollie payment on hold 始终会被保留，因此之前付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Mollie 是其各自所有者的商标。本模块与 Mollie 无关联，也未获得 Mollie 的认可或背书。