VibeFox Comgate for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：7.0 或更高版本，已安装并启用。未安装时插件无法激活。

PHP：8.0 或更高版本。

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. 在 WordPress 中进入 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件，然后点击 Install Now。您也可以通过 FTP 将 wcp_comgate_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

3. 打开设置：WooCommerce > Settings > Payments > Comgate > Manage，或在插件列表页点击插件名称下方的 Settings。

4. 在页面顶部的许可证区块中输入您的 VibeFox 许可证密钥，然后点击 Activate。

5. 从 Comgate 客户门户中输入 Merchant ID 和 Secret，并在该处设置通知 URL（参见「配置」）。

6. 开启 Enable / Disable。进行试付时保持 Test Mode 开启，之后关闭。

配置

所有设置位于同一页面：WooCommerce > Settings > Payments > Comgate。字段上方，若已启用 Comgate 但缺少 Merchant ID 或 secret，页面会发出警告（在两项都填写之前，该付款方式在结账时隐藏）；若店铺币种不受支持，页面也会发出警告。测试模式开启时，页面会显示 Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

常规

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

Title: 顾客在结账时看到的付款方式名称。默认：Comgate。

Description: 结账时付款方式下方显示的文字。默认：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（后台通知）设为本节显示的地址，形如 https://your-site/wc-api/comgate_payment_callback/。Comgate 会在每笔付款后调用该地址；随后插件会先通过 Comgate 状态 API 重新核对付款，再修改订单。顾客的返回 URL 会随每笔付款一同发送。若门户还要求填写返回 URL（已付款、已取消、待处理），请使用本节显示的第二个地址，形如 https://your-site/wc-api/comgate_payment_return/?id=${id}&refId=${refId}。

Merchant ID: Comgate 店铺标识符（merchant）。

Secret: 该店铺连接的后台通信密码（secret）。

Test Mode: Create test payments (no money is charged)。Comgate 对测试和正式付款使用相同的 Merchant ID 和 secret；测试付款会标记为 test=true。退款始终使用原付款所在的模式发送。默认：开启。

付款页面

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

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

订单

Order Status After Payment: Comgate 确认付款后设置的订单状态。状态会立即设置，无需第二次状态变更。

高级

Debug Log: Log API requests and notifications 写入 WooCommerce > Status > Logs，来源为 wcp_comgate_gateway。secret 和个人数据绝不会被记录。错误始终会被记录。默认：关闭。

Delete Data on Uninstall: Remove the gateway settings and log files when the plugin is deleted。订单及其 Comgate 交易 ID 始终会被保留。默认：关闭。

结账

顾客选择付款方式（默认为 Comgate）并下单。插件会在 Comgate 为订单总额（以订单币种计）创建付款，并将顾客重定向至 Comgate 付款页面。账单电子邮件和姓名会传递给 Comgate，付款将以订单号作为标签。必须提供有效的账单电子邮件地址。在 Comgate 页面中，顾客可使用您允许的任一方式付款。

付款后，顾客返回您的店铺。只有在 Comgate 确认后，订单才会被标记为已付款：无论后台通知到达，还是顾客返回时，插件都会从 Comgate 状态 API 读取付款信息。若付款尚未得到确认（例如银行转账仍在途中），订单已接收页面会显示 Comgate has not confirmed your payment yet. The order will be updated automatically as soon as the payment is confirmed — please do not pay again. 若订单已被设为保留，页面会显示 Your payment is being reviewed. We will contact you if anything else is needed.

若付款被取消或已过期，顾客会返回结账页面（或购物车），并显示 The Comgate payment was cancelled or has expired. You can try again or choose another payment method. 顾客可为未付款的订单重新付款，例如通过 Pay for order 页面。插件会先检查之前的尝试，因此已成功完成的付款不会被重复扣款；若该尝试在 Comgate 中仍处于打开状态，则会被取消。对较早尝试的延迟付款仍会为未付款订单完成付款。

若 Comgate 无法发起付款，顾客会看到简短提示，例如 The Comgate payment could not be started. Please try again or choose another payment method.，或提示 Comgate 无法接受该金额或币种，或所选的 Comgate 付款方式不可用。技术原因会写入日志。

该付款方式支持经典结账、结账区块以及 Pay for order 页面。兼容 WooCommerce 高性能订单存储（HPOS）。

插件仅在 Comgate 页面上处理一次性付款。不支持定期付款、订阅或保存银行卡，不支持嵌入式 Comgate 结账页面，不在您的站点上提供 Apple Pay 或 Google Pay 按钮（这些方式可在 Comgate 页面使用），也不支持在 WooCommerce 中对预授权进行扣款或取消。若没有通知，付款状态不会被自动轮询；仅在顾客返回时进行核对。

订单与退款

订单状态

Pending payment: 顾客已被转到 Comgate，但尚未付款，或 Comgate 将付款报告为待处理。订单备注会显示已创建的 Comgate 付款。

Processing or Completed: Comgate 以相同的金额和币种将付款报告为 PAID。状态遵循 Order Status After Payment 的设置。订单的交易 ID 即为 Comgate 交易 ID；所有尝试均与订单保存在一起。测试付款会附带备注 Comgate test payment — no money was charged.

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

Cancelled: 当前的 Comgate 付款已被取消或已过期。若在 WooCommerce 已取消未付款订单之后，Comgate 才确认付款（例如较慢的银行转账），订单将以已付款状态重新打开，并附带备注提示您在发货前检查库存。

若 Comgate 为已付款的订单报告了另一笔 PAID 付款，订单不会再次被更改。备注会提示您在 Comgate 门户中核对，并退还重复款项。重放的确认绝不会重新打开已退款的订单，或在付款后被取消的订单。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Comgate（按钮显示付款方式名称）。支持全额和部分退款。退款会发送至已付款的 Comgate 交易，并使用原付款所在的模式（测试或正式）发送。Comgate 仅对 PAID 付款办理退款，且退款金额不得超过已付金额；HUF 退款必须为整数福林。若 Comgate 未接受退款，WooCommerce 会显示错误，且不会记录退款。退款成功后，订单备注会添加退款金额、Comgate 交易及退款原因。

在 Comgate 门户中进行的退款不会回传到店铺。如有需要，可在 WooCommerce 中手动创建退款，而不使用该网关的 Refund via 功能。

许可证密钥

本插件需要来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块位于 WooCommerce > Settings > Payments > Comgate 页面顶部。将密钥粘贴到 License key 中，然后点击 Activate。该区块会显示状态，例如许可证有效期截止日期以及您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 将其从本站点移除。链接 Manage licenses and domains in your account 会打开您的 vibefox.net 账户。

一个密钥仅适用于一个域名。从站点移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账时不会向顾客显示 Comgate。若仍发起付款，顾客会看到 This payment method is not available. Please choose another one.。已登录的店铺管理员仍可看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前设置和测试插件。插件页面和 WooCommerce 页面上会显示提醒。现有订单不受影响：已发起的付款仍会被确认，退款也可正常使用。

许可证到期后，插件仍可继续使用，但更新和支持需要续费。系统会在后台自动重新检查状态。

故障排除

结账时未显示 Comgate：请检查许可证是否有效、Enable / Disable 是否开启、Merchant ID 和 Secret 是否已填写、订单币种是否受支持，以及订单总额是否未低于 Comgate 最低金额（例如 1 CZK、0.10 EUR 或 100 HUF）。缺少凭据或币种不受支持时，设置页面会显示警告。

付款已完成，但订单仍为待付款：Comgate 未能送达后台通知。请在 Comgate 门户中检查 URL for passing the payment result，确认您的站点可通过 HTTPS 从互联网访问（未处于维护模式，也未设置密码保护），并查看日志（请开启 Debug Log）。Comgate 会重发未送达的通知；插件在未能处理通知时会返回错误，因此通知会被重试。顾客返回店铺时，订单也会得到确认。

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

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

通知返回 Order not found、Unknown transaction 或 Reference mismatch：该通知所属的付款并非由本店铺为该订单创建。订单不会被更改。

通知返回 Status verification failed、Status verification rejected 或 Busy, retry later：无法连接 Comgate 状态 API，或其拒绝了请求，或订单在同一时刻正被另一请求处理。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 门户中核对该笔付款，然后手动完成订单或退款。

退款失败：请阅读提示。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. 表示连接问题。

许可证区块显示错误：请按照区块中的提示操作。例如，若该密钥已在其他域名上使用，请在您的 vibefox.net 账户中释放一个名额，然后点击 Check now。若站点地址已更改，请点击 Check now，为新域名激活密钥。若无法连接许可证服务器，插件将继续使用最后已知的状态。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面将其删除。本插件的许可证密钥和许可证状态始终会被移除。仅当开启了 Delete Data on Uninstall 时，网关设置和日志文件才会被移除。否则它们将保留，以便日后重新安装时使用。订单及其 Comgate 数据始终会被保留。现有订单保留其付款备注和交易 ID。

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