VibeFox Montonio for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。
货币：购物车货币必须为 EUR 或 PLN。使用其他货币时，结账时会隐藏该付款方式。
Montonio 账户：您需要 Montonio Partner System 中店铺的访问密钥和私钥。沙盒密钥和正式密钥不同，因此每种您使用的环境都需要一对密钥。在 Montonio 中无需其他设置：通知地址会随每笔付款一同发送。
公网站点：您的店铺必须能从互联网访问，才能接收 Montonio 通知。否则，当顾客返回店铺时订单仍会被创建。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Montonio Payment，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见“许可证密钥”）。
4. 在 Montonio Partner System 中打开 Stores > your store > API keys，复制沙盒访问密钥和私钥。将其粘贴到设置中，并保持 Sandbox mode 开启。
5. 开启 Enable/Disable，点击 Save，并在沙盒中测试一笔付款。然后输入正式密钥，并关闭 Sandbox mode。
安装时，模块会创建订单状态 Montonio payment on hold。PrestaShop 会为所有货币、国家和客户组提供一个新的付款模块。您可以在 Payment > Preferences 中对其进行限制。
配置
所有设置都位于模块页面：Modules > Module Manager > VibeFox Montonio Payment > Configure。每个部分都有自己的 Save 按钮，它会保存整个页面。在字段上方，当当前环境的密钥缺失（此时结账时会隐藏该付款方式）、店铺货币不是 EUR 或 PLN 时，页面会发出警告；沙盒开启时，页面还会显示 Sandbox mode is on: payments are simulated and no real money is charged.。Title 不能为空。
Montonio
Enable/Disable：Enable Montonio bank payments 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Bank payment (Montonio)。必填。
Description：结账时付款方式下方显示的文字。默认：Pay directly from your bank account. You will be redirected to Montonio to choose your bank.
API 密钥
请在 Montonio Partner System 的 Stores > your store > API keys 中获取密钥。沙盒密钥和正式密钥不同。沙盒仅使用沙盒密钥，正式模式仅使用正式密钥。
Sandbox mode：使用 Montonio 沙盒（测试付款，不会扣除真实资金）。它会同时切换 Montonio API 地址和密钥对。默认：开启。仅在输入正式密钥后再将其关闭。在另一种环境中完成的付款，在确认和退款时仍使用其所属环境的密钥。
Sandbox access key：您的店铺在 Montonio 沙盒中的访问密钥（UUID）。
Sandbox secret key：您的店铺在 Montonio 沙盒中的私钥。
Live access key：您的店铺在 Montonio 正式环境中的访问密钥（UUID）。
Live secret key：您的店铺在 Montonio 正式环境中的私钥。
已保存的私钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 仅在需要更改时才输入新值。
Clear saved secret keys：勾选某个密钥并点击 Save 即可将其删除。字段为空时保留已保存的值。
Notification URL：Montonio 发送付款通知的地址。在使用友好 URL 时，其形式如下：https://your-shop/module/wcp_montonio_payment/webhook。您无需在任何地方输入它：模块会在每笔付款时将其发送给 Montonio。
高级
Debug log：将付款事件写入模块文件夹中的 logs/wc_mnt_debug.log.php。该文件无法通过网页打开。即使此选项关闭，错误和警告也始终会被记录。密钥、令牌和顾客数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data：开启时，卸载模块会删除模块设置及其日志。禁用模块不会删除任何内容。订单数据（Montonio UUID、备注）始终保留。默认：关闭。
付款通知
Montonio 通过已签名的令牌告知您的店铺每笔付款。令牌有两种送达方式：通过服务器间通知发送到通知地址，以及顾客返回店铺时随其一同送达。两者都会进行检查：使用创建付款所在环境的私钥进行签名验证、有效期、您的访问密钥，以及该付款是否为您的店铺针对该购物车所创建。使用另一环境密钥签名的令牌会被拒绝。每个状态只会应用一次，因此重复的通知不会添加备注、电子邮件或库存变动。即使店铺处于维护模式，通知地址仍可正常工作，并且不受店铺国家限制的影响。
结账
在付款步骤中，顾客选择付款方式（默认为 Bank payment (Montonio)）并确认。模块会以购物车货币为购物车总额创建一笔 Montonio 付款，并将顾客引导至 Montonio 付款页面。在那里，顾客选择银行并付款。顾客账单国家的银行优先显示（PLN 购物车则为波兰）。付款显示为 Order 和购物车编号。若店铺语言为德语、英语、爱沙尼亚语、芬兰语、立陶宛语、拉脱维亚语、波兰语或俄语，Montonio 页面将以该语言打开，否则以英语打开。在沙盒模式下，结账时会在描述下方显示 SANDBOX MODE — test payment, no real money is charged.。此时尚未创建订单。
只有在 Montonio 确认付款后（通过通知或顾客返回时），订单才会被标记为已付款。随后订单被创建，顾客会看到标准订单确认页面，其中显示 Your Montonio bank payment has been received. 如果银行尚未确认付款，或订单处于保留状态，页面会显示 We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. 如果银行之后拒绝了已授权的付款，页面会显示 Your Montonio payment was not completed. Please contact us about this order.
如果顾客返回时 Montonio 报告付款仍处于待处理状态，将显示 Payment confirmation 页面，其中包含相同的文字和 Check again 按钮。该按钮会向 Montonio 查询付款的当前状态。通知一到达，订单就会被创建。
如果付款被取消或拒绝，顾客会返回结账页面，并看到以下任一消息：The payment was cancelled or rejected by the bank. You can try again or choose another payment method.、The payment was not completed. You can try again or choose another payment method. 或 Montonio could not complete the payment. Please try again or choose another payment method. 购物车会被保留。在创建新付款之前，模块会向 Montonio 查询之前的付款。如果已经付款，则会创建订单，并且不会再进行第二次付款。
如果 Montonio 无法发起付款，顾客会留在结账页面，并看到一条简短消息，例如 Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. 技术原因会写入日志。
本模块仅接受银行付款（付款发起）。不支持银行卡付款、BLIK、Apple Pay 或 Google Pay、先买后付或分期融资、Montonio 配送、订阅、已保存的付款方式，也不支持在您自己的网站上选择银行。
订单与退款
订单状态
No order yet：顾客已被引导至 Montonio，但尚未付款，或 Montonio 报告付款处于待处理状态。此时只存在购物车。
Payment accepted：Montonio 以购物车的准确金额和币种确认了付款（PAID）。付款会以 Montonio 订单 UUID 作为交易 ID 进行记录，备注中会显示银行、UUID、金额和环境。
Montonio payment on hold：银行尚未确认付款（AUTHORIZED）；当 Montonio 报告 PAID 时，订单会变为 Payment accepted。当 Montonio 报告的金额或币种与购物车总额不同、沙盒付款在店铺处于正式模式时到达（由于未收到款项，因此不会记录付款）、或付款在订单被取消后才到达时，订单也会被置于保留状态。备注会对此作出说明。请在 Montonio Partner System 中核实付款，然后处理订单或退款。
Payment error：银行拒绝了已授权的付款，或顾客未完成付款。只有购物车的最新付款才能更改订单。
Refunded：付款已通过模块全额退款。
已付款、已取消或已退款的订单不会因后续通知而重新打开。如果已付款的订单又收到第二笔付款，订单不会被更改。备注会提醒您在 Montonio Partner System 中退还第二笔付款。
Montonio payment 区块
订单页面会显示一个 Montonio payment 区块，其中包含 Montonio 订单 UUID、环境（测试付款会带有 Sandbox 标记）、银行、付款状态、已付款和已退款金额、退款记录，以及订单的 Montonio notes。
退款
在 Montonio payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因（仅保存在订单备注中），然后点击 Refund via Montonio。确认提示 Refund this amount through Montonio? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面的权限。退款金额以 Montonio 实际扣款金额为限，因此在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。退款会发送至付款所在的环境（沙盒或正式），因此必须设置该环境的密钥。如果 Montonio 不接受退款，区块会显示错误，且不会记录任何退款。已发送的退款会连同其状态和 Montonio 退款 ID 一起添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。Montonio 报告付款已付款后，才能进行退款。
之后，Montonio 会通过通知确认或拒绝每笔退款。确认会添加到备注中。如果 Montonio 拒绝退款，备注会说明款项未退还给顾客；请在 Montonio Partner System 中核实，并在 PrestaShop 中更正退款。
模块不会创建退款单（credit slip）。订单页面上标准的 PrestaShop 退款按钮不会通过 Montonio 退还款项。在 Montonio Partner System 中进行的退款，会在 Montonio 报告时添加到备注中。订单状态和退款单不会自动更改。如有需要，请手动更新。
许可证密钥
本模块需要使用来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Montonio Payment 许可证区块是 Modules > Module Manager > VibeFox Montonio Payment > Configure 页面顶部、设置上方的第一个区块。将密钥输入 License key 字段并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方是 Product: presta-payment-montonio 一行和 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 账户中释放该名额。
如果没有有效的密钥，结账时顾客将看不到 Montonio。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。Modules > Module Manager 中的 Alerts 标签页会出现一条提醒。现有订单不受影响：已发起的付款仍会被确认，退款也仍可进行。
许可证到期后，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间会自动重新检查状态：密钥输入后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块时，始终会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Montonio：请检查许可证是否有效、Enable/Disable 是否开启、当前环境的两个密钥是否均已设置（沙盒模式下为 Sandbox access key 和 Sandbox secret key，正式模式下为 Live access key 和 Live secret key），以及购物车货币是否为 EUR 或 PLN。当密钥缺失或店铺货币不受支持时，设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许用于购物车货币、顾客所在国家和顾客所在客户组。
付款已完成，但未创建订单：通知未到达您的店铺。请检查店铺能否从互联网访问，以及设置中的密钥是否属于付款所在的环境。顾客在付款后返回店铺、点击 Check again，以及顾客尝试再次支付同一购物车时，也会创建订单。
通知返回 Invalid token：令牌签名、有效期或访问密钥不匹配。请检查访问密钥和私钥是否复制正确、是否属于正确的环境，以及服务器时间是否正确。使用另一环境密钥签名的令牌同样会被拒绝。
通知返回 Payment does not belong to this order：该付款不是由本店铺为此购物车创建的。当两个店铺使用同一 Montonio 账户和相同的购物车编号时，就会出现这种情况。
通知返回 Gateway not configured：未设置任何 Montonio 密钥，或缺少该付款所在环境的密钥。请输入密钥；Montonio 会重试通知。
通知返回 Temporarily unavailable：购物车在同一时刻正被另一请求确认，或订单无法创建（例如模块已禁用）。Montonio 会重试通知。请查看 Log 字段了解原因。
顾客选择 Montonio 时看到错误：请查看模块页面上的 Log 字段。This payment method is temporarily unavailable. Please choose another payment method. 通常表示密钥错误或缺失。Montonio could not start the payment. Please check your order details or choose another payment method. 表示 Montonio 拒绝了付款数据；原因记录在日志中。
付款后订单处于 Montonio payment on hold 状态：请阅读 Montonio payment 区块中的备注（参见订单状态），然后处理订单或退款。
沙盒付款不会确认正式订单：当店铺处于正式模式时，沙盒付款绝不会完成订单；订单会被置于保留状态。请将 Sandbox mode 切换到您需要的环境，并使用该环境的密钥。
退款因环境相关消息失败：付款是在沙盒或正式环境中完成的，而该环境的密钥未设置。请输入密钥后重试。
对于开发人员，本模块提供以下钩子：actionWcpMontonioSupportedCurrencies、actionWcpMontonioOrderData 和 actionWcpMontonioLocale，用于更改支持的货币、付款数据以及 Montonio 页面语言。
卸载
进入 Modules > Module Manager，打开 VibeFox Montonio Payment 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便以后重新安装。Montonio 付款和退款记录以及 Montonio payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单保留其付款备注和交易 ID。
Montonio 是其各自所有者的商标。本模块与 Montonio 无关联，也未获得 Montonio 的认可。