VibeFox Quickpay for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

WooCommerce：7.1 或更高版本，已安装并启用。没有它插件无法激活。

PHP：8.0 或更高版本。

Quickpay 账户：您需要从 Quickpay 管理后台获取两个值：某个 API 用户的 API 密钥（用于创建付款、扣款和退款），以及账户的私钥（用于验证 Quickpay 回调的签名）。Quickpay 中无需其他设置。您的网站必须可以从互联网访问，不能有密码保护或处于维护模式，以便 Quickpay 回调能够送达。

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

安装

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

2. 点击 Activate。

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

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

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

6. 选择扣款方式和付款后的订单状态，开启 Enable/Disable 并保存。当您的 Quickpay 账户处于测试模式时，开启 Test payments，并使用 Quickpay 测试卡完成一次付款。

配置

所有设置都在一个页面中：WooCommerce > Settings > Payments > Quickpay。在输入 API 密钥和私钥之前，付款方式列表中 Quickpay 会标记为需要设置，并在结账时隐藏，因为付款既无法创建也无法确认。

常规

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

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

Description：结账时付款方式下方显示的文字。默认：Pay securely by card or MobilePay on the Quickpay payment page.

Quickpay API 凭据

在 Quickpay 管理后台（manage.quickpay.net）中打开 Settings > Integration。复制某个 API 用户的 API 密钥（Settings > Users）以及账户的私钥。该部分还会显示您商店的回调 URL，格式类似 https://your-site/wc-api/qpg_quickpay/。每笔付款都会自动发送该 URL，因此无需在 Quickpay 中进行任何配置。

API key：某个 Quickpay API 用户的 API 密钥，用于创建付款、扣款和退款。

字段下方的 Test API key 按钮会通过已验证的请求检查您在字段中输入的密钥（若字段为空，则检查已保存的密钥）。它会返回 Connection successful — the API key is valid.、Quickpay rejected the API key.、API key is not configured.，或 Connection failed: 加上原因。

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

Test payments：Accept payments made with Quickpay test cards。Quickpay 没有单独的沙盒：当您的 Quickpay 账户处于测试模式时，付款使用测试卡进行，并被标记为测试。仅在测试期间开启。关闭时，测试付款永远不会将订单标记为已付款，而是会为订单添加一条备注。开启时，结账页面会显示 Test mode: Quickpay test cards are accepted. 默认：关闭。

付款

Capture：从银行卡扣款的时机。

Order status after payment：Quickpay 确认已扣款的付款后，订单所处的状态。状态会一次性设置，只发生一次状态变更，并只发送一组邮件。

高级

Debug log：Enable logging。日志位于 WooCommerce > Status > Logs，来源为 wcp_quickpay_gateway。错误和警告（例如被拒绝的回调以及 Quickpay API 错误）始终会被记录。开启后还会记录每个请求和回调。API 密钥、银行卡数据和顾客信息永远不会被记录。默认：关闭。

Delete data：Delete the gateway settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。订单数据（Quickpay 付款 ID、备注）始终会保留。默认：关闭。

结账

顾客选择付款方式（默认为 Quickpay，显示 Visa 和 Mastercard 图标）并提交订单。插件会为订单创建以订单币种计价的 Quickpay 付款，并为订单总额生成付款链接，然后将顾客引导至 Quickpay 付款窗口。顾客在该窗口中使用您 Quickpay 付款窗口中启用的某种方式付款。账单邮箱会传递给 Quickpay。当 Quickpay 提供您网站所用语言时，付款窗口会以该语言打开（丹麦语、德语、英语、西班牙语、芬兰语、法语、意大利语、荷兰语、挪威语、波兰语、瑞典语），否则以英语显示。

付款后，顾客会返回您店铺的订单接收页面。返回本身不会将任何内容标记为已付款。只有在 Quickpay 通过已签名的回调确认，且金额和币种与订单一致后，订单才会标记为已付款。使用 Authorize only 时，订单会转为「保留」状态，您稍后再进行扣款。

如果顾客在结账期间在付款窗口中取消，未付款订单会按 WooCommerce 的标准方式取消，购物车会被恢复。在 Pay for order 页面中取消，会将顾客带回该页面，因此订单仍可付款。失败或已取消的付款可以重试：新的尝试会以新链接复用订单的 Quickpay 付款，因此旧链接永远无法被并行付款。取消未付款订单时，其付款链接会在 Quickpay 中被删除。

如果无法启动付款，顾客会看到 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.

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

本插件仅支持一次性付款。不支持订阅或定期付款、不保存银行卡、无付款手续费，不向 Quickpay 发送购物车或发票明细，也没有单独的 MobilePay、Apple Pay 或 Klarna 方式：顾客在您的 Quickpay 付款窗口中可用的方式中选择。

订单与退款

订单状态

Pending payment：顾客已被转到 Quickpay，但尚未付款。使用自动扣款时，等待扣款的已授权付款会记录在订单中。

Processing or Completed：Quickpay 已以正确的金额和币种确认已扣款的付款。状态遵循 Order status after payment。订单备注会显示 Quickpay 付款 ID（测试付款会标记为 TEST），并将其保存为订单的交易 ID。

On hold：付款仅已授权，等待 Capture Quickpay payment；或 Quickpay 报告的金额或币种与订单总额不同（例如付款开始后订单被修改，或在 Quickpay 管理后台扣除了不同金额）；或扣款失败，金额仍仅处于预留状态。订单备注会对此进行说明，即使订单已处于「保留」状态也会如此。

Failed：付款尝试被拒绝。顾客可以再次付款。

Cancelled：顾客在付款窗口中取消，订单被您取消或因 WooCommerce 库存保留超时而取消，或付款在 Quickpay 管理后台被取消。

对于已付款、已取消或已退款的订单，若收到新的付款，不会改变订单。备注会提醒您在 Quickpay 管理后台核实该付款，例如用于退还重复付款。

扣款

使用 Authorize only 时，打开订单，在订单操作中选择 Capture Quickpay payment，然后点击更新按钮。将扣除订单总额；不支持部分扣款。如果 Quickpay 立即确认，订单会被标记为已付款。否则，备注会说明已请求扣款，待 Quickpay 回调确认后再将订单标记为已付款。被拒绝的扣款会显示在订单页面并记录在订单备注中。

取消已授权的订单不会自动释放预留金额。订单备注会提醒您在 Quickpay 管理后台取消付款；否则，预留将在授权过期时结束。

退款

打开订单，点击 Refund，输入金额，然后点击 Refund via Quickpay。已扣款的付款支持全额和部分退款。Quickpay 异步处理退款：备注会说明退款已请求，回调会添加最终结果，即 confirmed 或 FAILED 及原因。如果 Quickpay 立即拒绝退款，WooCommerce 会显示错误，且不会记录任何退款。未曾扣款的已授权付款无法退款；请在 Quickpay 管理后台将其取消。

直接在 Quickpay 管理后台进行的付款和退款，仅会在订单上做备注，不会自动记录为 WooCommerce 退款。如有需要，可在 WooCommerce 中不使用 Refund via Quickpay 而创建手动退款。

许可证密钥

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

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

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

许可证到期后，插件仍会继续运行，但更新和支持需要续订。状态会在后台自动重新检查。

故障排除

Quickpay 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及 API key 和 Private key 是否均已填写。缺少任一密钥时，该付款方式都会被隐藏。

付款已完成，但订单仍为 Pending payment：Quickpay 回调未能到达您的店铺或被拒绝。请检查您的网站是否可从互联网访问（无密码保护或维护模式），以及 Private key 是否为同一 Quickpay 账户的私钥。被拒绝的回调始终会记录在 WooCommerce > Status > Logs 中，来源为 wcp_quickpay_gateway。开启 Debug log 可查看每一次回调。

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

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

日志显示 Callback: no order found for payment …：该回调属于一笔本店铺任何订单都不知道的 Quickpay 付款，例如在 WooCommerce 之外创建的付款，或针对已删除订单的付款。

日志显示 Callback: order #… is locked by another request.：同一订单的另一个回调当时正在处理中。该回调会收到错误响应，因此不会被视为已处理。如果订单保持不变，请在 Quickpay 管理后台检查付款。

测试付款未将订单标记为已付款：Test payments 处于关闭状态。订单备注会提示测试付款未被接受。测试时请开启此设置，账户正式上线后请关闭。

付款后订单处于 On hold 状态：请阅读订单备注。付款可能仅已授权，正等待 Capture Quickpay payment；已付金额或币种可能与订单不符；或扣款失败。请在 Quickpay 管理后台进行扣款、完成订单或退款。

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

顾客看到 The Quickpay payment could not be started.：请打开订单备注或日志。备注会显示 Quickpay 错误，例如您的 Quickpay 账户不接受的币种。

退款失败：订单必须有已扣款的 Quickpay 付款。消息 The Quickpay payment of this order has not been captured — there is nothing to refund. 表示该付款仅已授权；请改为在 Quickpay 管理后台取消。

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

卸载

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

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