VibeFox Quickpay for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Quickpay 账户：您需要从 Quickpay 管理后台获取两个值：某个 API 用户的 API 密钥（用于创建付款、捕获和退款），以及账户的私钥（用于验证 Quickpay 回调的签名）。在 Quickpay 中无需进行其他设置。您的店铺必须能够从互联网访问，且不能设有密码保护，以便 Quickpay 回调能够到达。

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

安装

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

OpenCart 3

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

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

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

4. 粘贴 Quickpay 管理后台中的 API 密钥和私钥，然后点击 Test API key（见配置）。

5. 选择捕获模式和付款后的订单状态，开启 Enable/Disable，然后点击 Save。当您的 Quickpay 账户处于测试模式时，请开启 Test payments，并使用 Quickpay 测试卡进行一次付款。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的第 3 至第 5 步输入许可证密钥、Quickpay 密钥和设置。两个版本的设置页面及其字段相同。只有回调 URL 不同（参见配置）。

新安装默认关闭付款方式。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Quickpay Gateway > Edit。各部分列于左侧；列表下方的 Save 按钮会保存整个页面。在 API 密钥和私钥都保存之前，页面会显示 Quickpay needs setup: enter the API key and the private key. Until both are saved the payment method is hidden at checkout. 当 Test payments 开启时，页面会提醒您在 Quickpay 账户正式启用后将其关闭。若没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 必须为 1 到 128 个字符，Sort Order 必须为整数（允许负数），Total 必须为 0 或更大的数字，并且地理区域和每个订单状态都必须存在。否则不会保存任何内容，页面会指出有问题的字段。

Quickpay

Enable/Disable：Enable Quickpay 用于开启或关闭该付款方式。默认：off。

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

Description：在 Confirm Order 步骤中、确认按钮上方向顾客显示的文字。默认：Pay securely by card or MobilePay on the Quickpay payment page。

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

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

Total：订单必须达到的结账金额（以店铺默认货币计）才会提供 Quickpay：0 或更大的数字。留空则对任何金额都提供 Quickpay。

Quickpay API 凭据

在 Quickpay 管理后台（manage.quickpay.net，页面中提供了相应链接）中打开 Settings > Integration。复制某个 API 用户的 API 密钥（Settings > Users）以及账户的私钥。

Callback URL：显示您店铺的回调 URL。其形式为 https://your-store/index.php?route=extension/payment/wcp_quickpay_gateway/callback（OpenCart 3）或 https://your-store/index.php?route=extension/wcp_quickpay_gateway/payment/wcp_quickpay_gateway.callback（OpenCart 4），由您的 OpenCart 安装的店铺前台地址生成。Quickpay 会在每次付款操作（授权、捕获、退款、取消）后调用它。它会随每笔付款、捕获和退款自动发送，因此无需在 Quickpay 中进行任何配置。

API key：Quickpay API 用户的 API 密钥。用于创建付款、捕获和退款。

Private key：账户的私钥。用于验证 Quickpay 回调的签名（HMAC-SHA256）。没有它，任何付款都无法被确认，回调也会被拒绝。

已保存的密钥将不再显示。该字段保持为空，并显示 Saved — leave empty to keep it. 仅当您想更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

Test API key：此按钮会使用经过身份验证的请求，向 Quickpay 检查 API key 字段中输入的密钥（如果该字段为空，则检查已保存的密钥），但不会保存它。它会返回 Connection successful — the API key is valid.、Quickpay rejected the API key.、API key is not configured.，或 Connection failed: 及原因。

Test payments：接受使用 Quickpay 测试卡完成的付款。Quickpay 没有独立的沙盒：当您的 Quickpay 账户处于测试模式时，付款会使用测试卡完成并被标记为测试付款。仅在测试期间开启此项。关闭时，测试付款永远不会将订单标记为已付款。开启时，顾客会在 Confirm Order 步骤中看到 Test mode: Quickpay test cards are accepted. 默认：off。

付款

Capture：何时从银行卡中扣款。

Order status after payment：在 Quickpay 确认已捕获的付款后，已付款订单获得的状态。

订单状态

OpenCart 在 Confirm Order 步骤中创建订单，此时订单无状态（缺失订单）。只有在签名的 Quickpay 回调之后，订单才会获得状态。下面的每个字段都列出了您的 OpenCart 订单状态。

"Payment accepted" status：已捕获的付款已确认，且金额和币种一致。默认：Processing。

"Delivered (completed)" status：当 Order status after payment 为 Delivered (completed) 时使用此状态代替。默认：Complete。

"Quickpay payment on hold" status：付款仅已授权，正在等待捕获；金额或币种不符；或捕获失败。默认：Pending，因为 OpenCart 没有 On hold 状态；订单中的备注会说明原因。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Cancelled status：当暂停订单的付款在 Quickpay 中被取消时设置。当您将本扩展的某个订单设为此状态时，其未付款的付款链接会在 Quickpay 中被删除（见订单与退款）。默认：Canceled。

Refunded status：在订单页面中将付款全额退款后设置。默认：Refunded。

高级

Debug log：写入 OpenCart 日志文件夹（storage/logs）中的 qpg_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 qpg_debug.old.log.php。错误和警告（例如被拒绝的回调和 Quickpay API 错误）始终会被记录。开启此项可同时记录每个请求和回调的详细信息。API 密钥、银行卡数据和顾客信息永远不会被记录。默认：off。

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

Delete data：开启后，卸载扩展时会删除网关设置和日志。订单数据（Quickpay 付款、退款、备注）始终会被保留。默认：off。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。API 密钥和私钥不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 以恢复设置。已保存的密钥将被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Quickpay）。在 Confirm Order 步骤中，顾客会看到您的说明以及提示 You will be redirected to the Quickpay payment window to complete the payment. OpenCart 在此步骤中创建订单，仍无状态。当顾客点击 Confirm Order 时，扩展会以订单货币创建一笔 Quickpay 付款，并为订单总额生成付款链接，然后将顾客带到 Quickpay 付款窗口。顾客在那里使用您的 Quickpay 付款窗口中启用的某种方式付款。顾客的电子邮件地址会传递给 Quickpay。如果 Quickpay 提供顾客所用语言，付款窗口会以该语言打开（丹麦语、德语、英语、西班牙语、芬兰语、法语、意大利语、荷兰语、挪威语、波兰语、瑞典语），否则显示英文。在 OpenCart 4 上，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

付款后，顾客会返回您的店铺。返回本身不会将任何内容标记为已付款。只有在 Quickpay 确认后，订单才会被标记为已付款：当已捕获的金额和币种与订单一致时，已签名的回调会设置订单状态。随后，订单会以 OpenCart 的标准方式获得其状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 订单成功页面。使用 Authorize only 时，订单会改为获得 "Quickpay payment on hold" status，之后您再捕获付款。如果顾客返回时回调尚未到达，Payment confirmation 页面会显示 Your payment is being confirmed by Quickpay. You will receive an e-mail as soon as the order is confirmed.，并附带 Check again 和 Back to checkout 按钮。当 Quickpay 回调之后将订单从 "Quickpay payment on hold" status 移至已付款状态或 Cancelled status 时，顾客会收到电子邮件通知。

如果顾客在付款窗口中取消，付款链接会在 Quickpay 中被删除，顾客会返回结账页面，并看到 The payment was cancelled. You can try again or choose another payment method. 如果银行卡被拒绝，提示为 The payment was not completed. You can try again or choose another payment method. 购物车会被保留。同一订单的新尝试会获得同一 Quickpay 付款的新链接。在 OpenCart 3 中，每次显示 Confirm Order 步骤时都会创建新订单；同一购物车的早期订单的付款链接会随之被删除，因此旧链接永远无法被并行支付。当购物车的某笔付款已授权并等待捕获时，不会发起第二笔付款；顾客会看到 Payment confirmation 页面。

在 OpenCart 4 上，取消和拒付的消息会显示在结账页面上方。OpenCart 4 将结账中的订单保持为一个订单，并在每次显示 Confirm Order 步骤时更新它，因此取消或拒付后，同一订单会通过同一 Quickpay 付款的新链接付款。如果该订单在此期间未付款即被关闭，顾客会被带回结账页面，并看到 您之前的订单在未付款的情况下已被取消。请重新确认订单，以新订单付款。，下一次 Confirm Order 将为新订单付款。如果结账中的订单已有状态，但购物车此后已变更（包括新的数量），顾客会被带回结账页面，并且新购物车将以新订单付款。

如果无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到 The Quickpay payment could not be started. Please try again or choose another payment method. 技术原因会写入日志。如果缺少密钥，提示为 Quickpay is not available at the moment. Please choose another payment method.

回调和顾客的返回即使在店铺处于维护模式时也有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 上，扩展会为此添加自己的启动动作。

该扩展仅接受一次性付款。它不支持订阅或定期付款、保存的银行卡或部分捕获，不会向 Quickpay 发送购物车或发票明细，也没有单独的 MobilePay、Apple Pay 或 Klarna 方式：顾客从您的 Quickpay 付款窗口提供的方式中选择。

订单与退款

订单状态

无状态（缺失订单）：顾客已被转到 Quickpay 但尚未付款，银行卡被拒绝，或付款已授权并等待自动捕获。在 Sales > Orders 中，只有将 Order Status 筛选器设置为 Missing Orders 时才会显示此类订单。

"Payment accepted" 或 "Delivered (completed)" status：Quickpay 已确认已捕获的付款，且金额和币种正确。状态取决于 Order status after payment。备注会显示 Quickpay 付款 ID（测试付款会标记为 TEST）。

"Quickpay payment on hold" status（默认 Pending）：付款仅已授权，正在等待 Capture Quickpay payment；或 Quickpay 报告的金额或币种与订单总额不同（例如在 Quickpay 后台捕获了其他金额）；或捕获失败，金额仅处于预留状态。备注会说明原因。当捕获的金额与订单不同时，扩展会记录 Quickpay 实际捕获的金额，退款上限为该金额。

Cancelled status：暂停订单的付款已在 Quickpay 后台中取消。

Refunded status：付款已通过扩展全额退款。

对于已付款、已取消或已退款的订单所收到的付款，不会改变订单。备注会要求您在 Quickpay 后台中核对该付款，例如以便退还重复付款。如果同一购物车的另一个订单已付款，新订单将保持无状态，已付款的订单会收到该备注。

当您在订单的 History 中将本扩展的未付款订单设为 Cancelled status 时，其付款链接会在 Quickpay 中被删除。取消已授权的订单不会自动释放预留金额：备注会提醒您在 Quickpay 后台中取消付款；否则，预留会在授权过期时结束。

备注是订单 History 中的记录，顾客看不到。

VibeFox Quickpay Gateway 标签页

在 Sales > Orders 中打开一个通过 Quickpay 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Quickpay Gateway 标签页会显示 Payment ID（测试付款会带有 Test payment 标签）、付款的 Status、Amount / refunded、订单的所有 Quickpay 付款列表（如果有多笔）、捕获按钮、退款表单、退款历史以及订单的 Quickpay notes。该标签页会显示给有权访问该扩展的用户。捕获和退款需要修改扩展的权限（在 System > Users > User Groups 中设置）。

捕获

使用 Authorize only 时，在标签页中点击 Capture Quickpay payment，并确认 Capture the order total through Quickpay? 将捕获订单总额；不支持部分捕获。如果 Quickpay 立即确认，订单会被设为 Order status after payment 所对应的已付款状态，不会通知顾客，也不会更改库存，与手动更改状态相同。否则，备注会说明已请求捕获，待 Quickpay 回调确认后再将订单标记为已付款。被拒绝的捕获会显示在标签页中，并记录在订单备注里。

退款

在标签页中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Quickpay。确认提示 Refund this amount through Quickpay? This cannot be undone. 对于已捕获的付款，支持全额和部分退款。退款按 Quickpay 实际捕获的金额和币种进行，而不是订单总额。Quickpay 以异步方式处理退款：退款历史会显示 requested，回调会将其设为 confirmed 或 failed，并将结果添加到备注中。失败的退款不计为已退款。如果 Quickpay 立即拒绝退款，标签页会显示错误，且不会记录任何退款。全额退款会将订单设为 Refunded status，不会通知顾客，也不会将商品退回库存；部分退款不会更改状态。从未被捕获的已授权付款无法退款；请在 Quickpay 后台取消它。

在 Sales > Returns 中的商品退货不会通过 Quickpay 退款。

直接在 Quickpay 后台进行的退款只会添加到备注中。订单状态不会自动更改。如有需要，请手动更新。

许可证密钥

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

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

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

故障排除

结账时不显示 Quickpay：请检查许可证是否有效、Enable/Disable 是否已开启，以及 API key 和 Private key 是否都已保存。两个密钥缺一，该付款方式就会被隐藏，并且设置页面会显示警告。另外请检查账单地址是否位于所选的 Geo Zone 内，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：Quickpay 回调未到达您的店铺，或被拒绝。请检查您的店铺是否可从互联网访问（没有密码保护），以及 Private key 是否为同一 Quickpay 账户的私钥。被拒绝的回调始终会写入扩展页面上的日志。开启 Debug log 可查看每一次回调。

日志显示 Callback rejected: invalid checksum.：设置中的私钥不属于发送回调的账户。请从 Quickpay 后台的 Settings > Integration 中重新复制。

日志显示 Callback rejected: the private key is not configured.：请输入私钥。没有私钥，回调永远不会被接受。

日志显示 Callback: no order found for payment …：该回调属于一笔并非由本店铺创建的 Quickpay 付款，例如在 OpenCart 之外完成的付款。

日志显示购物车已被另一请求锁定：同一购物车的另一个回调当时正在处理中。该回调会收到错误，因此 Quickpay 会重新发送它。

测试付款没有将订单标记为已付款：Test payments 已关闭。日志以及订单中的备注会说明测试付款未被接受。测试时请开启该设置，账户正式启用后请关闭。

付款后订单处于暂停状态：请阅读 VibeFox Quickpay Gateway 标签页中的备注。付款可能仅已授权，正在等待 Capture Quickpay payment；已付的金额或币种可能与订单不符；或捕获失败。请进行捕获、处理订单，或退还付款。

Test API key 提示 Quickpay rejected the API key.：密钥错误，或属于没有 API 访问权限的用户。请从 Quickpay 后台复制某个 API 用户的 API 密钥。

顾客看到 The Quickpay payment could not be started.：请查看扩展页面上的 Log 字段。它会显示 Quickpay 的错误，例如您的 Quickpay 账户不接受的货币。

退款失败：订单必须有已捕获的 Quickpay 付款。消息 The Quickpay payment of this order has not been captured — there is nothing to refund. 表示该付款仅已授权；请在 Quickpay 后台捕获或取消它。Invalid refund amount: at most … 表示金额超过了已捕获付款的剩余可退金额。

面向开发人员：在创建付款链接之前，扩展会携带链接参数和订单触发 OpenCart 事件 qpg_quickpay_link_data。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Quickpay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Order statuses 部分中的状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上，还会删除其事件和启动动作，它们让回调和顾客返回在维护模式下得以通过）。如果开启了 Delete data，则其他网关设置（标题、说明、密钥、测试付款、捕获、日志记录）和日志都会被删除。如果关闭，则会保留它们，以便之后重新安装时使用。Quickpay 的付款和退款数据始终会被保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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