VibeFox GoPay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

货币：GoPay 接受 CZK、EUR、PLN、USD、GBP、HUF、RON 和 BGN。如果顾客结账时使用其他货币，付款方式将在结账时隐藏。

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

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请先在电脑上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_gopay_gateway-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_gopay_gateway.ocmod.zip。只安装与您的 OpenCart 版本对应的安装包。许可证密钥对两个版本通用。

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

配置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox GoPay Gateway > Edit。各个部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示 Sandbox mode — test payments only 或 Production mode — real payments。如果当前模式缺少 GoID、Client ID 或 Client Secret，或者 GoPay 不接受店铺的默认货币，页面会发出提示。没有凭据时，GoPay 不会在结账时提供；如果默认货币不受支持，则只会提供给切换到受支持货币的顾客。如果没有修改扩展的权限，页面只会显示设置，无法保存。

保存时，如果某个字段的值无效，该字段会保留原值，页面会显示错误；其他字段仍会保存。以下情况都会如此：Title 为空或超过 128 个字符，GoID 不是 6 到 20 位数字，Sort Order 不是整数，Total 不是 0 或更大的数字，以及地理区域或订单状态不存在。保存时还会清除缓存的 GoPay 访问令牌，以便立即使用新凭据。

GoPay

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

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

Description：在 Confirm Order 步骤中、确认按钮上方显示的付款方式说明。默认：Pay securely via GoPay - cards, wallets, bank transfers.

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

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

Total：订单必须达到的金额（以店铺默认货币计）才会提供 GoPay。留空则对任何金额都提供。

API 凭据

GoID、Client ID 和 Client Secret 显示在您的 GoPay 商户账户（集成设置）中。沙盒（测试）账户有自己的凭据。本节链接到 GoPay API 文档。

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 仅包含 6 到 20 位数字，例如 8123456789。如果您输入其他内容，页面会显示 GoID must contain digits only, 6 to 20 digits (for example 8123456789). The previous value was kept.

已保存的 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。

OpenCart 在 Confirm Order 步骤创建订单时不带状态（缺失订单，missing order）。只有在顾客通过通知或返回店铺确认 GoPay 已付款后，订单才会获得状态；状态始终通过 GoPay API 读取。下方每个状态字段都列出了您的 OpenCart 订单状态。

Order Status After Payment：付款确认后设置的订单状态。默认：处理中。例如，虚拟商品可选择已完成。

GoPay Payment On Hold Status：与订单不符的付款、取消后的付款以及仅预授权的付款。备注会说明原因；请在 GoPay 账户中检查该付款。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled Order Status：对于处于此状态（或已退款状态）的订单，如果收到 GoPay 付款，订单会被置于等待状态，而不是悄悄地重新打开。默认：已取消。

Refunded Status：付款通过订单页面或 GoPay 报告被全额退款后设置。默认：已退款。

付款通知

通知会告知您的店铺已完成付款。Notification URL 显示在本节中，并会随每笔付款发送给 GoPay，因此无需在 GoPay 账户中进行任何设置。在 OpenCart 3 中，该 URL 形如 https://your-store/index.php?route=extension/payment/wcp_gopay_gateway/notify；在 OpenCart 4 中则形如 https://your-store/index.php?route=extension/wcp_gopay_gateway/payment/wcp_gopay_gateway.notify。它由您的 OpenCart 安装的店铺前台地址生成。它必须可以从互联网访问：前面不能有密码保护或防火墙。即使店铺处于维护模式，它也能正常工作：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动操作（startup action），使 GoPay 的通知和顾客返回都能通过。

GoPay 通知只包含付款 ID，不带签名。每条通知都会使用付款所用模式的凭据，向 GoPay API 查询付款状态来进行验证，并且该付款必须是扩展为本店铺某个订单创建的付款。如果无法从 GoPay 读取状态，您的店铺会返回错误，GoPay 会重新发送通知。没有通知时，订单只有在顾客付款后返回店铺时才会获得状态。

高级

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

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

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

导入 / 导出

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

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

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 GoPay）。在 Confirm Order 步骤中，顾客会看到您的说明。OpenCart 在此步骤创建订单，仍然不带状态。顾客点击 Confirm Order 后，扩展会以订单货币为单位，为订单总额创建一笔 GoPay 付款，其中包含商品、礼品卡、运费以及其他订单总计项，并将顾客引导至 GoPay 付款页面。在那里，GoPay 会提供您 GoPay 账户中已启用的付款方式，例如银行卡、银行转账和电子钱包。顾客的姓名、电子邮件、电话和付款地址会传递给 GoPay；空字段不会发送。付款在 GoPay 中显示为订单号 OC- 加上 OpenCart 订单号。

在 OpenCart 4 中，顾客通过 Payment method options 窗口中付款方式区块的 Choose 按钮选择付款方式，并在结账页面底部点击 Confirm Order。OpenCart 4 没有礼品卡，因此不会向 GoPay 发送礼品卡。OpenCart 4 默认不要求填写付款地址，此时扩展会将配送地址中的姓名和地址传递给 GoPay。

付款后，顾客返回您的店铺。只有在 GoPay 确认付款后，订单才会被标记为已付款：要么是通过通知，要么是顾客返回时向 GoPay API 发出的请求。如果通知和返回同时到达，会依次处理，因此付款只会被应用一次。随后，订单会以 OpenCart 的标准方式获得状态，发送常规订单邮件并更新库存，顾客会看到 OpenCart 的订单成功页面。如果订单进入了等待状态，页面会额外显示 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 confirmed automatically as soon as the payment is confirmed — please do not pay again. 并带有 Check again 和 Back to checkout 按钮。

如果付款未完成、已取消或已过期，顾客会返回结账页面，并显示 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. 购物车会被保留。在 OpenCart 4 中，这些消息显示在结账页面上方。每次新的尝试（OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则更新结账中的订单，并以相同的订单号通过新的 GoPay 付款来支付）都会先通过 GoPay API 检查购物车中未完成的 GoPay 付款。如果其中某笔已经付款，则确认该笔付款，顾客无需再次付款即可进入成功页面。购物车的任何变动（包括数量变化）都视为需要单独付款的新购物车。

OpenCart 4 在显示成功页面之前会将订单保留在结账流程中。如果该订单期间被关闭且未付款（例如您取消或退款了该订单），顾客会被带回结账页面，并显示 Your previous order was cancelled or refunded. Please confirm the order again.（或关于已取消付款的消息），下一次点击 Confirm Order 时将支付新订单。已付款的订单绝不会在另一个购物车中显示为已付款。

如果 GoPay 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 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 页面上选择付款方式，无法在 OpenCart 中选择。该扩展不支持订阅或定期付款、保存的银行卡、嵌入式付款表单，也不支持从 OpenCart 对预授权进行扣款或撤销。

订单与退款

订单状态

No status (missing order)：顾客已被引导至 GoPay 但尚未付款，或 GoPay 尚未确认付款。已取消或已过期的 GoPay 付款会使订单保持无状态，并附带一条备注。在 Sales > Orders 中，此类订单只有在筛选器 Order Status 设为 Missing Orders 时才会显示。

Order Status After Payment（默认 Processing）：付款已确认。备注中会显示 GoPay 付款 ID。

GoPay Payment On Hold Status（默认 Pending）：GoPay 已确认付款，但金额、币种或订单号与订单不符；或付款是在订单被取消或退款之后到达的；或付款只是预授权，资金尚未扣除。备注会说明原因。预授权付款必须在 GoPay 中扣款；之后，当 GoPay 报告付款已完成时，订单会转为已付款状态。

Refunded Status（默认 Refunded）：订单的 GoPay 付款已通过扩展或在 GoPay 账户中全额退款。

如果同一已付款订单又支付了另一次付款，或同一购物车中较早的订单被支付，已付款订单不会被更改。备注会要求您在 GoPay 账户中退还重复付款。如果某个并非通过 GoPay 标记为已付款的订单（例如手动标记）收到了 GoPay 付款，也会添加类似的备注。已取消或已退款的订单绝不会因后续通知而被重新打开。

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

VibeFox GoPay Gateway 选项卡

在 Sales > Orders 中打开一笔通过 GoPay 付款的订单。在订单页面底部，与 History 和 Additional 并列的 VibeFox GoPay Gateway 选项卡会显示 GoPay payment ID（沙盒付款带有 Sandbox 标签）、GoPay state 和付款工具、Payment amount、Paid / refunded、订单处于等待状态时附带原因的 Needs review、退款表单、退款历史，以及该订单的 GoPay notes。该选项卡对有权访问该扩展的用户显示。

退款

在选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via GoPay。确认 Refund this amount through GoPay? This cannot be undone. 支持全额和部分退款。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。GoPay 仅在付款后 24 小时内接受部分退款。退款按 GoPay 收取的金额和币种进行，因此在金额或币种不一致之后，您最多只能退还顾客实际支付的金额。退款适用于已付款订单，以及因不一致或迟到付款而处于等待状态的订单。退款会在付款所用的模式（沙盒或正式）中发送，因此该模式的凭据必须已设置。如果 GoPay 拒绝退款，选项卡会显示 GoPay 的消息，且不会记录任何退款。成功的退款会添加到退款历史和备注中；GoPay 已接受但稍后处理的退款会被记录为已接受。全额退款会将订单设置为 Refunded Status，不会通知顾客，也不会把商品退回库存，与手动更改状态相同。部分退款不会更改状态。

Sales > Returns 中的商品退货不会通过 GoPay 退还款项。

在 GoPay 账户中进行的退款会通过通知到达：全额退款会将订单改为退款状态；部分退款会添加一条备注。它们不会被添加到选项卡的退款历史中。

许可证密钥

该扩展需要使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox GoPay Gateway 是 Extensions > Extensions > Payments > VibeFox GoPay Gateway > Edit 页面中位于设置上方的第一个区块。将密钥粘贴到 License key 中并点击 Activate。之后，该区块会以掩码形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从本店铺移除该密钥）。其下方是 Product: opencart-payment-gopay 一行，以及打开您 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 账户中释放该名额。

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

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

故障排除

GoPay does not appear at checkout：请检查许可证是否有效、Enable/Disable 是否已开启、当前模式是否已设置 GoID、Client ID 和 Client Secret，以及结账货币是否为 CZK、EUR、PLN、USD、GBP、HUF、RON 或 BGN 之一。缺少凭据时，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到了设置中的 Total。

The payment went through, but the order stays without a status：GoPay 无法访问设置中显示的通知 URL，而且顾客没有返回店铺。请移除阻止该 URL 的密码保护或防火墙规则。请检查付款所用模式的凭据是否已设置，因为每条通知都会用它们进行验证。开启 Logging 并查看 Log 字段。GoPay 会重新发送未获得成功响应的通知。

Notification answers Order not found：该付款不是由本店铺创建的。

Notification answers Missing payment ID：请求不是来自 GoPay，或 URL 已被修改。无需任何操作。

Notification answers Payment state could not be verified：无法连接 GoPay API，或该模式的凭据缺失或有误。GoPay 会重新发送通知。

Notification answers Busy, retry later：订单在同一时刻正被另一个请求处理。GoPay 会重新发送通知。开启 Logging 可查看原因。

The customer sees an error after Confirm Order：开启 Logging 并查看 Log 字段。凭据错误，或使用了另一模式的凭据，是常见原因。与账单信息有关的消息表示 GoPay 不接受电子邮件、电话或地址。This payment method is not available. Please reload the checkout page. 表示结账会话已与订单不匹配，或付款方式在此期间已被关闭。

The customer comes back and sees We could not verify the GoPay payment. If money was charged, please contact us before paying again.：返回链接与店铺中的任何订单都不匹配，例如它是在另一个浏览器中打开或被修改过的。请在 GoPay 账户中检查该付款；通知仍会确认真实的付款。

Test payments do not confirm a live order：沙盒和正式环境是分开的。每笔付款都会在其创建时的模式中进行检查。将 Test Mode 切换为您需要的模式，并使用该模式的凭据。

Order is in the on hold status after payment：请阅读 VibeFox GoPay Gateway 选项卡中的备注。付款金额或币种与订单不同，付款是在订单被取消后到达的，或者付款只是预授权。

Refund fails：请阅读选项卡中 GoPay 的消息。部分退款只能在付款后 24 小时内进行。与模式相关的消息表示该付款是在沙盒或正式模式中进行的，而该模式的凭据未设置。You do not have permission to refund (modify this extension). 表示您的用户组没有修改该扩展的权限。

对开发人员：在付款发送到 GoPay 之前，扩展会触发 OpenCart 事件 gopay_p_payment_payload，并附带付款请求和订单。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox GoPay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除该扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及四个订单状态字段，这些字段在重新安装时会恢复默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 中，包括其事件以及在维护模式下放行通知和顾客返回 GoPay 的启动操作）。如果 Delete Data on Uninstall 已开启，其余网关设置（标题、说明、测试模式、凭据、付款页面语言、日志记录）、缓存的 GoPay 访问令牌和日志都会被删除；如果未开启，则会保留，以便日后重新安装时使用。订单的 GoPay 付款数据和退款始终会保留，因此重新安装后仍可对先前已付款的订单进行退款。现有订单会保留其付款备注。

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

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