VibeFox Comgate for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

互联网访问：您的商店必须可以从互联网访问，通知 URL 前面不能有维护页面、防火墙或密码保护，以便 Comgate 能够发送后台通知。

货币：CZK、EUR、PLN、HUF、USD、GBP、RON、HRK、NOK 或 SEK。对于其他货币，以及低于 Comgate 最低金额的总额（例如 1 CZK、0.10 EUR 或 100 HUF），付款方式将被隐藏。按照 Comgate 的要求，HUF 付款会四舍五入为整数福林。

Comgate 账户：您需要在 Comgate 客户门户中获取商店连接的 Merchant ID 和 secret（后台通信密码），并在那里设置通知 URL（参见配置）。Comgate 对测试付款和正式付款使用相同的 Merchant ID 和 secret。

VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。

安装

下载包是一个 zip 文件，内含适用于两个 OpenCart 版本的安装包。请解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_comgate_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_comgate_gateway.ocmod.zip。只安装适用于您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

4. 从 Comgate 客户门户中输入 Merchant ID 和 Secret，并在那里设置通知 URL（参见配置）。

5. 开启 Enable / Disable，然后点击 Save。进行试付时保持 Test Mode 开启，之后再关闭。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥、Comgate 凭据和通知 URL。设置页面及其字段在两个版本中相同。只有通知 URL 和返回 URL 不同（参见配置）。

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Comgate Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，当 Comgate 已启用但缺少 Merchant ID 或 secret 时（此时支付方式会在结账时隐藏，直到两者都已填写），以及商店的默认货币不受 Comgate 支持时，页面会发出警告。测试模式开启时，页面会显示 Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live. 没有修改扩展的权限时，页面只显示设置，无法保存。

保存时，Title 不能为空（最多 128 个字符），Sort Order 必须为整数，Total 不能为负数，并且所选的地理区域和订单状态必须存在。如果任何检查失败，则不会保存任何内容，页面会列出错误。

Comgate

Enable / Disable：Enable Comgate Payment Gateway 用于开启或关闭该支付方式。默认：关闭。

Title：顾客在结账时看到的支付方式名称。它也是订单中保存的支付方式名称。默认：Comgate。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方向顾客显示的文字。默认：Pay securely via Comgate — cards, bank transfers, wallets and more。测试模式下会在其后添加 TEST MODE: no real money is charged.；如果描述为空，则单独显示该提示。

Sort Order：Comgate 在结账时支付方式中的排列位置。留空或输入整数。

Geo Zone：仅对所选地理区域内的付款地址提供 Comgate。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单必须达到的结账总额（以商店默认货币计算），才会提供 Comgate。留空则对任何总额都提供 Comgate。该货币的 Comgate 最低金额始终适用。

Comgate 连接

从 Comgate 客户门户的 Integration > shop connection settings 中获取商店标识（Merchant ID）和密码（secret）（该页面会链接到门户）。在同一位置，将 URL for passing the payment result（后台通知）设置为本节 Notification URL 中显示的 URL。该 URL 在 OpenCart 3 中形如 https://your-store/index.php?route=extension/payment/wcp_comgate_gateway/notify，在 OpenCart 4 中形如 https://your-store/index.php?route=extension/wcp_comgate_gateway/payment/wcp_comgate_gateway.notify，由您的 OpenCart 安装的商店前台地址生成。请完全按照设置中显示的内容复制该 URL。Comgate 会在每笔付款后调用它；随后扩展会通过 Comgate 状态 API 重新核实付款，然后才会更改订单。每笔付款都会发送顾客的返回 URL。如果门户还要求填写返回 URL（已付款、已取消、待处理），请使用本节中第二个 URL，它以 back&id=${id}&refId=${refId} 结尾（OpenCart 4 中为 wcp_comgate_gateway.back&id=${id}&refId=${refId}）。

Merchant ID：Comgate 电子商店标识（merchant）。

Secret：本商店连接的后台通信密码（secret）。已保存的 secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有需要更改时才输入新值。若要删除已保存的 secret，请勾选字段下方的 Clear the saved secret，然后点击 Save。

Test Mode：创建测试付款（不会扣款）。Comgate 对测试和正式付款使用相同的 Merchant ID 和 secret；测试付款会以 test=true 标记。退款始终以原始付款的模式发送。默认：开启。

付款页面

Payment Methods：顾客可以选择的 Comgate 支付方式。仅显示在 Comgate 中为您的商店启用的方式。

Language：Comgate 付款页面的语言。Automatic (store language, English as fallback)（默认）或 26 种语言之一。

订单

OpenCart 在 Confirm Order 步骤创建订单，此时订单没有状态（即缺失订单）。只有在 Comgate 确认付款后（通过后台通知，或顾客返回时），订单才会获得状态；状态始终从 Comgate 状态 API 读取。以下每个字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：Comgate 确认付款时设置的状态。默认：处理中。

Comgate Payment On Hold Status：与订单不符的付款、正式模式下的测试付款以及预授权付款。备注会说明原因。默认：待付款，因为 OpenCart 没有保留状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Payment Canceled Status：预授权订单的 Comgate 付款已被取消或已过期。默认：已取消。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug Log：将 API 请求和通知写入 OpenCart 日志文件夹（storage/logs）中的 comgate_p_debug.log.php。该文件无法通过网页打开。secret 和个人数据永远不会被记录。即使关闭，错误也始终会被记录。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载扩展会删除网关设置和日志。订单及其 Comgate 交易编号始终保留。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择支付方式（默认为 Comgate）。在 Confirm Order 步骤中，顾客会看到您的描述以及提示 You will be redirected to the secure Comgate payment page. OpenCart 在此步骤创建订单，此时仍没有状态。当顾客点击 Confirm Order 时，扩展会在 Comgate 上以订单货币为订单总额创建付款，并将顾客带到 Comgate 付款页面。顾客的电子邮件和姓名会传递给 Comgate，付款会标注为 Order 和订单号。需要有效的电子邮件地址。在 Comgate 页面上，顾客使用您允许的付款方式之一完成付款。在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。如果商店不要求付款地址（OpenCart 4 默认设置），则会将收货地址的国家传递给 Comgate。

付款后，顾客会返回您的商店。只有在 Comgate 确认后，订单才会被标记为已付款：扩展会从 Comgate 状态 API 读取付款信息，无论后台通知何时到达，或顾客何时返回。随后，订单会按照 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存；顾客会看到 OpenCart 订单成功页面。如果订单被置于保留状态，页面还会添加 Your payment is being reviewed. We will contact you if anything else is needed. 在 OpenCart 4 中，顾客返回时浏览器不会发送商店会话，因此扩展会先显示一个短暂页面，从您的商店重新打开相同的返回地址：顾客保留购物车和登录状态。

如果顾客返回时付款尚未确认（例如银行转账正在途中），Payment confirmation 页面会显示 Comgate has not confirmed your payment yet. Your order will be confirmed automatically as soon as the payment is confirmed — please do not pay again.，并带有 Check again 按钮和 Back to checkout 按钮。

如果付款被取消或过期，顾客会返回结账页面，并显示 The Comgate payment was cancelled or has expired. You can try again or choose another payment method. 在 OpenCart 4 中，结账消息会显示在结账页面上方。购物车会被保留。每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建新订单，OpenCart 4 则为结账保留一个订单并进行更新）会先在 Comgate 上检查该购物车的早前尝试。如果其中一次已付款，则该订单会被确认，顾客会进入成功页面而不会被二次扣款；未完成的尝试会在 Comgate 上被取消。较早尝试的延迟付款仍会被识别，并确认其订单。已被其他订单付款的购物车不会再次扣款：顾客会进入成功页面。

在 OpenCart 4 中，订单会一直保留在结账中，直到显示成功页面。如果该订单在此期间被取消而未付款，Confirm Order 会将顾客带回结账页面，并显示有关已取消付款的消息。如果订单以其他方式关闭（例如已退款或付款后被取消），消息为 Your previous order is closed (cancelled or refunded). Please confirm the order again: the cart will be paid with a new order. 在这两种情况下，下一次点击 Confirm Order 都会为购物车支付一个新订单。如果订单已付款，且购物车此后已发生变化（其他商品或数量），顾客会被送回结账页面，变更后的购物车将获得新订单及其自己的付款。

如果 Comgate 无法启动付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到一条简短消息，例如 The Comgate payment could not be started. Please try again or choose another payment method.，表示 Comgate 不接受该金额或货币，或所选的 Comgate 付款方式不可用。技术原因会写入日志。

即使商店处于维护模式，通知也能正常工作，：OpenCart 3 会放行付款扩展的请求，在 OpenCart 4 中，扩展会添加一个启动操作，允许通知和顾客返回通过。

本扩展仅在 Comgate 页面上处理一次性付款。它不支持定期付款、订阅或保存的银行卡，不支持嵌入式 Comgate 结账，不在您的网站上提供 Apple Pay 或 Google Pay 按钮（这些功能可在 Comgate 页面上使用），也不支持从 OpenCart 捕获或取消预授权。如果没有通知，付款状态不会自动轮询；只有在顾客返回时才会检查。

订单与退款

订单状态

无状态（缺失订单）：顾客已被发送到 Comgate 但尚未付款，付款已取消，或 Comgate 将其报告为待处理。在 Sales > Orders 中，这些订单仅在 Order Status 筛选器设置为 Missing Orders 时显示。

Order Status After Payment (default Processing)：Comgate 以相同金额和货币将付款报告为 PAID。备注会显示 Comgate 交易和金额。测试付款会收到备注 Comgate test payment — no money was charged.

Comgate Payment On Hold Status (default Pending)：已付金额或货币与订单不符，商店处于正式模式时确认了一笔测试付款（未收到任何款项），或付款仅为授权（Comgate 账户中的预授权）。已授权的付款在您于 Comgate 门户中捕获后会自动变为已付款。备注会说明原因。

Payment Canceled Status (default Canceled)：已授权的付款在 Comgate 上被取消或已过期。如果之后 Comgate 确认了该付款，订单会以已付款状态重新打开，并附带备注提醒您在发货前检查库存。

Refunded Status (default Refunded)：付款已通过本扩展全额退款。

如果 Comgate 为一个已付款的订单报告了另一笔 PAID 付款，订单不会被更改。备注会要求您在 Comgate 门户中检查并退还重复付款。如果同一购物车又与另一个订单一起付款（例如同时在两个浏览器标签页中），该订单将不会获得状态，已付款的订单会收到此备注。如果一笔付款到达的订单，其状态在此期间已被您更改，则不会改动状态，并且备注会要求您检查该订单。重复的确认绝不会重新打开已退款的订单。

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

VibeFox Comgate Gateway tab

在 Sales > Orders 中打开一笔通过 Comgate 付款的订单。在订单页面底部，紧挨着 History 和 Additional 的位置，VibeFox Comgate Gateway 标签页会显示 Comgate transaction (transId)（测试付款会带有 Test mode 标签）、Status、Payment amount、Order total / refunded、复核原因、退款表单、退款记录以及该订单的 Comgate notes。该标签页仅显示给有权访问本扩展的用户。

退款

在 VibeFox Comgate Gateway 标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Comgate。确认提示 Refund this amount through Comgate? This cannot be undone. 支持全额和部分退款。您需要具有修改扩展的权限（在 System > Users > User Groups 中设置），并且必须已设置 Merchant ID 和 secret。退款会关联到已付款的 Comgate 交易，并以原始付款的模式（测试或正式）发送。Comgate 仅对 PAID 付款退款，且退款金额不超过已付金额；HUF 退款必须为整数福林。如果 Comgate 不接受退款，标签页会显示错误，并且不会记录任何退款。成功的退款会连同金额、Comgate 交易和原因一起添加到退款记录和备注中。全额退款会将订单设为 Refunded Status，且不通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。

退款仅适用于已付款的订单。因金额或货币不符而置于保留状态的订单无法从 OpenCart 退款，请在 Comgate 门户中退款。Sales > Returns 中的商品退货不会通过 Comgate 退还资金。在 Comgate 门户中进行的退款不会回传给商店。

许可证密钥

本扩展需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox Comgate Gateway 是 Extensions > Extensions > Payments > VibeFox Comgate Gateway > Edit 中位于设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方是 Product: opencart-payment-comgate 一行，以及打开您 vibefox.net 账户的 Manage licenses and domains in your account 链接。只有对本扩展拥有 Modify 权限的管理员用户才能更改密钥。区块中的文字遵循后台语言（包括英文和俄文）。

如果密钥未被接受，区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached 或 License expired on 加日期。更改商店地址后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，扩展将继续使用最后一次已知的状态运行。

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 Comgate。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍能在商店中看到该支付方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 中，此预览不可用：商店看不到后台登录，因此在没有有效密钥的情况下，支付方式对所有人都隐藏。打开一次 Edit 页面后，后台的 Dashboard 上会出现提醒。点击 × 关闭，可隐藏 7 天。现有订单不受影响：已发起的付款仍会被确认，退款也可以正常进行。

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

故障排除

Comgate does not appear at checkout：请检查许可证是否有效、Enable / Disable 是否开启、Merchant ID 和 Secret 是否已填写、结账货币是否受支持，以及订单总额是否不低于 Comgate 的最低金额（例如 1 CZK、0.10 EUR 或 100 HUF）。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单金额是否达到设置中的 Total。

The payment went through, but the order stays without a status：Comgate 没有送达后台通知。请检查 Comgate 门户中的 URL for passing the payment result（必须与设置中的 Notification URL 完全一致）、您的商店是否可以从互联网访问，并查看日志（开启 Debug Log）。Comgate 会重发未送达的通知；只要扩展未能处理某个通知，它就会返回错误，因此该通知会被重试。顾客返回商店时，订单也会获得状态。

Notification answers Invalid merchant or secret：设置中的 Merchant ID 或 secret 与 Comgate 门户中的商店连接不匹配。

Notification answers Gateway not configured：设置中的 Merchant ID 或 secret 为空。填写后 Comgate 会重试。

Notification answers Unknown transaction, Order not found or Reference mismatch：该通知属于一笔并非由本商店为该订单创建的付款。不会更改任何内容。

Notification answers Status verification failed, Status verification rejected or Busy, retry later：无法连接 Comgate 状态 API，它拒绝了请求，或订单在同一时刻正被另一请求处理。当订单状态无法设置时，也会返回 Busy；原因记录在日志中。Comgate 会重试通知。

The notification URL shows code=1&message=POST%20required in the browser：这是正常现象。该 URL 只接受来自 Comgate 的请求。

The customer sees We could not verify the Comgate payment：返回链接与订单不匹配。如果已扣款，通知仍会确认订单。请在顾客再次付款之前，在 Comgate 门户中核实付款。

The customer sees This payment method is not available. Please reload the checkout page.：结账会话与订单不再匹配，或支付方式在此期间已被关闭。顾客重新加载结账页面即可。

The customer sees The order total is below the minimum amount accepted by Comgate or A valid billing e-mail address is required for Comgate payments：订单按目前的状态无法使用 Comgate 付款。

Order is in the on-hold status after payment：阅读 VibeFox Comgate Gateway 标签页中的备注。已付金额或货币不一致，正式模式下收到了测试付款，或付款仅为授权。请在 Comgate 门户中核实付款，然后手动完成或退款该订单。

No refund form in the tab：标签页会说明原因：订单没有已确认的 Comgate 付款，已全额退款，您的用户组没有修改扩展的权限，或未设置 Merchant ID 和 secret。

Refund fails：阅读标签页中的消息。Comgate rejected the refund: the amount exceeds the refundable amount. 表示退款金额超过了剩余可退金额；状态不是 PAID 的付款无法退款。Comgate could not be reached. The refund was not made — please try again later. 表示连接问题。

面向开发人员：OpenCart 事件 comgate_p_currencies（支持的货币及其最低金额）和 comgate_p_create_params（Comgate 付款和订单的参数）允许其他扩展更改这些内容。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Comgate Gateway 旁边的 Uninstall（红色 − 按钮）。本扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable / Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装时会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，还包括其事件以及在维护模式下放行 Comgate 的启动操作）。如果 Delete Data on Uninstall 已开启，其余网关设置（标题、描述、Merchant ID、secret、测试模式、付款页面、日志记录）和日志将被删除；如果关闭，则保留这些设置，以便日后重新安装时使用。Comgate 交易和退款始终会保留，因此重新安装后仍可对之前已付款的订单退款。现有订单会保留其付款备注。

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

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