VibeFox Mollie for OpenCart — 帮助

要求

OpenCart：3.0.x（已在 3.0.5.0 上测试）或 4.0.2 及更高版本（已在 4.1.0.3 上测试）。

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 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请在您的电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_mollie_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_mollie_gateway.ocmod.zip。只需安装与您的 OpenCart 版本相对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_mollie_gateway-oc3-(version).ocmod.zip。该扩展没有 OCMOD 修改，因此无需刷新 Extensions > Modifications。您也可以不使用安装程序，而是将本安装包中 upload 文件夹的内容复制到商店的根目录。

2. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Mollie Gateway，点击 Install（绿色的 + 按钮）。您的管理员用户需要拥有修改支付扩展列表的权限。

3. 点击 Edit（铅笔按钮）打开设置页面。将您的 VibeFox 许可证密钥粘贴到页面顶部许可证区块中的 License key，然后点击 Activate（参见 License key）。

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

5. 开启 Enable/Disable 并点击 Save。在完成一次测试付款之前，请保持 Test Mode 开启，之后再将其关闭。

OpenCart 4

1. 在后台进入 Extensions > Installer，点击 Upload，然后选择文件 wcp_mollie_gateway.ocmod.zip。请不要重命名该文件：OpenCart 4 从文件名中获取扩展代码，重命名后的安装包无法使用。

2. 安装包会出现在同一页面的已安装扩展列表中。点击其旁边的 Install（绿色 + 按钮）。

3. 进入 Extensions > Extensions，选择类型 Payments。找到 VibeFox Mollie Gateway，点击 Install（绿色 + 按钮），然后点击 Edit（铅笔按钮）。

4. 按照 OpenCart 3 中第 3 至 5 步的方法输入许可证密钥和 API 密钥。两个版本的设置页面及其字段相同，只有 Webhook URL 不同（参见 Webhook URL）。

新安装默认关闭付款方式，并开启测试模式。

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果 Mollie 已启用但当前模式的 API 密钥为空，或者 Mollie 不支持商店的默认货币，页面会提示您。在这两种情况下，结账时都会隐藏该付款方式。如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字；否则不会保存任何内容。不以 test_ 或 live_ 开头、或其后不是至少 30 个字母和数字的 API 密钥不会被保存：页面会显示 Settings saved, except the API key shown in red.，错误信息会指出该密钥，并保留之前保存的密钥。

Checkout

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

Title：结账时显示给顾客的付款方式标题。它也是订单中保存的付款方式名称。默认：Mollie。必填。

Description：在 Confirm Order 步骤中、确认按钮上方显示给顾客的文本。默认：Pay securely via Mollie。

Sort Order：Mollie 在结账时付款方式中的位置。可留空或输入整数。

Geo Zone：仅向所选地理区域内的账单地址提供 Mollie。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以商店默认货币计）才会提供 Mollie。留空则对任何金额都提供 Mollie。

API 密钥

您可以在 Mollie Dashboard 的 Developers > API keys 下找到 API 密钥；本部分中的链接会指向该页面。测试密钥和正式密钥是分开的。

Test Mode：新付款使用测试 API 密钥。不会处理任何真实付款。在 Mollie 测试结账页面上，您可以选择付款结果。顾客在 Confirm Order 步骤中会看到 Test mode: no real payment will be made. 在另一模式下进行的付款，在查询状态和退款时仍会使用其自身模式的密钥。默认：开启。

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

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

已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。若要删除已保存的密钥，请勾选字段下方的 Clear the saved key on save，然后点击 Save。

Webhook

Webhook URL：仅供参考。无需设置 Webhook：扩展会在每次付款时将此 URL 发送给 Mollie。在 OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_mollie_gateway/webhook，在 OpenCart 4 中类似 https://your-store/index.php?route=extension/wcp_mollie_gateway/payment/wcp_mollie_gateway.webhook，由您的 OpenCart 安装的商店前台地址生成。它必须可以从互联网访问，否则订单只有在顾客从 Mollie 返回后才会获得状态。

订单

OpenCart 会在 Confirm Order 步骤中创建订单，此时订单没有状态（即缺失订单）。只有在 Mollie 报告付款后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款成功后设置的状态。默认：处理中。选择 Complete 可将已付款的订单标记为已完成。

Awaiting Mollie Payment Status：顾客在 Mollie 页面上选择了银行转账；Mollie 收到款项后，订单会自动标记为已付款。默认：待处理。

Mollie Payment On Hold Status：该付款需要您审核（参见 Order statuses）。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Error Status：等待中的银行转账或已授权的付款失败、过期或被取消。默认：失败。

Refunded Status：付款已从订单页面全额退款。默认：已退款。

高级

Logging：将 API 调用和 Webhook 写入 OpenCart 日志文件夹（storage/logs）中的 molg_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误也始终会被记录。API 密钥和顾客数据绝不会被记录。默认：关闭。

Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。

Delete Data on Uninstall：开启后，卸载扩展时会删除网关设置及其日志。随订单保存的 Mollie 付款 ID（付款、退款）始终会保留。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API 密钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API 密钥会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Mollie）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to Mollie to choose a payment method and pay. OpenCart 在此步骤中创建订单，此时仍无状态。当顾客点击 Confirm Order 时，扩展会以订单货币（JPY 和 ISK 无小数位）为订单总额创建一笔 Mollie 付款，描述为 Order # 加订单号，并将顾客带到 Mollie 托管的结账页面。在那里，顾客可选择您 Mollie 账户中启用的一种付款方式并付款。在 OpenCart 4 中，顾客需在付款方式区块中点击 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

Mollie 的 Webhook 没有签名，只包含付款 ID。因此，扩展从不单独信任某个 Webhook：它只接受由自身创建的付款 ID，使用付款所在模式的密钥通过 Mollie API 读取付款信息，检查付款是否属于该订单，并将已付金额和货币与订单总额进行比较。只有 Mollie 以这种方式确认后，订单才会被标记为已付款。扩展会处理以下 Mollie 付款状态：

顾客返回时，扩展会以同样的方式通过 Mollie API 检查付款。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面，其中显示 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. 在 OpenCart 4 中，这些提示显示在结账页面上方。购物车会被保留。如果无法连接 Mollie，或 Mollie 尚未作出决定，则会显示 Payment confirmation 页面，请顾客不要重复付款，并提供 Check again 按钮；Webhook 一到达就会设置订单状态。

OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单，OpenCart 4 则保留一个结账订单，并通过新的 Mollie 付款为同一订单再次付款。无论哪种情况，扩展都会将同一购物车的所有订单视为一笔付款。顾客再次付款时，会复用相同金额且仍处于开放状态的 Mollie 付款，而不是创建第二笔可付款的付款。如果总额已更改，Mollie 允许的情况下，旧的开放付款会在 Mollie 中被取消。如果旧付款期间已完成支付，则该付款会被确认，顾客直接进入成功页面，无需新的付款。

OpenCart 4 会在显示成功页面之前将订单保留在结账流程中。如果该订单期间未付款即被关闭（例如其银行转账已过期，或您取消或退款了该订单），顾客会被带回结账页面，并看到 Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order.，下一次点击 Confirm Order 时将为新订单付款。已付款后又被取消或退款的购物车订单不再占用该购物车。

如果 Mollie 无法启动付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 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 仍然有效，因为 OpenCart 3 会放行付款扩展的请求；而在 OpenCart 4 中，扩展会为此添加一个启动动作，该动作也允许顾客从 Mollie 返回。

顾客是在 Mollie 页面而不是您的结账页面上选择 Mollie 付款方式的。该扩展不支持订阅或定期付款、已保存的银行卡或授权书（mandate）、您网站上的银行卡输入框、Apple Pay 或 PayPal 快捷按钮以及 Orders API，因此需要订单明细的付款方式（例如部分 Klarna、Billie 或 in3 变体）不会由 Mollie 为这些付款提供。已授权的付款需要在 Mollie Dashboard 中扣款或撤销，而不是在 OpenCart 中操作。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Mollie 但尚未付款，或者 Mollie 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment（默认处理中）：付款已确认。备注会显示 Mollie 付款（tr_...）、付款方式和模式。

Awaiting Mollie Payment Status（默认待处理）：顾客在 Mollie 页面上选择了银行转账。Mollie 收到款项后，订单会转为已付款状态。

Mollie Payment On Hold Status（默认待处理）：已授权的付款等待扣款，Mollie 报告了拒付，已付金额或货币与订单不符，在商店处于正式模式时付了一笔测试付款（未收到任何款项），或者付款是在订单已获得其他状态（例如已取消）之后到达的。备注会说明情况。请在 Mollie Dashboard 中检查该付款，然后处理订单或为付款退款。

Payment Error Status（默认失败）：订单的银行转账或授权失败、过期或被取消。

Refunded Status（默认已退款）：付款已通过该扩展全额退款。

OpenCart 会以常规方式通知顾客这些状态变化。如果同一购物车的第二笔付款已完成，订单不会被更改。已付款订单上的备注会提醒您在 Mollie Dashboard 中为重复付款退款。

备注是订单 History 中的条目，顾客看不到。

VibeFox Mollie Gateway 选项卡

在 Sales > Orders 中打开一笔通过 Mollie 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Mollie Gateway 选项卡会显示 Mollie payment 的 ID（测试付款会带有 Test mode 标签）、Method、付款的 Status、Paid / refunded 金额、退款表单、退款历史（日期、退款 ID、金额、模式、Mollie 状态、原因）以及订单的 Mollie notes。该选项卡会显示给有权访问该扩展的用户。

退款

在 VibeFox Mollie Gateway 选项卡中输入 Amount（系统会预先填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Mollie。确认提问 Refund this amount through Mollie? This cannot be undone. 支持全额和部分退款。您需要拥有修改扩展的权限（在 System > Users > User Groups 中设置）。退款以 Mollie 实际扣款的金额和货币进行，因此在金额不一致后，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会针对实际支付该订单的那笔付款进行，并使用该付款模式的 API 密钥，因此必须设置该模式的密钥。如果 Mollie 拒绝退款，或将其报告为失败或取消，选项卡会显示相应信息，且不会记录任何退款。成功的退款会连同 Mollie 退款 ID 一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。Mollie 报告付款已付款后，即可进行退款。

在 Sales > Returns 中的商品退货不会通过 Mollie 退回款项。在 Mollie Dashboard 中创建的退款不会显示在订单上；拒付则会添加备注。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Mollie Gateway 位于 Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit 页面中，是设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、许可状态（例如许可证有效期截止日期和您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（将密钥从本商店移除）。其下方是 Product: opencart-payment-mollie 一行，以及 Manage licenses and domains in your account 链接，该链接会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文本跟随后台语言显示（包含英语和俄语）。

如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或 License expired on 加上日期。在商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展会继续使用最后已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效的密钥时，结账时不会向顾客显示 Mollie。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍可在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，以便您在购买密钥之前进行设置和测试。在 OpenCart 4 中此预览不可用：商店无法看到管理员登录状态，因此没有有效密钥时，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 可将其关闭，并隐藏 7 天。现有订单不受影响：已经开始的付款仍会被确认，退款也照常进行。

许可证过期时，扩展仍会继续工作，但更新和支持需要续费。当您打开后台的 Dashboard 或 Edit 页面时，系统会自动重新检查状态：输入密钥后的前 14 天每天检查一次，之后每周检查一次。无需 cron 任务。卸载扩展时，始终会删除许可证密钥和许可证状态。

故障排除

结账时不显示 Mollie：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否有 API 密钥：测试模式需要 Test API Key，正式模式需要 Live API Key。检查结账货币是否受 Mollie 支持，付款地址是否位于所选 Geo Zone 中，以及订单金额是否达到设置中的 Total。设置页面会针对缺失的密钥和不受支持的商店货币显示警告。

付款已完成，但订单仍无状态：Webhook 无法访问您的商店。Webhook URL 中显示的 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 重新复制。

顾客在 Confirm Order 后看到错误：查看扩展页面上的 Log 字段。它会显示 HTTP 代码和 Mollie 消息。401 表示 API 密钥错误；422 表示请求中的某个字段有问题，例如 Mollie 不接受的金额或货币。This payment method is not available. 表示结账会话已与订单不匹配，或付款方式在此期间已被关闭：顾客需要重新加载结账页面。

订单处于暂停状态：请阅读 VibeFox Mollie Gateway 选项卡中的备注（参见 Order statuses），然后处理订单或为付款退款。

选项卡中没有退款表单：选项卡会说明原因：付款尚未完成、已全额退款、您的用户组没有修改扩展的权限，或者付款是在测试或正式模式下完成的，而该模式的 API 密钥未设置（请输入密钥并重新打开订单）。

对开发人员：该扩展会触发 OpenCart 事件 molg_supported_currencies（货币列表）和 molg_payment_data（在创建 Mollie 付款之前的付款请求和订单）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Mollie Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及在维护模式下放行 Webhook 的启动动作）。如果 Delete Data on Uninstall 已开启，则其他网关设置（标题、描述、测试模式、API 密钥、日志记录）和日志都会被删除。如果关闭，这些设置会保留，以便日后重新安装时使用。Mollie 付款 ID 和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

在 OpenCart 4 中，如需同时删除扩展文件，请在卸载后进入 Extensions > Installer，在已安装扩展列表中点击 VibeFox Mollie Gateway 旁边的 Uninstall（橙色 − 按钮），然后点击 Delete（红色垃圾桶按钮）以删除已上传的安装包。

Mollie 是其所有者的商标。本扩展与 Mollie 无关联，也未获得 Mollie 的认可。