VibeFox Moneris for OpenCart — 帮助

要求

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

PHP：8.0 或更高版本。

货币：加拿大 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 购买。一个密钥只能用于一个域名。

安装

下载文件是一个 zip 压缩包，包含两个 OpenCart 版本的安装包。请先将其解压到电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_moneris_gateway-oc3-(version).ocmod.zip 以及 OpenCart 4 安装包 wcp_moneris_gateway.ocmod.zip。请只安装与您的 OpenCart 版本相符的安装包。两个版本的许可证密钥相同。

OpenCart 3

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

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

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

4. 选择账户国家，并输入 Live Store ID 和 Live API Token。测试模式默认开启，并使用公开的测试商店（加拿大为 store5 / yesguy，美国为 monusqa002 / qatoken）。

5. 选择交易类型和卡品牌标志，然后开启 Enable / Disable 并点击 Save。

6. 使用 Moneris 测试卡下一个测试订单，然后关闭 Test mode。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 6 输入许可证密钥和设置。设置页面及其字段在两个版本中相同。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Moneris Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。测试模式开启时，设置上方会显示 Moneris gateway is in TEST MODE. No real charges will be made. 在实际模式下，如果实际字段包含 Moneris 测试凭据（此时结账时会隐藏该付款方式），或商店未启用 SSL（OpenCart 4 上为商店地址以 http:// 开头时），页面会发出警告。如果付款方式已启用，但当前模式的 Store ID 或 API Token 为空，或者商店的默认货币不是 Moneris 账户的货币，页面也会发出警告；在这两种情况下，结账时都会隐藏该付款方式。如果没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数，Total 必须为 0 或更大的数字。如果某个值有误，页面会显示错误，且不会保存任何内容。

Moneris

Enable / Disable：Enable Moneris Gateway 用于开启或关闭该付款方式。默认：关闭。

Title：显示给顾客的付款方式标题。它也是订单中保存的付款方式名称。默认：信用卡（Moneris）。测试模式下，标题中会添加（Test Mode）。必填。

Description：在 Confirm Order 步骤中、银行卡字段上方显示的文本。默认：Pay securely with your credit card.

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

Geo Zone：仅向所选地理区域内的账单地址显示银行卡表单。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账金额（以商店默认货币计）才会显示该付款方式。留空则对任何金额都显示。

Moneris 账户

您的 Store ID 和 API Token 位于 Moneris Merchant Resource Center 的 Admin > Store Settings 下。测试凭据和测试卡位于 Moneris 开发者门户上。本部分链接到这两处。

Moneris account country：加拿大账户以 CAD 扣款，美国账户以 USD 扣款。只有订单货币与之匹配时，才会显示该付款方式。默认：加拿大（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：公开的测试令牌：yesguy（加拿大）或 qatoken（美国）。默认：yesguy。

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

付款

Transaction type：银行卡的扣款方式。默认：Purchase。

Card logos：结账时与付款方式一同显示的卡品牌：Visa、Mastercard、Discover、American Express、JCB。可接受的品牌取决于您的 Moneris 账户。默认：Visa 和 Mastercard。

订单

OpenCart 会在 Confirm Order 步骤中创建订单，此时订单没有状态（即缺失订单）。只有在 Moneris 作出响应后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：银行卡已扣款（购买，或预授权的捕获）。默认：处理中。

Authorized Status：预授权：资金仅被预留，尚未扣款。可在订单选项卡中捕获，或设为已付款状态。默认：待处理。

On Hold (Review) Status：需要人工审核：Moneris 处理的金额与订单不符，或 Moneris 未作出响应且状态检查也失败（银行卡可能已被扣款）。备注会说明原因。默认：待处理，因为 OpenCart 没有“暂停”状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处和 Authorized Status 中选择。

Canceled Status：由订单选项卡中的 Void pre-authorization (cancel order) 设置。将订单设为此状态会释放（撤销）尚未捕获的预授权。默认：已取消。

Refunded Status：在订单选项卡中将付款全额退款后设置。将订单设为此状态也会释放尚未捕获的预授权。默认：已退款。

高级

Debug log：将 API 请求和响应记录到 OpenCart 日志文件夹（storage/logs）中的 wc_mng_debug.log.php。该文件无法通过网页打开。卡号、CVV、有效期和 API Token 均会被隐藏。即使此选项关闭，错误也始终会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载扩展时会删除网关设置和日志。订单的 Moneris 数据（捕获和退款所需）始终保留。默认：关闭。

导入 / 导出

Export：Download JSON 会将设置保存为 JSON 文件。API Token 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的 API Token 会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Credit card (Moneris)）。在 Confirm Order 步骤中，顾客会看到您的描述、卡品牌标志以及 Card number、Expiry (MM/YY) 和 Card code (CVC) 字段。三个字段均为必填。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式；此时银行卡字段会显示在结账页面底部、Confirm Order 按钮上方的订单确认区块中。顾客点击 Confirm Order 时，您的服务器会将银行卡信息按订单总额发送给 Moneris，并立即获得结果。没有重定向，也没有 Webhook。银行卡数据仅用于这一次请求；绝不会被保存，日志中只显示后四位数字。

只有在收到 Moneris 的批准响应后，订单才会获得状态，其方式与 OpenCart 的常规流程相同，会发送常规订单邮件并更新库存。购物车会被清空，顾客会看到 OpenCart 订单成功页面。使用预授权时，订单会停留在 Authorized Status，直到您捕获资金。如果 Moneris 处理的金额与订单总额不同，订单会获得审核状态并附带备注。

如果银行卡被拒绝，顾客会停留在 Confirm Order 步骤，并看到 Your card was declined 以及 Moneris 给出的原因，可以检查银行卡信息或使用其他银行卡。订单不会保留任何状态；拒付原因也会写入日志。如果 Moneris 无法处理请求（例如 Store ID 或 API Token 错误），顾客会看到 The payment could not be processed. Please try again or use another payment method. 原因会写入日志。银行卡字段填写有误会给出简短提示，例如 Please enter your card details.、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. OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则为结账保留一个订单，银行卡被拒后顾客支付的仍是同一个订单。无论哪种情况，扩展都会将同一购物车的所有订单视为一次付款：已付款或结果未知的购物车绝不会再次扣款，顾客会被引导至成功页面。在显示成功页面之前，OpenCart 4 会将该订单保留在结账流程中。如果该订单已有状态，且购物车中又有了商品（例如付款已完成但未显示成功页面，顾客又添加了商品），或者该订单在此期间被取消、退款或撤销，顾客会被带回结账页面的 Confirm Order 步骤，下一次 Confirm Order 将支付一个新订单。在结账页面上方，若订单已关闭，顾客会看到 This order was cancelled or refunded by the store, so it cannot be paid again. Please check your cart and confirm the new order.；若订单是为之前的购物车付的款，则会看到 This order has already been paid, and your cart now holds a new purchase. Please check your cart and confirm the new order.

如果 Moneris 没有响应（网络错误或超时），扩展会使用相同的 Moneris 订单 ID 向 Moneris 发送状态检查，以确认交易是否已完成。如果 Moneris 没有此类交易，顾客可以再次付款。如果状态检查也没有得到响应，订单会获得审核状态，备注中会注明 Moneris 订单 ID，且不会邀请顾客再次付款。如果付款已完成，但无法设置订单状态，顾客会看到 Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.

该扩展不支持保存的银行卡或 Moneris Vault，不支持订阅、Apple Pay、Google Pay 或 Interac Online，不支持 Moneris Checkout 或 Hosted Tokenization，不支持 3-D Secure、AVS 或 Kount，也不支持多货币定价。

订单与退款

订单状态

无状态（缺失订单）：银行卡被拒绝或未被处理。顾客可以再次付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设置为 Missing Orders 时才会显示。

Order Status After Payment（默认处理中）：购买已获批准，或预授权已被捕获。备注会显示金额、Moneris Trans ID 和收据。

Authorized Status（默认待处理）：预授权已获批准，等待捕获。

On Hold (Review) Status（默认待处理）：处理的金额与订单总额不符，或 Moneris 未确认结果。备注会说明原因。

Canceled Status（默认已取消）：对于已预授权的订单，预留的资金已被释放（撤销）。

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

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

VibeFox Moneris Gateway 选项卡

在 Sales > Orders 中打开一笔通过 Moneris 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Moneris Gateway 选项卡会显示 Trans ID（捕获后还会显示预授权的 Trans ID）、Moneris order ID、Receipt、Transaction type 及其状态（未捕获、已捕获或已释放）、Account / environment（测试付款会带有 Test mode 标签）、Card（含授权码）、Authorized / charged / refunded 金额、捕获、撤销和退款按钮、退款历史以及订单的 Moneris notes。对于未确认的付款，该选项卡会要求您在 Merchant Resource Center 中查找 Moneris 订单 ID。该选项卡会显示给有权访问该扩展的用户；捕获、撤销和退款需要修改扩展的权限（在 System > Users > User Groups 中设置）。

捕获与撤销

要捕获预授权，请在选项卡中点击 Capture payment 并确认 Capture the pre-authorized amount through Moneris?，或使用 Add History 将订单状态更改为已付款状态，例如 Order Status After Payment 或其他 OpenCart 处理中或已完成状态。系统会捕获订单总额减去退款后的金额；金额不能超过预授权金额。通过按钮捕获后，订单会获得 Order Status After Payment。如果 Moneris 拒绝捕获，状态不会改变，不会发送邮件，Add History 会显示原因而不是成功消息，并且备注会说明：Moneris: status not changed — the pre-authorization could not be captured，并附上原因。Moneris 的预授权几天后会过期，因此请及时捕获。

要释放资金，请点击 Void pre-authorization (cancel order) 并确认，或将订单设为 Canceled Status。将订单设为 Refunded Status 也会释放未结的预授权。如果释放失败，备注会提示您在 Merchant Resource Center 中释放。

即使扩展已关闭（但仍安装），这些状态更改也会生效，因此之前进行的预授权仍可被捕获和释放。

退款

在 VibeFox Moneris Gateway 选项卡中输入 Amount（尚未退款的金额会自动填入），可选填写 Reason (optional)，然后点击 Refund via Moneris。确认提问 Refund this amount through Moneris? This cannot be undone. 支持全额和部分退款。退款金额受限于 Moneris 实际扣款的金额；因此，在金额不一致的情况下，您最多只能退还顾客实际支付的金额，而不是订单总额。预授权只有在捕获之后才能退款；在此之前，请撤销它以释放资金。退款会发送到付款时所在的环境和账户，因此该模式的凭据必须仍然填写。如果 Moneris 不接受退款，选项卡会显示 Refund failed 及原因，且不会记录任何退款。成功的退款会连同 Moneris Trans ID 一起添加到退款历史和备注中。全额退款会将订单设为 Refunded Status；部分退款不会改变状态。捕获、撤销和退款会直接更改订单状态，不会通知顾客，也不会将商品退回库存，与手动更改状态相同。

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

许可证密钥

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

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

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

故障排除

结账时不显示 Moneris：请检查许可证是否有效、Enable / Disable 是否已开启，以及当前模式是否有 Store ID 和 API Token。在实际模式下，实际字段必须包含您的正式凭据，而不是 Moneris 测试凭据。检查结账货币是否为账户货币（加拿大为 CAD，美国账户为 USD），付款地址是否位于所选 Geo Zone 中，以及订单金额是否达到设置中的 Total。

付款已完成，但订单处于审核状态：该扩展没有 Webhook；结果仅来自 Moneris 的响应。请阅读选项卡中的 Moneris notes。如果 Moneris 没有确认结果，说明 Moneris 未作出响应，状态检查也失败了。请在 Merchant Resource Center 中查找 Moneris 订单 ID：如果交易在那里存在，请发货（必要时在那里退款）；如果不存在，请取消订单，或请顾客重新付款。如果金额不同，请检查订单并完成处理，或为付款退款。

顾客看到 This payment method is not available. Please reload the checkout page. ：结账会话已与订单不匹配，付款方式在此期间已被关闭，或当前模式的凭据缺失（或实际模式使用了 Moneris 测试凭据）。

顾客看到 This payment method does not support the order currency. ：订单货币不是 Moneris 账户的货币。

顾客付款时出现错误：请查看扩展页面上的 Log 字段。错误始终会被记录；开启 Debug log 可查看完整的请求和响应。

捕获失败：订单没有等待捕获的预授权，订单总额为零，或金额大于预授权金额。此外，Moneris 的预授权几天后也会过期。

退款、捕获或撤销失败，并显示与模式或账户有关的消息：付款是在测试或实际模式下进行的，而该模式的凭据未设置；或者付款是使用另一国家的 Moneris 账户进行的。请输入凭据，或在 Merchant Resource Center 中处理付款。

卡片测试攻击：直接的银行卡表单是卡片测试的目标。请在您的 Moneris 账户中使用 eFraud 或速率规则，并为您的商店使用验证码（CAPTCHA）或限速扩展。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Moneris Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total 以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被移除，因此状态更改不再捕获或释放预授权。如果 Delete data on uninstall 已开启，则其他网关设置（标题、描述、账户国家、测试模式、Store ID 和 API Token、交易类型、卡品牌标志、日志记录）和日志都会被删除。如果关闭，这些设置会保留，以便日后重新安装时使用。Moneris 交易和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可捕获或退款。现有订单会保留其付款备注。

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

Moneris 是其所有者的商标。本扩展与 Moneris 无关联，也未获得 Moneris 的认可。