VibeFox GoPay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

币种：GoPay 接受 CZK、EUR、PLN、USD、GBP、HUF、RON 和 BGN。如果购物车币种不在此列，结账时将隐藏该付款方式。

GoPay 账户：您需要 GoPay 商户账户的 GoID、Client ID 和 Client Secret。这些信息位于账户的集成设置中。沙盒（测试）账户有自己的凭据。通知无需在 GoPay 账户中进行任何设置，但您的商店必须可从互联网访问。

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

安装

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

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

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

4. 输入沙盒的 GoID、Client ID 和 Client Secret，保持 Test Mode 开启，打开 Enable/Disable，然后点击 Save。

5. 下一个测试订单。一切正常后，输入正式环境凭据并关闭 Test Mode。

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

配置

所有设置都在模块页面：Modules > Module Manager > VibeFox GoPay Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，页面会显示 Sandbox mode — test payments only 或 Production mode — real payments。当当前模式缺少 GoID、Client ID 或 Client Secret，或 GoPay 不接受商店的默认币种时，页面会发出警告。在这两种情况下，结账时都不会提供 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 商户账户中（集成设置）。沙盒（测试）账户有自己的凭据。API 文档位于 doc.gopay.com。

Test Mode：使用沙盒凭据将付款发送到 gw.sandbox.gopay.com。不会扣除真实款项。关闭后，将使用正式环境凭据接受真实付款。默认：开启。

Sandbox GoID：您的 GoPay 沙盒（测试）账户的 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。如果输入其他内容，页面会显示错误，并保留之前的值。

已保存的 Client Secret 不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Clear saved client secrets：勾选后点击 Save，即可删除两个已保存的 Client Secret。字段为空时将保留已保存的值。

付款

Payment Page Language：GoPay 付款页面的语言。默认：Automatic (site language, then billing country)。自动模式使用顾客购物车的语言；如果 GoPay 不支持该语言，则由账单国家决定，否则使用英语。您也可以固定为以下 19 种语言之一：Czech、English、Slovak、German、Polish、Hungarian、Romanian、Bulgarian、Croatian、Slovenian、Estonian、Latvian、Lithuanian、French、Italian、Spanish、Portuguese、Ukrainian 或 Russian。

Order Status After Payment：付款得到确认后设置的订单状态。

与订单不符的付款、取消后的付款以及预授权付款，始终会进入 GoPay payment on hold。

付款通知

通知会告诉您的商店已完成付款。Notification URL 显示在本部分中，并会随每笔付款发送给 GoPay，因此无需在 GoPay 账户中进行任何设置。使用友好 URL 时，它看起来像 https://your-shop/module/wcp_gopay_gateway/webhook，前面可能带有语言代码，例如 /en/。它必须可从互联网访问：前面不能有密码保护或防火墙。商店处于维护模式时它仍然有效，也不会被商店的国家限制拦截。

GoPay 通知只包含付款 ID，没有签名。每条通知都会通过 GoPay API 验证：使用付款时所用模式的凭据查询付款状态，并且该付款必须是模块为您商店的某个购物车创建的。如果无法从 GoPay 读取状态，您的商店会返回错误，GoPay 将重复发送通知。没有通知时，只有在顾客付款后返回商店时才会创建订单。

高级

Logging：将 GoPay 事件写入模块文件夹中的 logs/gopay_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。凭据、令牌、银行卡数据以及顾客的电子邮件和姓名永远不会被记录。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载模块时会删除模块设置、已缓存的 GoPay 访问令牌和日志。订单、其 GoPay 付款数据以及 GoPay payment on hold 订单状态始终保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 GoPay）并确认。模块会以购物车币种为该购物车总额创建 GoPay 付款，其中包括商品、运费和礼品包装，然后将顾客带到 GoPay 付款页面。在那里，GoPay 会提供您 GoPay 账户中已启用的付款方式，例如银行卡、银行转账和数字钱包。顾客的账单姓名、电子邮件、电话和地址会传递给 GoPay；空字段不会发送。在 GoPay 中，该付款显示为 Order PS- 加上购物车编号。此时尚未创建订单。

付款后，顾客会返回您的商店。只有在 GoPay 确认付款后，订单才会被标记为已付款：通过通知，或在顾客返回时向 GoPay API 发出请求。同时到达的通知和返回会依次处理，因此只会创建一个订单。随后，顾客会看到标准的订单确认页面。如果订单进入了 GoPay payment on hold，页面会添加 Your payment is being reviewed. We will contact you if anything else is needed.

如果顾客返回时 GoPay 尚未确认付款（例如银行转账正在途中，或无法连接 GoPay），Payment confirmation 页面会显示 GoPay 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 按钮。

如果付款未完成、已取消或已过期，顾客会回到结账页面，并看到 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. 技术原因会写入日志。

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

订单与退款

订单状态

No order yet：顾客已被发送到 GoPay 且尚未付款，或 GoPay 尚未确认付款。此时仅存在购物车。

Payment accepted or Delivered：付款已确认。状态遵循 Order Status After Payment。付款会以 GoPay 付款 ID 作为交易 ID 记录，备注中会显示付款 ID 和付款方式。

GoPay payment on hold：GoPay 已确认付款，但金额、币种或订单号与购物车不一致（例如，付款开始后购物车被修改）；或者付款是在订单被取消之后到达的；或者付款只是预授权，尚未捕获款项。备注会说明原因。预授权付款需要在 GoPay 中进行捕获；当 GoPay 报告付款已完成后，订单才会进入已付款状态。

Refunded：订单的 GoPay 付款已通过模块或在 GoPay 账户中全额退款。

如果已付款订单的另一次付款尝试也被付款，订单不会改变。备注会要求您在 GoPay 账户中退还重复付款。当 GoPay 付款针对一个已在没有 GoPay 的情况下被标记为已付款的订单（例如手动标记）而完成时，也会添加类似的备注。已取消或已退款的订单永远不会因为之后的通知而被重新打开。

GoPay 付款区块

订单页面会显示 GoPay payment 区块，包含 GoPay 付款 ID、GoPay 状态和付款方式、付款金额、已付和已退金额、沙盒付款的 Sandbox 标记、人工审核原因、退款记录以及订单的 GoPay notes。

退款

在 GoPay payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via GoPay。确认询问 Refund this amount through GoPay? This cannot be undone. 支持全额和部分退款。您需要具有编辑订单的权限；无需访问 Modules 页面。GoPay 仅在付款后 24 小时内接受部分退款。退款金额和币种与 GoPay 扣款一致，因此在金额或币种不一致后，您最多只能退还顾客实际支付的金额。退款会在付款时所用的模式（沙盒或正式环境）中发送，因此该模式的凭据必须已设置。如果 GoPay 拒绝退款，该区块会显示 GoPay 的消息，且不会记录任何退款。成功的退款会添加到退款记录和备注中；GoPay 已接受、稍后处理的退款会被标注为已接受。全额退款会将订单设为 Refunded。部分退款不会改变状态。

模块不会创建 credit slip（贷项凭单）。订单页面上 PrestaShop 的标准退款按钮不会通过 GoPay 退款。

在 GoPay 账户中进行的退款会通过通知到达。全额退款会将订单更改为 Refunded；部分退款会添加备注。这些退款不会添加到区块的退款记录中。

许可证密钥

模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。License — VibeFox GoPay Gateway 许可证区块是模块 Modules > Module Manager > VibeFox GoPay Gateway > Configure 页面中位于设置上方的第一个区块。请将密钥输入 License key 并点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期和您的域名），并提供 Check now 按钮以重新检查状态、Change key 按钮以输入其他密钥，以及 Remove key 按钮以从本店移除密钥。其下方是 Product: presta-payment-gopay 一行，以及 Manage licenses and domains in your account 链接，可打开您在 vibefox.net 上的账户。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英语和俄语）。

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

一个密钥只适用于一个域名：即主店铺的域名，多店铺设置中也是如此。从店铺中移除密钥不会释放其域名名额。请在 vibefox.net 账户中释放名额。

没有有效密钥时，结账时不会向顾客显示 GoPay。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已开始的付款仍会得到确认，退款也正常工作。

许可证到期后，模块仍会继续运行，但更新和支持需要续费。在您使用后台期间，状态会自动重新检查：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。

故障排除

结账时没有 GoPay：请检查许可证是否有效、Enable/Disable 是否开启、当前模式是否已设置 GoID、Client ID 和 Client Secret，以及购物车币种是否为 CZK、EUR、PLN、USD、GBP、HUF、RON 或 BGN 之一。缺少凭据时，设置页面会显示警告。在 Payment > Preferences 中，请检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属群组。

付款已完成，但未创建订单：GoPay 无法访问设置中显示的 Notification URL，并且顾客也没有返回商店。请移除阻止该 URL 的密码保护或防火墙规则。请检查付款所用模式的凭据是否已设置，因为每条通知都会使用这些凭据进行验证。开启 Logging，并查看 Log 字段。GoPay 会重新发送未获得成功响应的通知。

Notification answers Order not found：该付款不是由本商店创建的，或其购物车已被删除。

Notification answers Payment state could not be verified：无法访问 GoPay API，或该模式的凭据缺失或错误。GoPay 将重新发送通知。

Notification answers Busy, retry later：购物车在同一时刻正被另一个请求处理，或无法创建订单（例如模块已禁用）。GoPay 将重新发送通知。开启 Logging 可查看原因。

顾客在选择 GoPay 时看到错误：开启 Logging 并查看 Log 字段。凭据错误，或使用了另一种模式的凭据，通常是原因。关于账单信息的消息表示 GoPay 不接受电子邮件、电话或地址。

测试付款不会确认正式订单：沙盒和正式环境是分开的。每笔付款都会在其创建时所用的模式中检查。请将 Test Mode 切换到您需要的模式，并使用该模式的凭据。

付款后订单进入 GoPay payment on hold：请阅读 GoPay payment 区块中的备注。已付金额或币种与购物车不符、付款是在订单取消后到达的，或者付款只是预授权。

退款失败：请阅读区块中 GoPay 的消息。部分退款只能在付款后 24 小时内进行。如果消息提到模式，则表示付款是在沙盒或正式环境中完成的，而该模式的凭据尚未设置。

开发人员注意：actionGopayPaymentPayload 钩子会在付款请求发送到 GoPay 之前对其进行修改。

卸载

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

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