VibeFox GoPay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

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

PHP：8.0 或更高版本。

币种：GoPay 支持 CZK、EUR、PLN、USD、GBP、HUF、RON 和 BGN。使用其他币种时，结账页面会隐藏此付款方式。

GoPay 账户：您需要 GoPay 商户账户的 GoID、Client ID 和 Client Secret。可在账户的集成设置中找到这些信息。测试（sandbox）账户有独立的凭据。无需在 GoPay 账户中设置通知，但您的店铺必须能从互联网访问。

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

安装

1. 在 WordPress 中打开 Plugins > Add New > Upload Plugin，选择插件 ZIP 文件并点击 Install Now。您也可以通过 FTP 将 wcp_gopay_gateway 文件夹上传到 /wp-content/plugins/。

2. 点击 Activate。

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

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

5. 输入测试环境的 GoID、Client ID 和 Client Secret，保持 Test Mode 开启，并启用 Enable/Disable。

6. 提交一笔测试订单。确认一切正常后，输入正式环境凭据并取消勾选 Test Mode。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > GoPay。网关说明下方会显示 Sandbox mode — test payments only 或 Production mode — real payments。如果当前模式缺少 GoID、Client ID 或 Client Secret，或者 GoPay 不接受店铺币种，页面会显示警告。在这两种情况下，结账时都不会提供 GoPay。在付款方式列表中，如果尚未填写当前模式的凭据，网关会标记为需要设置。保存时会清除缓存的 GoPay 访问令牌，因此新凭据会立即生效。

Enable/Disable: Enable GoPay payment gateway 用于启用或停用付款方式。默认：关闭。

Title: 结账时显示的付款方式标题。默认：GoPay。

Description: 结账时显示的付款方式说明。默认：Pay securely via GoPay - cards, wallets, bank transfers。

API 凭据

GoID、Client ID 和 Client Secret 显示在您的 GoPay 商户账户（集成设置）中。测试（sandbox）账户有独立凭据。API 文档位于 doc.gopay.com。

Test Mode: Enable sandbox/test mode 使用测试环境凭据将付款发送到 gw.sandbox.gopay.com。不会收取真实款项。取消勾选此项后，将使用正式环境凭据（gate.gopay.cz）接受真实付款。默认：开启。

Sandbox GoID: 您的 GoPay 测试（sandbox）账户的 GoID。

Sandbox Client ID: 测试账户的 OAuth Client ID。

Sandbox Client Secret: 测试账户的 OAuth Client Secret。

Production GoID: 您的 GoPay 商户 ID（GoID）。

Production Client ID: GoPay 提供的 OAuth Client ID。

Production Client Secret: GoPay 提供的 OAuth Client Secret。

GoID 只能包含数字，例如 8123456789。如果输入其他内容，页面会显示错误并保留之前的值。

付款

Payment Page Language: GoPay 付款页面的语言。默认：Automatic (site language, then billing country)。自动模式会使用网站语言；如果 GoPay 不支持该语言，则根据账单国家/地区选择，否则使用英语。您也可以固定使用以下 19 种语言之一：捷克语、英语、斯洛伐克语、德语、波兰语、匈牙利语、罗马尼亚语、保加利亚语、克罗地亚语、斯洛文尼亚语、爱沙尼亚语、拉脱维亚语、立陶宛语、法语、意大利语、西班牙语、葡萄牙语、乌克兰语或俄语。

Order Status After Payment: 付款确认后设置的订单状态。状态会立即设置，只进行一次状态变更并向顾客发送一封电子邮件。

付款通知

通知会告知您的店铺已收到付款。每笔付款都会向 GoPay 发送通知 URL，因此无需在 GoPay 账户中进行任何设置。设置页面会显示此 URL，格式类似 https://your-site/?gopay-api=gopay_payment_notification。该 URL 必须能从互联网访问，且不能受到密码保护、维护模式或前置防火墙的阻挡。

GoPay 通知只包含付款 ID，没有签名。每条通知都会通过 GoPay API 查询付款状态进行验证，而且该付款必须是插件为您店铺的某个订单创建的。如果无法从 GoPay 读取状态，您的店铺会返回错误，GoPay 随后会重试通知。若没有通知，只有顾客付款后返回店铺时，订单才会确认。

高级

Logging: Enable logging 会将 GoPay 事件写入 WooCommerce > Status > Logs，来源为 wcp_gopay_gateway。错误始终会记录。凭据、令牌、银行卡数据以及顾客的电子邮件、电话和地址绝不会记录。默认：关闭。

Delete Data on Uninstall: Delete plugin settings, cached access tokens and log files when uninstalled。启用后，删除插件时会移除网关设置、缓存的 GoPay 访问令牌和日志。默认：关闭。

结账

顾客选择付款方式（默认是 GoPay）并提交订单。插件会按订单币种和总额创建 GoPay 付款，其中包括商品、运费和费用，然后将顾客发送到 GoPay 付款页面。GoPay 会在那里提供您账户中已启用的付款方式，例如银行卡、Apple Pay、Google Pay 和银行转账。顾客的账单姓名、电子邮件、电话和地址会传递给 GoPay；空字段不会发送。在 GoPay 中，付款会显示为 Order 和订单号。

付款后，顾客会返回您的店铺。只有 GoPay 确认后订单才会标记为已付款：通过通知，或顾客返回时向 GoPay API 发出请求。如果通知和返回同时到达，会按顺序处理，因此订单不会被重复完成。付款确认后，顾客会看到订单已收到页面。

如果付款未完成、已取消或已过期，顾客会进入 Pay for order 页面，并看到消息 The GoPay payment was not completed. You can try again or choose another payment method. 或 The GoPay payment was cancelled or has expired. You can try again or choose another payment method. 顾客可以在该页面重新支付未付款的订单。已付款订单不会创建第二笔 GoPay 付款。

如果 GoPay 无法启动付款，顾客会看到简短消息，例如 GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. 或 GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. 技术原因会添加到订单备注中。

该付款方式可用于经典结账、Cart 和 Checkout 区块以及 Pay for order 页面。在测试模式下，Checkout 区块会显示 Sandbox mode: no real payment will be made. 兼容 WooCommerce High-Performance Order Storage (HPOS)。

顾客在 GoPay 页面选择付款方式，无法在 WooCommerce 中选择。本插件不支持订阅或定期付款、保存的银行卡、嵌入式付款表单，也不能在 WooCommerce 中捕获或作废预授权。

订单和退款

订单状态

Pending payment: 顾客已跳转到 GoPay 但尚未付款，或者 GoPay 尚未确认付款。

Processing or Completed: 付款已确认。状态由 Order Status After Payment 决定。订单备注会显示 GoPay 付款 ID 和付款工具。交易 ID 即 GoPay 付款 ID。

On hold: GoPay 已确认付款，但金额或币种与订单不符；或付款是在订单取消后才收到；或付款仅获预授权，款项尚未捕获。订单备注会说明原因。必须先在 GoPay 中捕获预授权付款，然后再手动完成订单。

Failed: 未付款订单的最后一笔 GoPay 付款已取消或过期。

Refunded: 订单的 GoPay 付款已全额退款，例如在 GoPay 账户中操作。

如果已付款订单的另一笔付款尝试也成功付款，订单不会更改。系统会添加备注，要求您在 GoPay 账户中退还重复款项。如果某笔 GoPay 付款对应的订单已通过其他方式标记为已付款（例如手动操作），也会添加类似备注。您取消或退款的已付款订单不会因后续通知而重新打开。

退款

打开订单，点击 Refund，输入金额并点击 Refund via GoPay。支持全额和部分退款。GoPay 仅在付款 24 小时后接受部分退款。退款会在付款时使用的模式（测试或正式）下提交，因此必须设置该模式的凭据。如果 GoPay 拒绝退款，WooCommerce 会显示 GoPay 的消息，且不会记录退款。成功的退款会添加到订单备注。GoPay 接受并安排稍后处理的退款也会标记为已接受。

在 GoPay 账户中进行的退款会通过通知传回。全额退款会将订单状态更改为“已退款”；部分退款会添加备注。它们不会自动记录为 WooCommerce 退款。

许可证密钥

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

一个密钥只能用于一个域名。从网站移除密钥不会释放域名名额。请在 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 GoPay。如果仍然启动付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺经理仍会看到该付款方式，并显示 (unlicensed — visible to admins only)，因此您可以在购买密钥前设置和测试插件。Plugins 页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已启动的付款仍会确认，退款仍可使用。

许可证过期后，插件仍会运行，但需要续费才能获得更新和支持。系统会在后台自动重新检查状态。

故障排除

结账时没有显示 GoPay：检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否已填写 GoID、Client ID 和 Client Secret，以及币种是否为 CZK、EUR、PLN、USD、GBP、HUF、RON 或 BGN。在 Pay for order 页面中，使用订单币种。凭据或币种不正确时，设置页面会显示警告。

付款已完成，但订单仍为 Pending payment：GoPay 无法访问设置中显示的通知 URL，而且顾客没有返回店铺。请移除阻挡该 URL 的密码保护、维护模式或防火墙规则。请确认付款所在模式的凭据已设置，因为每条通知都使用这些凭据进行验证。查看 WooCommerce > Status > Logs 中来源为 wcp_gopay_gateway 的记录。GoPay 会重试未收到成功响应的通知。

通知返回 Order not found：此付款不是由该店铺创建的，或者对应订单已删除。

通知返回 Payment state could not be verified：无法访问 GoPay API，或者该模式的凭据不正确。GoPay 会重试通知。

顾客下单时看到错误：打开订单备注或启用 Logging。备注中会显示 GoPay 错误。通常是凭据错误或使用了另一个模式的凭据。关于账单信息的消息表示 GoPay 不接受该电子邮件、电话或地址。

测试付款无法确认正式订单：测试和正式环境彼此独立。每笔付款都会在创建时使用的模式下检查。将 Test Mode 切换到所需模式，并使用该模式的凭据。

付款后订单处于 On hold：查看订单备注。付款金额或币种与订单不符、付款在订单取消后才到达，或付款仅获预授权。

退款失败：查看 GoPay 消息。部分退款只能在付款 24 小时后进行。有关模式的消息表示该付款是在测试或正式模式下完成，但没有设置该模式的凭据。

许可证区域显示错误：按照区域中的说明操作。例如，如果该密钥已用于其他域名，请在 vibefox.net 账户中释放一个名额，然后点击 Check now。如果网站地址发生变化，请点击 Check now，为新域名激活密钥。如果无法访问许可证服务器，插件会根据最后已知状态继续运行。

供开发者使用：筛选器 gopay_p_payment_payload 可更改付款请求，gopay_p_icon 可更改付款方式图标。

卸载

停用插件不会删除任何数据。要移除插件，请在 Plugins 页面停用并删除它。此插件的许可证密钥和许可证状态始终会被移除。只有启用了 Delete Data on Uninstall，才会删除网关设置、缓存的访问令牌和日志。否则，这些数据会保留以便日后重新安装。订单中保存的 GoPay 付款 ID 始终会保留。现有订单的付款备注和交易 ID 也会保留。

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