VibeFox Mollie for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。没有 WooCommerce 时，插件无法启用。

PHP：8.0 或更高版本。

店铺币种：须为 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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件的 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_mollie_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Mollie > Manage，或在插件页面中点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 输入您的测试和正式 API 密钥（参见配置）。无需在 Mollie 中配置任何 Webhook。

6. 开启 Enable/Disable。在完成一笔测试付款之前保持 Test Mode 开启，然后取消勾选。

配置

所有设置都在同一页面中：WooCommerce > Settings > Payments > Mollie。在字段上方，若 Mollie 已启用但当前模式的 API 密钥为空，或 Mollie 不支持店铺币种，页面会发出警告。在这两种情况下，该付款方式都会在结账时隐藏。在付款方式列表中，在当前模式具有 API 密钥之前，Mollie 会被标记为需要设置；测试模式开启时则显示 Test mode。

保存时，如果 API 密钥不是以 test_ 或 live_ 开头并后接至少 30 个字母和数字，则不会保存：会显示错误，并保留之前的值。

结账

Enable/Disable：Enable Mollie Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：结账时向顾客显示的付款方式标题。默认：Mollie。

Description：结账时向顾客显示的付款方式描述。默认：Pay securely via Mollie。

API 密钥

您可以在 Mollie Dashboard > Developers > API keys 中找到 API 密钥。无需设置 Webhook：插件会在每笔付款中发送其 Webhook URL。该 URL 显示在本节中，形如 https://your-site/?wc-api=molg_mollie_webhook。它必须能被互联网访问，否则订单只会在顾客从 Mollie 返回时更新。

Test Mode：Enable test mode 会对新付款使用测试 API 密钥。不会处理任何真实付款。在 Mollie 测试付款页面中，您可以选择结果（paid、failed、cancelled、expired）。顾客在结账时会看到 Test mode: no real payment will be made.。在另一模式下完成的付款，在状态检查和退款时仍使用其所属模式的密钥。默认：开启。

Test API Key：您的 Mollie 测试 API 密钥（以 test_ 开头）。

Live API Key：您的 Mollie 正式 API 密钥（以 live_ 开头）。

订单

Order Status After Payment：付款成功后设置的订单状态。状态会一步设置完成，不会再次变更。

高级

Logging：Enable debug logging 会将 API 调用和 Webhook 写入 WooCommerce > Status > Logs，来源为 wcp_mollie_gateway。错误始终会被记录。API 密钥和顾客数据绝不会被记录。默认：关闭。

Delete Data on Uninstall：Remove the plugin settings and logs when uninstalling。勾选后，删除插件时会一并删除插件设置及其日志文件。订单上保存的 Mollie 付款 ID 会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Mollie）并下单。插件会以订单币种为订单总额创建一笔 Mollie 付款（JPY 和 ISK 无小数位），描述为 Order # 加订单号，并将顾客转到 Mollie 托管的付款页面。在那里，顾客从您 Mollie 账户中已启用的付款方式中选择一种并完成付款。

Mollie 的 Webhook 不带签名，只包含付款 ID。因此插件从不单独信任 Webhook：它会使用您自己的 API 密钥从 Mollie API 获取付款信息，核对该付款是否属于此订单，并将已付金额和币种与订单进行比较。只有在 Mollie 以这种方式确认后，订单才会被标记为已付款。插件会处理以下 Mollie 付款状态：

顾客返回时，插件会以同样的方式通过 Mollie API 核对最近一笔付款。已付款的付款会引导至订单已接收页面。如果付款已取消、失败、过期或尚未完成，顾客会被转到 Pay for 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 允许的情况下，会在 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.。技术原因会添加到订单备注和日志中。

该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce 高性能订单存储（HPOS）。

顾客在 Mollie 页面而非您的结账页面中选择 Mollie 付款方式。本插件不支持订阅或定期付款、已保存的银行卡或授权书、Mollie Components（您网站上的银行卡输入框）、Apple Pay 或 PayPal 快捷按钮，也不支持 Orders API，因此 Mollie 不会为这些付款提供需要订单行的付款方式（例如部分 Klarna、Billie 或 in3 选项）。已授权的付款须在 Mollie Dashboard 中扣款或撤销，而不能通过 WooCommerce 操作。

订单与退款

订单状态

Pending payment：顾客已被转到 Mollie，但尚未付款。

Processing or Completed：付款已确认。状态遵循 Order Status After Payment。订单备注会显示 Mollie 付款、付款方式和模式。交易 ID 为完成该订单付款的 Mollie 付款 ID（tr_...）。

On hold：银行转账正在等待款项，已授权的付款正在等待扣款，或 Mollie 报告了拒付。当已付金额或币种与订单不一致、测试付款是在店铺处于正式模式时完成的（未收到任何款项），或付款是在订单取消之后到达时，同样会设置保留状态。订单备注会说明原因。请在 Mollie Dashboard 中核对付款，然后处理订单或退还付款。

Failed：最近一次付款尝试失败、过期或被取消。已付款的订单绝不会被更改。顾客可以重新付款。

如果同一订单的第二笔付款已完成，订单不会再次更改。备注会提示您在 Mollie Dashboard 中退还重复的付款。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Mollie（按钮会显示您的 Title）。支持全额和部分退款。退款会针对真正支付该订单的付款发起，并使用进行该付款时所处模式的 API 密钥，因此必须已设置该模式的密钥。该按钮仅对已完成 Mollie 付款的订单可用。如果 Mollie 拒绝退款，WooCommerce 会显示 Mollie 的错误信息，且不会记录任何退款。成功的退款会连同 Mollie 退款 ID 一起添加到订单备注中。

在 Mollie Dashboard 中创建的退款和拒付不会转换为 WooCommerce 退款。拒付只会添加一条备注。

许可证密钥

本插件需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Mollie 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证的有效截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥只能用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，Mollie 不会在结账时显示给顾客。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍会看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已启动的付款仍会被确认，退款也可正常进行。

许可证到期后，插件仍可继续运行，但更新和支持需要续费。状态会在后台自动重新检查。

故障排除

Mollie 未在结账中显示：请检查许可证是否有效、Enable/Disable 是否已开启，以及当前模式是否已有 API 密钥：测试模式下为 Test API Key，正式模式下为 Live API Key。检查店铺币种（或 Pay for order 页面上的订单币种）是否受 Mollie 支持。设置页面会针对上述每个问题显示警告。

付款已完成，但订单仍为 Pending payment：Webhook 无法访问您的网站。设置中显示的 Webhook URL 必须能被互联网访问（不能有维护模式、基本身份验证或阻止访问的防火墙）。顾客付款后返回店铺时，订单也会更新。

Webhook answers Unknown payment.：对于您的测试或正式 API 密钥，Mollie 无法识别该付款 ID，例如属于其他 Mollie 账户的付款。

Webhook answers Payment ID mismatch.：根据其数据，该付款不属于此订单。订单不会被更改。

Webhook answers Failed to fetch payment.：无法连接 Mollie API。Mollie 会稍后重试 Webhook。

API 密钥未保存：密钥必须以 test_ 或 live_ 开头，后接至少 30 个字母和数字。请从 Mollie Dashboard 重新复制。

付款未创建：订单备注和日志会显示 HTTP 代码和 Mollie 消息。401 表示 API 密钥错误；422 表示请求中的某个字段有问题，例如 Mollie 不接受的金额或币种。请开启 Logging，并查看 WooCommerce > Status > Logs，来源为 wcp_mollie_gateway。

订单处于 On hold：请阅读订单备注。原因可能是金额或币种不一致、正式模式下的测试付款、取消后的付款、银行转账、未扣款的授权或拒付。

退款因模式相关消息而失败：付款是在测试或正式模式下完成的，而该模式的 API 密钥尚未设置。请输入该密钥后重试。

其他币种：开发者可以使用 molg_supported_currencies 过滤器更改币种列表。

许可证区块显示错误：请按照区块中的提示操作。例如，如果该密钥已在其他域名上使用，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果站点地址已更改，请点击 Check now，为新域名激活该密钥。如果无法连接许可证服务器，插件将继续使用最后已知的状态运行。

卸载

停用插件会保留所有数据。若要删除，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被删除。仅当 Delete Data on Uninstall 已开启时，网关设置和日志文件才会被删除；否则它们会保留，以便日后重新安装。现有订单会保留其付款备注、Mollie 付款 ID 和交易 ID。

Mollie 是其各自所有者的商标。本插件与 Mollie 无关联，也未获得 Mollie 的认可。