VibeFox Comgate for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本。在较旧的 PHP 版本上，模块会拒绝安装。

HTTPS：您的店铺必须可通过 HTTPS 从互联网访问，以便 Comgate 能够发送后台通知。

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

Comgate 账户：您需要 Comgate 客户门户中店铺连接的 Merchant ID 和 Secret（后台通信密码），以及在该门户中设置的通知 URL（参见“配置”）。Comgate 对测试付款和正式付款使用相同的 Merchant ID 和 Secret。

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

安装

1. 在后台进入 Modules > Module Manager，点击 Upload a module。选择模块的 ZIP 文件。

2. 上传完成后，点击 Configure，或稍后在模块列表中找到 VibeFox Comgate Gateway 并点击 Configure。

3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥粘贴到 License key 中，然后点击 Activate（参见许可证密钥）。

4. 输入 Comgate 客户门户中的 Merchant ID 和 Secret，并在该门户中设置通知 URL（参见“配置”）。

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

安装时，模块会创建订单状态 Comgate payment on hold。PrestaShop 会为所有货币、国家和客户群组提供一种新的付款模块。您可以在 Payment > Preferences 中进行限制。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Comgate Gateway > Configure。每个部分都有自己的 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.

Comgate

Enable / Disable：Enable Comgate Payment Gateway 用于开启或关闭该付款方式。Default: off。

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。Default: Comgate。必填。

Description：结账时显示在付款方式下方的文字。Default: Pay securely via Comgate — cards, bank transfers, wallets and more。在测试模式下，会在其后添加 TEST MODE: no real money is charged.；如果描述为空，则仅显示该提示。

Comgate 连接

从 Comgate 客户门户的 Integration > shop connection settings 中获取店铺标识（Merchant ID）和密码（Secret）。在同一位置，将 URL for passing the payment result（后台通知）设置为本部分 Notification URL 中显示的 URL。使用友好 URL 时，它的形式为 https://your-shop/module/wcp_comgate_gateway/webhook，可能带有语言代码，例如 /en/。请按设置中显示的内容完整复制该 URL。Comgate 会在每次付款后调用它；模块随后会先通过 Comgate 状态 API 重新核对付款，然后才会做出任何更改。顾客的返回 URL 会随每笔付款一同发送。如果门户还要求设置返回 URL（已付款、已取消、待处理），请使用本部分中显示的第二个 URL，它以 return?id=${id}&refId=${refId} 结尾。

Merchant ID：Comgate 中的店铺标识（商户）。

Secret：此店铺连接的后台通信密码（Secret）。已保存的 Secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

清除已保存的 Secret：勾选该选项并点击 Save，即可删除已保存的 Secret。字段为空时会保留已保存的值。

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

付款页面

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

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

订单

Order Status After Payment：Comgate 确认付款后设置的状态。

与订单不匹配的付款、正式模式下的测试付款以及预授权付款，始终进入 Comgate payment on hold。

高级

Debug Log：将 API 请求和通知写入模块文件夹中的 logs/comgate_p_debug.log.php。该文件无法通过网页打开。密钥和个人数据从不记录。错误始终会被记录。Default: off。

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

Delete Data on Uninstall：开启后，卸载模块时会删除网关设置和日志。订单及其 Comgate 交易 ID 始终保留。Default: off。

结账

在支付步骤中，顾客选择付款方式（默认为 Comgate）并确认订单。模块会按购物车金额和购物车货币在 Comgate 创建付款，并将顾客重定向到 Comgate 付款页面。顾客的电子邮件和姓名会传递给 Comgate，付款会以 Cart 和购物车编号作为标识。必须提供有效的电子邮件地址。在 Comgate 页面上，顾客使用您允许的付款方式之一进行付款。此时尚未生成订单。

付款后，顾客返回您的店铺。只有在 Comgate 确认后，订单才会被标记为已付款：无论后台通知何时到达，还是顾客返回时，模块都会通过 Comgate 状态 API 读取付款信息。随后订单被创建，顾客会看到标准的订单确认页面。如果订单被置于保留状态，页面会添加 Your payment is being reviewed. We will contact you if anything else is needed.。如果预授权订单后来被取消，页面会显示 Your Comgate payment was not completed. Please contact us about this order.

如果顾客返回时付款尚未确认（例如银行转账仍在途中），Payment confirmation 页面会显示 Comgate has not confirmed your payment yet. Your order will be created 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. 购物车会保留。每次新的尝试都会先检查之前的尝试，因此已经成功的付款不会被重复扣款；如果之前的尝试仍处于未完成状态，则会在 Comgate 中取消。较早尝试的延迟付款仍会创建订单。

如果 Comgate 无法发起付款，顾客会停留在结账页面，并看到一条简短提示，例如 The Comgate payment could not be started. Please try again or choose another payment method.，或表示 Comgate 无法接受该金额或货币，或所选的 Comgate 付款方式不可用。技术原因会写入日志。

即使店铺处于维护模式，通知仍会正常工作，并且不受店铺国家限制的影响。

该模块仅在 Comgate 页面上处理一次性付款。它不支持定期付款、订阅或保存银行卡，不支持嵌入式 Comgate 结账页面，您的网站上也没有 Apple Pay 或 Google Pay 按钮（它们可在 Comgate 页面使用），并且不能在 PrestaShop 中捕获或取消预授权。如果没有通知，付款状态不会自动查询，只有在顾客返回时才会检查。

订单与退款

订单状态

尚无订单：顾客已被转到 Comgate 但尚未付款，或 Comgate 将付款报告为待处理。目前只存在购物车。

Payment accepted or Delivered：Comgate 以相同的金额和货币将付款报告为 PAID。状态遵循 Order Status After Payment。付款会以 Comgate 交易 ID 记录。测试付款会添加备注 Comgate test payment — no money was charged.

Comgate payment on hold：已付金额或货币与订单不一致；店铺处于正式模式时确认了测试付款（未收到任何款项）；或付款仅为预授权（Comgate 账户中的预授权）。预授权付款在您于 Comgate 门户中执行扣款后会自动变为已付款。备注会说明原因。

Canceled：预授权付款在 Comgate 中已被取消或已过期。如果此后 Comgate 确认了该付款，订单会以已付款状态重新打开，并附带备注，提示您在发货前检查库存。

Refunded：付款已通过该模块全额退款。

如果 Comgate 对一个已付款的订单报告了另一笔 PAID 付款，订单不会被更改。备注会提醒您在 Comgate 门户中核查并退还重复付款。重放的确认不会重新打开已退款的订单。

Comgate 付款区块

订单页面会显示 Comgate payment 区块，其中包括交易 ID、Comgate 状态、付款金额、订单总额和已退款金额，测试付款会显示 Test mode 标记，此外还有需要审核的原因、退款记录以及订单的 Comgate notes。

退款

在 Comgate payment 区块中输入金额（会自动填入尚未退款的金额），可选择填写原因，然后点击 Refund via Comgate。确认提示 Refund this amount through Comgate? This cannot be undone.。支持全额和部分退款。您需要具有编辑订单的权限；无需访问模块页面。退款会发送到已付款的 Comgate 交易，并以原付款的模式（测试或正式）发送。Comgate 只会退还 PAID 状态的付款，且金额不超过已付金额；HUF 退款必须为整数福林。如果 Comgate 拒绝退款，区块会显示错误，并且不会记录任何退款。退款成功后，会将金额、Comgate 交易和原因添加到退款记录和备注中。全额退款会将订单设为 Refunded。部分退款不会更改状态。

退款仅适用于已付款的订单。因金额或货币不一致而处于保留状态的订单无法在 PrestaShop 中退款，请在 Comgate 门户中退款。模块不会生成贷项凭证。订单页面上标准的 PrestaShop 退款按钮不会通过 Comgate 退回款项。在 Comgate 门户中进行的退款不会回传给店铺。

许可证密钥

该模块需要来自 vibefox.net 的 VibeFox 许可证密钥。License — VibeFox Comgate Gateway 许可证区块位于 Modules > Module Manager > VibeFox Comgate Gateway > Configure 页面的最上方，位于设置之上。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以隐藏形式显示密钥，并显示状态（例如许可证的有效截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本店铺移除密钥）。其下方有 Product: presta-payment-comgate 这一行，以及打开您的 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。区块中的文字遵循后台语言（包含英语和俄语）。

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

一个密钥仅适用于一个域名：主店铺的域名，包括多店铺设置。从店铺中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Comgate。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 前台商店并不知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时进行测试。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响：已经发起的付款仍会被确认，退款也照常可用。

许可证过期后，模块仍会继续运行，但更新和支持需要续订。在后台工作期间会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需设置计划任务。卸载或重置模块时，始终会移除许可证密钥和许可证状态。

故障排除

结账时不显示 Comgate：请检查许可证是否有效、Enable / Disable 是否已开启、Merchant ID 和 Secret 是否已填写、购物车货币是否受支持，以及订单总额是否未低于 Comgate 的最低金额（例如 1 CZK、0.10 EUR 或 100 HUF）。在 Payment > Preferences 中，请检查模块是否允许用于该购物车货币、顾客所在国家和顾客群组。

付款已完成，但未创建订单：Comgate 未能送达后台通知。请检查 Comgate 门户中的 URL for passing the payment result（必须与设置中的 Notification URL 完全一致）、店铺能否通过 HTTPS 从互联网访问，并查看日志（开启 Debug Log）。Comgate 会重发未送达的通知；只要模块未能处理某条通知，它就会返回错误，因此该通知会被再次发送。顾客返回店铺时也会创建订单。

通知返回 Invalid merchant or secret：设置中的 Merchant ID 或 Secret 与 Comgate 门户中的店铺连接不匹配。

通知返回 Gateway not configured：设置中的 Merchant ID 或 Secret 为空。填写后 Comgate 会重试。

通知返回 Unknown transaction、Order not found 或 Reference mismatch：该通知对应的付款并非由本店铺为该购物车创建。不会做任何更改。

通知返回 Status verification failed、Status verification rejected 或 Busy, retry later：无法连接 Comgate 状态 API，或其拒绝了请求，或该购物车在同一时刻正被另一请求处理。当订单无法创建时也会返回 Busy；原因记录在日志中。Comgate 会重试该通知。

通知 URL 在浏览器中显示 code=1&message=POST%20required：这是正常现象。该 URL 只接受来自 Comgate 的请求。

顾客看到 We could not verify the Comgate payment：返回链接与购物车不匹配。如果已经扣款，通知仍会创建订单。请在顾客再次付款前，在 Comgate 门户中核查该付款。

顾客看到 The order total is below the minimum amount accepted by Comgate 或 A valid billing e-mail address is required for Comgate payments：该购物车按现状无法通过 Comgate 付款。

付款后订单处于 Comgate payment on hold：请阅读 Comgate payment 区块中的备注。已付金额或货币不一致、正式模式下收到了测试付款，或付款仅为预授权。请在 Comgate 门户中核查该付款，然后手动完成或退款。

退款失败：请阅读区块中的消息。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. 表示连接问题。

卸载

进入 Modules > Module Manager，打开 VibeFox Comgate Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被移除。如果 Delete Data on Uninstall 已开启，网关设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。Comgate 交易和退款以及订单状态 Comgate payment on hold 始终保留，因此重新安装后，之前已付款的订单仍可退款。现有订单会保留其付款备注和交易 ID。

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