VibeFox MakeCommerce for PrestaShop — 帮助
系统要求
PrestaShop： 8.0 至 9.x。
PHP： 8.0 或更高版本。模块拒绝在更低版本的 PHP 上安装。
商店的互联网访问： MakeCommerce 会将付款通知发送到您的商店，因此网站必须可从互联网访问。防火墙或基本身份验证可能会阻止这些通知。商店的维护模式和国家限制不会阻止它们。
MakeCommerce 账户： 您需要 MakeCommerce Merchant Portal（Settings > API）中的 Shop ID 和 Secret key。测试环境和正式环境使用独立的账户和密钥。可用的支付方式和货币由您的 MakeCommerce 合同决定。不支持 KWD 或 BHD 等小数位为三位的货币。
VibeFox 许可证密钥： 在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，然后点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者稍后在模块列表中找到 VibeFox MakeCommerce Payment，再点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段并点击 Activate（参见许可证密钥）。
4. 输入测试环境的 Shop ID 和 Secret key，若要接收真实付款，还需输入正式环境的密钥（参见配置）。无需在 Merchant Portal 中进行任何设置。
5. 开启 Enable/Disable 并点击 Save。在开启 Test mode 的情况下测试一笔付款，然后将其关闭以接收真实付款。
安装时，模块会创建订单状态 MakeCommerce payment on hold。PrestaShop 会为所有货币、国家和顾客组提供新的支付模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都在模块页面上：Modules > Module Manager > VibeFox MakeCommerce Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，测试模式开启时页面会显示 Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. 如果已启用该方式，但当前环境的 Shop ID 或 Secret key 为空，或者商店的默认货币无法由 MakeCommerce 收款，页面也会发出提示。在这两种情况下，该支付方式都会在结账页面隐藏。保存时，密钥中的空格会被删除。
MakeCommerce
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 账户
Shop ID 和 Secret key 位于 MakeCommerce Merchant Portal 的 Settings > API 下。测试门户和正式门户使用独立的账户和密钥。该部分提供了两个门户以及 MakeCommerce 注册页面的链接。
Test mode： 使用 MakeCommerce 测试环境（不会扣除真实款项）。新付款会使用所选环境及其密钥创建。每个订单都会记住其付款所在的环境：状态检查和退款始终指向该环境。开启时，顾客会在支付方式下方看到 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。
已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。
Clear saved secret keys： 勾选某个密钥并点击 Save 即可将其删除。字段为空时将保留已保存的值。
付款通知
无需在 Merchant Portal 中进行任何设置。Callback URLs 仅供参考，显示顾客返回或取消的地址以及付款通知地址。每笔交易都会携带自己的返回、取消和通知 URL，这些 URL 基于上述地址生成，并附加购物车编号和一个密钥。MakeCommerce 会以服务器对服务器的方式将带签名的消息发送到通知 URL，并通过顾客的浏览器将其发送到返回或取消 URL。签名使用创建该交易所在环境的 Secret key 进行验证。没有有效签名的消息会被拒绝。
模块会处理以下 MakeCommerce 交易状态：
顾客返回商店时也会确认付款。如果顾客在没有签名消息的情况下返回，模块会向 MakeCommerce API 查询状态。
高级
Debug log： 将 API 调用和付款通知记录到模块文件夹中的 logs/wc_mkc_debug.log.php。该文件无法通过网页打开。错误始终会被记录。密钥和顾客数据从不记录。默认：关闭。
Log： 显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data： 开启时，卸载模块会删除模块设置和日志。订单及其 MakeCommerce 付款数据始终保留。默认：关闭。
结账
在付款步骤，顾客选择付款方式（默认为 Bank link or card (MakeCommerce)）并确认。模块会以购物车货币为单位，为购物车总额创建一笔 MakeCommerce 交易，并将顾客重定向至 MakeCommerce 支付页面。顾客在该页面上选择银行链接或卡片。顾客的电子邮件和国家会传递给 MakeCommerce；若 MakeCommerce 支持，页面会以商店语言打开（爱沙尼亚语、英语、拉脱维亚语、立陶宛语、芬兰语、俄语、德语、波兰语），否则以英语显示。此时尚未创建订单。
付款后，顾客返回您的商店。只有在 MakeCommerce 确认付款后，订单才会被标记为已付款：通过带签名的通知或顾客带签名的返回，并通过 MakeCommerce API 核对交易。随后订单被创建，顾客会看到标准的订单确认页面，并显示 Your MakeCommerce payment has been received. 如果订单因审核而进入保留状态，页面会显示 Your MakeCommerce payment was received and is being reviewed by the shop.
如果付款已获批准但尚未完成，或者无法连接 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 按钮。付款完成后，通知会立即创建订单。
如果顾客在 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. 购物车会保留，顾客可以再次付款。每次尝试都会创建一笔新的 MakeCommerce 交易。同一购物车的较早付款链接仍然有效，并且购物车不能被两次付款而生成两个订单。
如果 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. 技术原因会写入日志。
银行或卡片由顾客在 MakeCommerce 页面上选择，而不是在您的结账页面。本模块不提供保存卡片、定期付款或订阅功能，也不包含 MakeCommerce 物流配送（包裹自提柜、面单标签）。
订单和退款
订单状态
No order yet： 顾客已被重定向至 MakeCommerce 但尚未付款，或 MakeCommerce 尚未确认付款。此时只存在购物车。
Payment accepted： 付款已确认。付款会以 MakeCommerce 交易 ID 记录，备注中会显示金额、交易、环境以及验证方式（MakeCommerce API 或带签名的通知）。
MakeCommerce payment on hold： 付款金额或币种与购物车不符（例如付款开始后购物车被修改）、金额缺失、MakeCommerce 上的交易虽被报告为已完成但尚未最终确定，或付款是在订单被取消之后到达的。备注会说明原因。如果付款币种与订单币种相同，则订单中会记录实际支付的金额。存在不符的交易永远不会在之后为订单付款；尚未最终确定的交易，会在 MakeCommerce 报告其已完成时完成订单。请在 Merchant Portal 中检查该交易，然后处理订单或退还付款。
Refunded： 付款已通过模块全额退款。
如果已付款的订单又收到第二笔付款，订单不会改变。备注会提醒您在 MakeCommerce Merchant Portal 中退还重复付款。
MakeCommerce 付款区块
订单页面会显示 MakeCommerce payment 区块，其中包含该购物车的所有 MakeCommerce 交易（日期、交易 ID、测试付款的 Test 标记、金额、MakeCommerce 状态和结果）、已付和已退金额、退款记录以及订单的 MakeCommerce notes。该区块的按钮只需要编辑订单的权限，不需要模块的访问权限。
Check MakeCommerce payment status： 向 MakeCommerce API 查询该购物车交易的状态（最新的排在最前），应用该状态并添加一条包含结果的备注。当顾客表示已付款但订单未完成时使用此功能。
退款
在 MakeCommerce payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 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。部分退款不会改变状态。只有在 MakeCommerce 确认付款后才能退款。
本模块不会生成退款凭证。订单页面上标准的 PrestaShop 退款按钮不会通过 MakeCommerce 退款。
在 Merchant Portal 中完成的退款会附带交易状态，并添加到备注中。订单状态和退款凭证不会自动更改。
许可证密钥
模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox MakeCommerce Payment 许可证区块是 Modules > Module Manager > VibeFox MakeCommerce Payment > Configure 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now 用于再次检查状态，Change key 用于输入其他密钥，Remove key 用于从本店铺中删除该密钥。其下方有一行 Product: presta-payment-makecommerce 和链接 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 账户中释放该名额。
没有有效密钥时，结账页面不会向顾客显示 MakeCommerce。如果仍然开始了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该支付方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已开始的付款仍会被确认，退款也可以正常进行。
许可证过期后，模块仍会继续运行，但更新和支持需要续费。在后台工作时会自动再次检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账页面中没有 MakeCommerce： 请检查许可证是否有效、Enable/Disable 是否开启，以及当前环境是否已设置密钥：测试模式需要 Test Shop ID 和 Test Secret key，正式模式需要 Live Shop ID 和 Live Secret key。检查购物车货币的小数位是否不超过两位。在 Payment > Preferences 中检查模块是否允许用于该购物车货币、顾客所在国家以及顾客组。
付款已完成，但未创建订单： 通知无法到达商店，例如由于防火墙或基本身份验证。当顾客返回商店或点击 Check again 时，订单也会被创建。请检查付款所在环境的密钥是否已设置：通知会使用该环境的 Secret key 进行验证，没有它，MakeCommerce 会收到错误并重试。开启 Debug log 可查看通知。
订单处于 MakeCommerce payment on hold 状态： 请阅读订单页面区块中的 MakeCommerce notes（参见订单状态），在 Merchant Portal 中检查该交易，然后处理订单或退还付款。
通知被拒绝： 签名错误、属于其他购物车、其他商店，或并非为该购物车创建的交易的消息会被拒绝，且不会更改任何内容。请检查 Shop ID 和 Secret key 是否属于同一 MakeCommerce 账户和环境。
顾客在选择 MakeCommerce 时看到错误： 开启 Debug log，并查看模块页面上的 Log 字段。MakeCommerce 无法收款的货币会显示 MakeCommerce cannot process payments in 以及货币代码。
退款因环境相关的信息失败： 订单是在测试或正式环境中付款的，而该环境的密钥未配置。请输入这些密钥后重试。
退款因 No MakeCommerce transaction ID found for this order 失败： 该订单没有已确认的 MakeCommerce 付款。请在 Merchant Portal 中退款。
卸载
进入 Modules > Module Manager，打开 VibeFox MakeCommerce Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。MakeCommerce 交易和退款，以及 MakeCommerce payment on hold 订单状态始终会保留，因此此前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
MakeCommerce 是其各自所有者的商标。本模块与 MakeCommerce 无关联，也未获得 MakeCommerce 的认可。