VibeFox MakeCommerce for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

商店的互联网访问：MakeCommerce 会将付款通知发送到您的商店，因此网站必须能够从互联网访问。防火墙或基本身份验证可能会阻止这些通知。维护模式不会阻止它们：OpenCart 3 允许付款扩展的请求通过，而在 OpenCart 4 中，扩展会为它们添加一个启动动作。

MakeCommerce 账户：您需要 MakeCommerce Merchant Portal（Settings > API）中的 Shop ID 和 Secret key。测试环境和正式环境拥有独立的账户和密钥。可用的付款方式和货币由您与 MakeCommerce 的合同决定。不提供 KWD 或 BHD 等小数位为三位的货币。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载文件是一个压缩包，包含两个 OpenCart 版本的安装包。请先在您的电脑上解压。压缩包中有 README.txt、OpenCart 3 安装包 wcp_makecommerce_payment-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_makecommerce_payment.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 输入测试环境的 Shop ID 和 Secret key；如需接受真实付款，则输入正式环境的密钥（参见配置）。无需在 Merchant Portal 中进行任何设置。

5. 开启 Enable/Disable，然后点击 Save。在开启 Test mode 的情况下测试一笔付款，然后关闭它以接受真实付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至 5 步输入许可证密钥和 MakeCommerce 密钥。两个版本的设置页面及其字段相同。只有回调 URL 不同（参见付款通知）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox MakeCommerce Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当测试模式开启时，页面会显示 Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. 当支付方式已启用但当前环境的 Shop ID 或 Secret key 为空时（此时该支付方式在结账时会被隐藏），以及当商店的默认货币无法被 MakeCommerce 收款时（此时该支付方式会对该货币的订单隐藏），页面都会向您发出警告。如果没有修改扩展的权限，页面只显示设置，但无法保存。

保存时，Title 不能为空且不能超过 128 个字符，Sort Order 必须为整数（允许负数），Total 必须是大于或等于 0 的数字，并且每个订单状态都必须存在。如果某个字段有误，则不会保存任何内容，页面会指出该字段。保存时会删除 Shop ID 和密钥中的空格。

MakeCommerce

Enable/Disable：Enable MakeCommerce payments 用于开启或关闭该支付方式。默认：关闭。

Title：客户在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Bank link or card (MakeCommerce)。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方显示给客户的文字。默认：Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

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

Geo Zone：仅为所选地理区域内的支付地址提供 MakeCommerce。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

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

MakeCommerce 账户

Shop ID 和 Secret key 位于 MakeCommerce Merchant Portal 的 Settings > API 下。测试门户和正式门户拥有独立的账户和密钥。该部分提供了两个门户以及 MakeCommerce 注册页面的链接。

Test mode：使用 MakeCommerce 测试环境（不会扣除真实资金）。新付款会使用所选环境及其密钥创建。每个订单都会记住其付款所在的环境：状态查询和退款始终会发送到该环境。开启时，客户在 Confirm Order 步骤会看到 TEST MODE — MakeCommerce test environment, no real money is charged. 默认：开启。

Test Shop ID：您测试账户的 Shop ID，格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。

Test Secret key：您测试账户的 Secret key。它用于签名和验证付款消息。

Live Shop ID：您正式账户的 Shop ID，格式相同。

Live Secret key：您正式账户的 Secret key。

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

付款通知

在 Merchant Portal 中无需进行任何设置。Callback URLs 仅供参考，显示客户返回或取消的地址，以及付款通知的地址。它们由您的 OpenCart 安装的商店地址生成，例如 OpenCart 3 中的 https://your-store/index.php?route=extension/payment/wcp_makecommerce_payment/notification，以及 OpenCart 4 中的 https://your-store/index.php?route=extension/wcp_makecommerce_payment/payment/wcp_makecommerce_payment.notification。每笔交易都带有自己的返回、取消和通知 URL，这些 URL 基于这些地址，并添加了订单号和一个密钥。MakeCommerce 会向通知 URL 发送已签名的消息（服务器对服务器），并通过客户的浏览器向返回或取消 URL 发送消息。签名使用创建该交易的环境的 Secret key 进行验证。没有有效签名的消息会被拒绝。

该扩展会处理以下 MakeCommerce 交易状态：

当客户返回商店时，付款也会得到确认。如果客户在没有已签名消息的情况下返回，扩展会向 MakeCommerce API 查询状态。

订单

OpenCart 在 Confirm Order 步骤中创建的订单没有状态（缺失订单）。只有在 MakeCommerce 确认付款后（已签名的通知或客户的已签名返回，并通过 MakeCommerce API 再次核实），订单才会获得状态。下面的每个字段都列出了您 OpenCart 中的订单状态。

Order Status After Payment：经过验证的 MakeCommerce 付款后的状态。默认：Processing（处理中）。

Payment On Hold Status：付款需要人工审核：付款金额或货币与订单不符，交易在 MakeCommerce 尚未最终确定，或者款项是在订单已取消后到账的。备注会说明原因。默认：Pending（待付款），因为 OpenCart 没有“保留”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：在您的商店中表示“已取消”的状态。针对此类订单到达的 MakeCommerce 付款会使该订单进入保留状态。扩展本身从不设置此状态。默认：Canceled（已取消）。

Refunded Status：在订单页面中全额退款后设置。默认：Refunded（已退款）。

高级

Debug log：将 API 调用和付款通知记录到 OpenCart 日志文件夹（storage/logs）中的 wc_mkc_debug.log.php。该文件无法通过网页打开。错误始终会被记录。密钥和客户数据绝不会被记录。默认：关闭。

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

Delete data：开启后，卸载扩展会删除扩展设置和日志。订单及其 MakeCommerce 付款数据始终会被保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。Shop ID 和 Secret key 不会被导出。

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

结账

在 Payment Method 步骤中，客户选择支付方式（默认为 Bank link or card (MakeCommerce)）。在 Confirm Order 步骤中，客户会看到您的说明。OpenCart 在此步骤中创建订单，此时仍无状态。当客户点击 Confirm Order 时，扩展会以订单货币为订单总额创建一笔 MakeCommerce 交易，并将客户带到 MakeCommerce 付款页面。在那里，客户选择银行链接或卡片。在 OpenCart 4 中，客户在付款方式区块中点击 Choose 按钮选择付款方式（位于 Payment method options 窗口中），然后点击结账页面底部的 Confirm Order。客户的电子邮件和国家会传递给 MakeCommerce；如果 MakeCommerce 支持商店语言（爱沙尼亚语、英语、拉脱维亚语、立陶宛语、芬兰语、俄语、德语、波兰语），页面会以该语言打开，否则以英语打开。

付款后，客户会返回您的商店。只有在 MakeCommerce 确认后，订单才会被标记为已付款：通过已签名的通知或客户已签名的返回，并通过 MakeCommerce API 核对交易。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，客户会看到 OpenCart 订单成功页面，并显示 Your MakeCommerce payment has been received. 如果订单进入了审核状态，页面会显示 Your MakeCommerce payment was received and is being reviewed by the store.

如果付款已获批准但尚未完成，或者订单正被另一请求同时确认，或者无法连接 MakeCommerce，则会显示 Payment confirmation 页面，其中包含 We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. 以及 Check again 和 Back to checkout 按钮。Check again 会向 MakeCommerce 查询该订单最近交易的状态。一旦付款完成，通知便会设置订单状态。

如果客户在 MakeCommerce 页面上取消，或付款过期或失败，客户会返回结账页面并看到消息，例如 The payment was cancelled. You can try again or choose another payment method.、The payment session expired. Please try again. 或 The payment was not completed. Please try again or choose another payment method. 在 OpenCart 4 中，这些消息显示在结账页面上方。购物车会被保留，客户可以再次付款。每次尝试都是一笔新的 MakeCommerce 交易（OpenCart 3 每次显示 Confirm Order 步骤时也会创建一个新订单，OpenCart 4 则会保留一个订单并再次为其付款）。在创建新交易之前，系统会在 MakeCommerce 检查同一购物车的未完成尝试：如果其中某一笔已付款，客户会直接进入成功页面。同一购物车较早的付款链接仍然有效，但购物车永远不会被付款到两个订单中：已付款购物车的较早订单若迟到付款，只会在已付款订单上添加一条备注。

在 OpenCart 4 中，订单会保留在结账流程中，直到显示成功页面。如果该订单在未付款的情况下已被关闭（例如您取消了订单），客户会被带回结账页面，并显示 Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order.，下一次 Confirm Order 会支付一个新订单。即使订单曾付款后又被取消，这类订单也不再占用购物车。

如果 MakeCommerce 无法启动付款，客户会停留在 Confirm Order 步骤，并看到 MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. 或 MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. 技术原因会写入日志。

银行或卡片在 MakeCommerce 页面上选择，而不是在您商店的结账页面中选择。该扩展不支持保存的卡片、定期付款或订阅，也不支持通过 MakeCommerce 发货（自提柜、运单标签）。

订单与退款

订单状态

无状态（缺失订单）：客户已被转到 MakeCommerce 但尚未付款，付款已取消、过期或失败，或者 MakeCommerce 尚未确认付款。在 Sales > Orders 中，此类订单仅在筛选器 Order Status 设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：付款已确认。备注会显示金额、交易、环境以及验证方式（MakeCommerce API 或已签名通知）。

Payment On Hold Status（默认 Pending）：已付金额或货币与订单不符，金额缺失，MakeCommerce 上的交易虽被报告为已完成但尚未最终确定，或付款是在订单取消后到达的。备注会解释原因。金额不符的交易永远不会在之后为订单付款；尚未最终确定的交易会在 MakeCommerce 报告其已完成时完成订单。请在 Merchant Portal 中检查该交易，然后处理订单或退还付款。

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

如果已付款的订单又收到第二笔付款，订单不会被更改。备注会要求您在 MakeCommerce Merchant Portal 中退还重复付款。对已退款订单或已切换为其他支付方式的订单的付款，只会添加备注。

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

VibeFox MakeCommerce Payment 选项卡

在 Sales > Orders 中打开使用 MakeCommerce 付款的订单。在订单页面底部，紧挨着 History 和 Additional，VibeFox MakeCommerce Payment 选项卡会显示该订单的所有 MakeCommerce 交易（日期、交易 ID、测试付款的 Test 标签、金额、MakeCommerce 状态和结果）、Paid / refunded 金额、退款表单、退款历史以及订单的 MakeCommerce notes。该选项卡对有权访问该扩展的用户显示；其按钮需要修改扩展的权限（在 System > Users > User Groups 中设置）。

Check MakeCommerce payment status：向 MakeCommerce API 查询该订单交易的状态（最新的优先），应用该状态并添加一条带有结果的备注。当客户称已付款但订单没有状态时使用。

退款

在 VibeFox MakeCommerce Payment 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via MakeCommerce。确认问题 Refund this amount via MakeCommerce? 支持全额和部分退款。退款金额和货币受 MakeCommerce 交易的限制，因此在金额不一致后，您最多只能退还客户实际支付的金额，而不是订单总额。退款会发送到付款所在的环境（测试或正式），因此该环境的密钥必须已设置。退款原因会作为退款备注发送给 MakeCommerce；如果没有原因，备注为 Refund for order 加订单号。如果 MakeCommerce 不接受退款，选项卡会显示错误，添加一条备注，并且不会记录任何退款。如果 MakeCommerce 仍在处理该付款，消息为 MakeCommerce is still processing this payment — try the refund again later. 成功的退款会添加到退款历史和备注中，并附带 MakeCommerce 退款 ID。全额退款会将订单设为 Refunded Status，且不会通知客户，也不会将商品退回库存，与手动更改状态时一样。部分退款不会改变状态。退款在 MakeCommerce 确认付款后即可进行。

Sales > Returns 中的商品退货不会通过 MakeCommerce 退回款项。

在 Merchant Portal 中进行的退款会随交易状态一起到达，并添加到备注中。订单状态不会自动改变。

许可证密钥

该扩展需要使用从 vibefox.net 获得的 VibeFox 许可证密钥。许可证区块 License — VibeFox MakeCommerce Payment 位于 Extensions > Extensions > Payments > VibeFox MakeCommerce Payment > Edit 页面的第一个区块，位于设置上方。将密钥粘贴到 License key 中，然后点击 Activate。此后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店移除密钥）。其下方是行 Product: opencart-payment-makecommerce 以及链接 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 账户中释放该名额。

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

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

故障排除

MakeCommerce 未在结账时显示：检查许可证是否有效、Enable/Disable 是否开启，以及当前环境是否已有密钥：测试模式下为 Test Shop ID 和 Test Secret key，正式模式下为 Live Shop ID 和 Live Secret key。检查订单货币的小数位不超过两位，付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。

付款已完成，但订单仍无状态：通知无法到达商店，例如由于防火墙或基本身份验证。当客户返回商店或点击 Check again，以及您在订单选项卡中点击 Check MakeCommerce payment status 时，订单也会获得状态。请检查付款所在环境的密钥是否已设置：通知会使用该环境的 Secret key 进行验证，没有它，MakeCommerce 会收到错误并重试。开启 Debug log 可查看通知。

订单处于审核状态：阅读订单选项卡中的 MakeCommerce notes（参见订单状态），在 Merchant Portal 中检查该交易，然后处理订单或退还付款。

通知被拒绝：签名错误、属于其他订单、其他商店或并非为该订单创建的交易的消息会被拒绝，并且不会更改任何内容。请检查 Shop ID 和 Secret key 是否属于同一个 MakeCommerce 账户和环境。

客户在 Confirm Order 之后看到错误：开启 Debug log，并查看扩展页面上的 Log 字段。This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不匹配，或支付方式在此期间已被关闭：客户需要重新加载结账页面。MakeCommerce 无法收款的货币会显示 MakeCommerce cannot process payments in 以及货币代码。

退款因与环境相关的消息而失败：订单是在测试或正式环境中付款的，而该环境的密钥未配置。请输入后重试。

选项卡中没有退款表单：选项卡会说明原因：付款尚未确认，付款已全额退款，您的用户组没有修改该扩展的权限，订单已切换为其他支付方式，或付款环境的密钥未设置。

对于开发人员：该扩展会触发 OpenCart 事件 wc_mkc_transaction_data、wc_mkc_customer_data、wc_mkc_supported_locales 和 wc_mkc_is_available，以修改交易数据、客户数据、付款页面语言以及该支付方式的可用性。

卸载

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

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

MakeCommerce 是其各自所有者的商标。本扩展与 MakeCommerce 没有关联，也未获得 MakeCommerce 的认可。