VibeFox Moneris for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本，并启用 SimpleXML 扩展。模块会拒绝在较旧的 PHP 版本或未启用 SimpleXML 的环境中安装。
商店货币：加拿大 Moneris 账户使用 CAD，旧版 Moneris USA 账户使用 USD。只有当购物车货币与账户货币一致时，才会显示该付款方式。
HTTPS 和 PCI DSS：银行卡号在您的结账页面输入，并经过您的服务器。正式付款需要启用 HTTPS 并符合 PCI DSS SAQ D 标准。如果无法满足，请改用托管付款页面的解决方案。
Moneris 账户：您需要 Moneris Gateway 商店的 Store ID 和 API Token，可在 Moneris Merchant Resource Center > Admin > Store Settings 中找到。测试时，Moneris 的公共测试商店已默认填写。测试凭据和测试卡可在 Moneris 开发者门户中找到。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或之后在模块列表中找到 VibeFox Moneris Gateway，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中的 License key 字段输入您的 VibeFox 许可证密钥，然后点击 Activate（参见许可证密钥）。
4. 选择账户所在国家，并填写 Live Store ID 和 Live API Token。测试模式默认开启，并使用公共测试商店（加拿大为 store5 / yesguy，美国为 monusqa002 / qatoken）。
5. 选择 Purchase 或 Pre-Authorization 以及卡标志，然后开启 Enable / Disable，并点击 Save。
6. 使用 Moneris 测试卡下一个测试订单，然后关闭 Test mode。
安装时，模块会创建两个订单状态：Moneris payment authorized 和 Moneris payment on hold。PrestaShop 默认为所有货币、国家和客户组启用新的付款模块。您可以在 Payment > Preferences 中进行限制。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Moneris Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。测试模式开启时，页面在字段上方显示 Moneris gateway is in TEST MODE. No real charges will be made.。在正式模式下，如果正式字段中包含 Moneris 测试凭据（此时结账页面会隐藏该付款方式），或者商店未启用 SSL，页面会发出警告。如果商店默认货币与 Moneris 账户货币不符，页面也会发出警告；此时该付款方式会在结账页面针对其他货币隐藏。
Moneris
Enable / Disable：Enable Moneris Gateway 用于开启或关闭该付款方式。默认：关闭。
Title：向顾客显示的付款方式标题，也是订单中保存的付款方式名称。默认：Credit card (Moneris)。测试模式下，标题后会添加 (Test Mode)。必填。
Description：结账时显示在银行卡字段上方的文字。默认：Pay securely with your credit card.
Moneris 账户
您的 Store ID 和 API Token 位于 Moneris Merchant Resource Center 的 Admin > Store Settings 中。测试凭据和测试卡位于 Moneris 开发者门户中。该部分提供了两者的链接。
Moneris 账户国家：加拿大账户以 CAD 扣款，美国账户以 USD 扣款。只有当购物车货币匹配时才会显示该付款方式。默认：Canada (CAD)。
Test mode：使用 Moneris QA 网关和测试凭据；不会产生真实扣款。扣款、撤销和退款始终发送到付款时所用的环境。顾客会在银行卡字段上方看到 TEST MODE: use a Moneris test card, no real charges are made.。默认：开启。
Live Store ID：正式环境的 Store ID，例如 monca01234。
Live API Token：正式环境的 API Token。
Test Store ID：Moneris 公共测试商店：store5（加拿大）或 monusqa002（美国）。默认：store5。
Test API Token：公共测试 token：yesguy（加拿大）或 qatoken（美国）。默认：yesguy。
已保存的 API token 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。
Clear saved tokens：勾选某个 token 并点击 Save 即可将其删除。字段留空则保留已保存的值。
付款
Transaction type：银行卡的扣款方式。默认：Purchase。
Card logos：结账时与付款方式一同显示的银行卡品牌：Visa、Mastercard、Discover、American Express、JCB。可接受的品牌取决于您的 Moneris 账户。默认：Visa 和 Mastercard。
高级
Debug log：将 API 请求和响应记录到模块文件夹中的 logs/wc_mng_debug.log.php。该文件无法通过网页打开。银行卡号、CVV、有效期和 API token 均已隐藏。即使关闭此选项，错误仍会始终记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：开启后，卸载模块时会删除网关设置和日志。订单的 Moneris 数据（退款所需）和订单状态始终保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Credit card (Moneris)），并在该选项下方的银行卡表单中输入 Card number、Expiry (MM/YY) 和 Card code (CVC)。这三个字段均为必填。下单时，您的服务器会将银行卡信息连同购物车总额发送至 Moneris，并即时获得结果。没有跳转，也没有 webhook。银行卡数据仅用于此次请求，不会被存储，日志中只显示最后四位数字。
只有根据 Moneris 的批准响应，才会创建订单。顾客随后会看到标准的订单确认页面。使用 Pre-Authorization 时，订单会停留在 Moneris payment authorized，直到您扣款。如果 Moneris 处理的金额与购物车总额不同，或者付款期间购物车发生了变化，订单将以附注的形式创建在 Moneris payment on hold 状态。
如果银行卡被拒绝，顾客会停留在结账页面，看到 Your card was declined 以及 Moneris 给出的原因，可以检查银行卡信息或改用其他银行卡。不会创建订单。如果 Moneris 无法处理请求（例如 Store ID 或 API Token 有误），顾客会看到 The payment could not be processed. Please try again or use another payment method. 原因会写入日志。银行卡信息格式错误时会显示简短的提示，例如 Invalid card number. 或 Invalid card expiry date.，并且不会向 Moneris 发送任何内容。
在付款处理期间进行第二次点击或打开第二个浏览器标签页时，会显示 A payment for this order is already being processed. Please wait a moment and check your order status before trying again. 已有订单的购物车绝不会再次扣款；顾客会被引导至现有订单。
如果 Moneris 无响应（网络错误或超时），模块会使用相同的 Moneris 订单 ID 向 Moneris 发送 Status Check，以确定交易是否已完成。如果 Moneris 没有此类交易，顾客可以再次付款。如果 Status Check 也没有得到响应，订单会以 Moneris 订单 ID 创建在 Moneris payment on hold 状态，并且不会要求顾客第二次付款。
本模块不支持保存银行卡或 Moneris Vault、订阅、Apple Pay、Google Pay 或 Interac Online、Moneris Checkout 或 Hosted Tokenization、3-D Secure、AVS 或 Kount，也不支持多币种定价。
订单与退款
订单状态
No order yet：银行卡被拒绝或未处理。仅存在购物车和日志中的尝试记录。顾客可以再次付款。
Payment accepted：购买已获批准。付款以 Moneris 交易编号作为交易 ID 记录。
Moneris payment authorized：预授权已获批准，等待扣款。目前尚未记录付款。
Moneris payment on hold：处理金额与购物车总额不符，付款期间购物车发生了变化，Moneris 未确认结果，或扣款失败但 PrestaShop 仍写入了已付款状态。备注会说明原因。对于金额不同的购买，付款会以 Moneris 实际处理的金额记录。
Canceled：对于预授权订单，取消会释放预留资金（撤销，即 void）。
Refunded：付款已通过本模块全额退款。
Moneris payment 区块
订单页面会显示 Moneris payment 区块，包括 Moneris 订单 ID、账户国家和模式、测试付款的 Test mode 标志、Trans ID（扣款后还包括预授权的 Trans ID）、交易类型及其状态（未扣款、已扣款或已释放）、收据和卡类型、处理金额、订单总额和已退款金额、退款记录以及订单的 Moneris notes。对于未确认的付款，该区块会要求您在 Merchant Resource Center 中查找 Moneris 订单 ID。区块中的所有操作仅需要编辑订单的权限。
扣款与撤销
要扣款预授权金额，请点击区块中的 Capture payment 并确认；或将订单改为已付款状态，例如付款已接受、已发货或已送达。扣款金额为订单总额减去退款；不能超过授权金额。使用按钮扣款后，订单会变为 Payment accepted，付款以扣款的 Trans ID 记录。如果 Moneris 拒绝扣款，状态不会改变，不会发送已付款邮件，并会有备注说明原因：Status not changed: the Moneris pre-authorization could not be captured，后接原因。Moneris 预授权会在几天后过期，因此请及时扣款。
要释放资金，请点击 Void pre-authorization (cancel order)，或将订单改为 Canceled。将订单改为 Refunded 也会释放未完成的预授权。如果释放失败，备注会提示您在 Merchant Resource Center 中进行释放。
退款
在 Moneris payment 区块中输入金额（会自动填入尚未退款的金额），可选填原因，然后点击 Refund via Moneris。确认提示 Refund this amount through Moneris? This cannot be undone.。支持全额和部分退款。退款以 Moneris 实际扣款金额为上限，因此在出现金额差异后，您最多只能退还顾客实际支付的金额，而不是订单总额。预授权只有在扣款后才能退款；在此之前，请取消订单以释放资金。退款会发送到付款时所用的环境和账户，因此该模式的凭据必须仍然填写。如果 Moneris 不接受退款，区块会显示 Refund failed 及原因，且不会记录任何退款。成功的退款会以 Moneris Trans ID 添加到退款记录和备注中。全额退款会将订单改为 Refunded；部分退款不会改变状态。
本模块不会开具退款单。订单页面中 PrestaShop 的标准退款按钮不会通过 Moneris 退款。
许可证密钥
本模块需要使用 vibefox.net 提供的 VibeFox 许可证密钥。License — VibeFox Moneris Gateway 许可证区块位于 Modules > Module Manager > VibeFox Moneris Gateway > Configure 页面中设置上方的第一个区块。在 License key 中输入密钥并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店中删除该密钥）。其下方有一行 Product: presta-payment-moneris 和链接 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 账户中释放名额。
没有有效密钥时，结账页面不会向顾客显示 Moneris。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也是隐藏的：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 选项卡会出现提醒。现有订单不受影响：先前付款的扣款、撤销和退款仍可正常进行。
许可证过期时，模块仍会继续工作，但更新和支持需要续费。在您使用后台期间，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账页面未显示 Moneris：请检查许可证是否有效、Enable / Disable 是否已开启，以及当前模式是否已填写 Store ID 和 API Token。在正式模式下，正式字段必须填写您的正式凭据，而不是 Moneris 测试凭据。请确认购物车货币与账户货币一致：加拿大为 CAD，美国账户为 USD。在 Payment > Preferences 中，请确认该模块已允许该货币、顾客所在国家和顾客组。
付款已完成，但订单处于 Moneris payment on hold：本模块没有 webhook；结果仅来自 Moneris 的响应。请阅读区块中的 Moneris notes。如果 Moneris 未确认结果，说明 Moneris 未响应，且 Status Check 也失败了。请在 Merchant Resource Center 中查找 Moneris 订单 ID：如果交易存在，请发货（如有需要，可在那里退款）；如果不存在，请取消订单或请顾客重新付款。如果金额不同，请检查订单并处理，或退还付款。
顾客看到 Payment gateway is misconfigured. Please contact the store administrator.：当前模式的凭据缺失，或正式模式已开启但正式字段中填写的是 Moneris 测试凭据。请输入您的正式 Store ID 和 API Token。
顾客看到 This payment method does not support the order currency.：购物车货币不是 Moneris 账户的货币。
顾客付款时出现错误：请查看模块页面上的 Log 字段。错误始终会被记录；开启 Debug log 即可查看完整的请求和响应。
扣款失败：订单没有等待扣款的预授权，订单总额为零，或金额高于授权金额。Moneris 预授权也会在几天后过期。
退款、扣款或撤销失败，并提示模式或账户相关信息：付款是在测试或正式模式下进行的，而该模式的凭据未设置；或者付款是使用另一国家的 Moneris 账户进行的。请填写凭据，或在 Merchant Resource Center 中处理该付款。
卡号测试攻击（card testing）：直接银行卡表单是盗刷测试的目标。请在您的 Moneris 账户中使用 eFraud 或 velocity 规则，并为您的商店使用 CAPTCHA 或限流模块。
卸载
进入 Modules > Module Manager，打开 VibeFox Moneris Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便之后重新安装。Moneris 交易和退款以及订单状态 Moneris payment authorized 和 Moneris payment on hold 始终会保留，因此重新安装后，之前已付款的订单仍可扣款或退款。现有订单会保留其付款备注和交易 ID。
Moneris 是其各自所有者的商标。本模块与 Moneris 无关联，也未获得 Moneris 的认可。