VibeFox MakeCommerce for WooCommerce — 帮助
系统要求
WordPress: 6.0 或更高版本。
WooCommerce: 7.0 或更高版本，已安装并启用。若未安装 WooCommerce，插件将拒绝启用。
PHP: 8.0 或更高版本。
网站的互联网访问权限： MakeCommerce 会向您的店铺发送支付通知，因此网站必须支持外网访问（推荐使用 HTTPS）。防火墙、维护模式或基本身份验证可能会阻止这些通知。
MakeCommerce 账户： 您需要从 MakeCommerce Merchant Portal (Settings > API) 获取 Shop ID 和 Secret key。测试环境和正式环境拥有独立的账户和密钥。可用支付方式和币种由您的 MakeCommerce 合同决定（银行链接使用 EUR）。不提供带有三位小数的币种（如 KWD 或 BHD）。
VibeFox 许可证密钥： 从 vibefox.net 购买。一个密钥适用于一个域名。
安装
1. 在 WordPress 中前往 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_makecommerce_payment 文件夹上传至 /wp-content/plugins/。
2. 点击 Activate。
3. 打开设置页面：WooCommerce > Settings > Payments > MakeCommerce > Manage，或在“插件”页面点击插件名称下方的 Settings。
4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。
5. 输入测试环境的 Shop ID 和 Secret key；若要进行真实付款，请输入正式密钥（参见“配置”）。无需在 Merchant Portal 中进行任何配置。
6. 开启 Enable/Disable。在启用 Test mode 的情况下测试支付，然后取消勾选以接受真实付款。
配置
所有设置均位于同一页面：WooCommerce > Settings > Payments > MakeCommerce。在测试模式启用期间，页面字段上方会显示 Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged.。如果该支付方式已启用但当前环境的 Shop ID 或 Secret key 为空，或者店铺币种无法通过 MakeCommerce 收款，页面会显示警告。在上述两种情况下，该支付方式都会在结账页面隐藏。在支付方式列表中，MakeCommerce 会被标记为需要设置，直到当前环境配置了相应密钥。保存设置时会自动去除密钥中的空格。
General
Enable/Disable: Enable MakeCommerce payments 用于开启或关闭此支付方式。默认：关闭。
Title: 顾客在结账页面看到的支付方式名称。默认：Bank link or card (MakeCommerce)。
Description: 在结账页面显示在支付方式下方的说明文本。默认：Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page。
MakeCommerce account
Shop ID 和 Secret key 可在 MakeCommerce Merchant Portal 中的 Settings > API 下找到。测试门户和正式门户拥有独立的账户和密钥。该部分提供了指向两个门户及 MakeCommerce 注册页面的链接。
Test mode: Use the MakeCommerce test environment (no real money is charged)。新的付款将在选定的环境中通过其对应密钥创建。每个订单都会记录其付款时所在的环境：状态检查和退款始终导向该环境。结账页面会显示提示文字 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。
Payment notifications
无需在 Merchant Portal 中进行任何配置。每笔交易都会携带其自身的返回、取消和通知 URL，这些 URL 基于本节显示的地址（类似于 https://your-site/wc-api/wc_mkc_payment/）并追加订单号和订单密钥。MakeCommerce 会向通知 URL 发送带有签名的消息（服务器到服务器），并通过顾客浏览器向返回或取消 URL 发送消息。签名将使用创建交易时所在环境的 Secret key 进行验证。未包含有效签名的消息将被拒绝。
本插件支持处理以下 MakeCommerce 交易状态：
当顾客返回店铺时，付款也会得到确认。如果顾客返回时未携带已签名消息，插件会向 MakeCommerce API 查询最新状态。
Advanced
Debug log: Log API calls and payment notifications 将详细信息写入 WooCommerce > Status > Logs，来源为 wcp_makecommerce_payment。错误始终会被记录。密钥和顾客数据绝不会被记录到日志中。默认：关闭。
Delete data: Delete the gateway settings and logs when the plugin is deleted。订单及其付款备注将始终保留。停用插件绝不会删除任何内容。默认：关闭。
结账
顾客选择支付方式（默认为 Bank link or card (MakeCommerce)）并提交订单。插件将针对订单币种下的订单总额创建一笔 MakeCommerce 交易，并将顾客重定向至 MakeCommerce 支付页面。顾客在该页面选择银行链接或卡片。账单邮箱和国家信息会传递给 MakeCommerce，如果 MakeCommerce 支持，页面将以店铺语言打开（爱沙尼亚语、英语、拉脱维亚语、立陶宛语、芬兰语、俄语、德语、波兰语），否则以英语打开。
付款完成后，顾客将返回您店铺的“收到订单”页面。只有在 MakeCommerce 确认付款后，订单才会被标记为已付款：确认方式包括带有签名的通知或顾客带有签名的返回，并配合通过 MakeCommerce API 对交易进行的核对。
如果顾客在 MakeCommerce 页面取消付款或付款会话过期，顾客将返回结账页面（或 Pay for order 页面）并看到提示消息，例如 The payment was cancelled. You can try again or choose another payment method. 或 The payment session expired. Please try again.。如果付款尚无法确认，提示消息为 We could not confirm your payment yet. If you completed it, your order will be updated automatically; otherwise please try again.。顾客可以重新付款。该订单之前的旧支付链接依然有效，且订单绝不会被重复支付。
如果 MakeCommerce 无法发起付款，顾客将看到 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.。技术原因将追加记录到订单备注和日志中。
此支付方式适用于经典结账、结账区块以及 Pay for order 页面。它与 WooCommerce 高性能订单存储 (HPOS) 完全兼容。
银行或卡片由顾客在 MakeCommerce 页面上选择，而不是在您的结账页面。插件不提供保存卡片、定期付款或 WooCommerce Subscriptions 功能，也不包含 MakeCommerce 物流配送（包裹自提柜、面单标签）。
订单与退款
订单状态
Pending payment: 顾客已被引导至 MakeCommerce 且尚未付款，或者 MakeCommerce 尚未确认付款。订单备注会显示 MakeCommerce 交易标识、金额和所在环境。
Processing: 付款已确认。仅包含虚拟可下载商品的订单将转为已完成（Completed），这是 WooCommerce 的默认行为。订单备注会显示金额、交易标识、所在环境以及验证方式（MakeCommerce API 或签名通知）。交易 ID 即为 MakeCommerce 交易 ID。
On hold: 支付金额或币种与订单不符、金额缺失、MakeCommerce 端的交易状态尚未最终确定，或者已取消订单收到了付款。订单备注中会说明具体原因。此类交易绝不会在日后使订单自动变为已付款。请在 Merchant Portal 中检查该交易，并手动完成或退款该订单。
Failed: 该订单最近一次付款已被取消、已过期或失败。顾客可以重新付款。
如果已付款的订单收到了第二次付款，订单不会被再次更改。系统会生成一条备注，提示您在 MakeCommerce Merchant Portal 中退还重复支付的款项。
Check MakeCommerce payment status
在订单详情页面中，于订单操作下拉菜单中选择 Check MakeCommerce payment status。插件会向 MakeCommerce API 查询该订单各笔交易的状态（优先查询最新一笔），应用该状态并添加一条包含查询结果的备注。当顾客已付款但订单仍停留在待付款状态时，请使用此功能。
退款
打开订单，点击 Refund，输入金额并点击 Refund via Bank link or card (MakeCommerce)（按钮上会显示您的 Title）。支持全额退款和部分退款。退款将提交至订单付款时所在的环境（测试或正式），因此必须配置该环境的密钥。如果 MakeCommerce 不接受该退款，WooCommerce 将显示错误信息，添加一条备注且不会记录退款。如果 MakeCommerce 仍在处理该付款，提示信息为 MakeCommerce is still processing this payment — try the refund again later.。退款成功后，将携带 MakeCommerce 退款 ID 记录到订单备注中。
在 Merchant Portal 中发起的退款将随交易状态同步传达，并添加到订单备注中。它们不会自动记录为 WooCommerce 退款。
许可证密钥
本插件需配合来自 vibefox.net 的 VibeFox 许可证密钥使用。许可证区块位于 WooCommerce > Settings > Payments > MakeCommerce 页面顶部。将密钥粘贴至 License key 并点击 Activate。该区块会显示许可证状态，例如到期日期以及绑定的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从此网站移除密钥。点击 Manage licenses and domains in your account 链接可打开您的 vibefox.net 账户。
一个密钥仅支持一个域名。从此网站移除密钥并不会释放该域名配额。请在您的 vibefox.net 账户中释放配额。
若无有效密钥，MakeCommerce 不会在结账页面向顾客展示。如果仍发起了支付，顾客将看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到该支付方式，并带有 (unlicensed — visible to admins only) 标记，以便您在购买密钥前进行配置和测试。插件页面和 WooCommerce 各页面均会显示相应提醒。现有订单不受影响：已发起的付款仍可正常确认，退款功能亦可正常使用。
许可证过期后，插件仍可继续工作，但更新和技术支持需要续期。系统会在后台自动重新检查状态。
故障排除
MakeCommerce 未在结账页面显示： 请检查许可证是否处于激活状态、Enable/Disable 是否已开启，以及当前环境是否配置了密钥：测试模式下为 Test Shop ID 和 Test Secret key，正式模式下为 Live Shop ID 和 Live Secret key。检查店铺币种（或 Pay for order 页面上的订单币种）是否最多包含两位小数。设置页面会针对其中的每一项问题显示警告。
付款已成功，但订单仍停留在待付款状态： 通知未能成功送达网站，可能由于防火墙、维护模式或基本身份验证所致。打开订单并执行订单操作 Check MakeCommerce payment status。检查付款发生时所在环境的密钥是否已配置：通知需使用该环境的 Secret key 进行验证，若缺少该密钥，MakeCommerce 将接收到错误并进行重试。
订单处于保留状态（On hold）并带有 MakeCommerce 备注： 付款与订单不符（金额、币种、状态），或属于已取消订单的付款。请在 Merchant Portal 中检查该交易，并手动完成或退款该订单。
通知被拒绝： 签名错误、属于其他订单或店铺、或非针对该订单创建的交易消息将被拒绝，订单不会发生变更。请检查 Shop ID 和 Secret key 是否属于同一个 MakeCommerce 账户及相同环境。
顾客在下单时遇到错误： 请查看订单备注，或开启 Debug log 并查阅 WooCommerce > Status > Logs（来源为 wcp_makecommerce_payment）。若币种无法通过 MakeCommerce 收款，将提示 MakeCommerce cannot process payments in 及对应的币种代码。
退款失败并提示环境相关信息： 订单是在测试或正式环境中支付的，而该环境的密钥未配置。请输入对应密钥后重试。
退款失败并提示 No MakeCommerce transaction ID found for this order： 订单未关联 MakeCommerce 交易。请在 Merchant Portal 中进行退款。
许可证区块显示错误： 请按照区块中的提示进行操作。例如，如果密钥已在其他域名上使用，请在 vibefox.net 账户中释放配额并点击 Check now。如果网站网址发生变更，请点击 Check now 为新域名激活密钥。如果无法连接许可证服务器，插件将按照最后已知的有效状态继续运行。
卸载
停用插件会保留所有数据。若要彻底移除，请在 Plugins 页面停用并删除插件。该插件的许可证密钥和许可证状态始终会被清除。仅当启用了 Delete data 时，网关设置和日志才会被清除；否则它们将被保留以便日后重新安装。现有订单将保留其付款备注和交易 ID。
MakeCommerce 是其各自所有者的商标。本插件未获得 MakeCommerce 的关联或认可。