VibeFox Quickpay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

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

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

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

安装

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

2. 上传完成后，点击 Configure，或之后在模块列表中找到 VibeFox Quickpay Gateway 并点击 Configure。

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

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

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

安装时，模块会创建一个订单状态：Quickpay payment on hold。PrestaShop 会为所有币种、国家和客户组启用新的付款模块。该模块会关联安装时已启用的国家。您可以在 Payment > Preferences 中修改所有这些设置。

配置

所有设置都在模块页面：Modules > Module Manager > VibeFox Quickpay Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在保存 API 密钥和私钥之前，页面会显示 Quickpay 需要设置：请输入 API 密钥和私钥。两者都保存之前，结账时会隐藏该付款方式。 当 Test payments 开启时，页面会提醒您在 Quickpay 账户正式上线后将其关闭。

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 用户（Settings > Users）的 API 密钥以及账户的私钥。

Callback URL：显示您店铺的回调 URL。使用友好 URL 时，格式类似：https://your-shop/module/wcp_quickpay_gateway/callback。Quickpay 会在每次付款操作（授权、扣款、退款、取消）后调用该 URL。它会随每笔付款自动发送，因此无需在 Quickpay 中进行配置。

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

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

已保存的密钥不会再次显示。字段保持为空，并显示 已保存 — 留空即可保留。 只有需要更改时才输入新值。

清除已保存的密钥：勾选 API key 或 Private key，然后点击 Save 即可删除。字段留空则保留已保存的值。

Test payments：接受使用 Quickpay 测试卡完成的付款。Quickpay 没有单独的沙盒：当您的 Quickpay 账户处于测试模式时，付款会使用测试卡完成，并标记为测试付款。仅在测试期间开启。关闭时，测试付款永远不会将订单标记为已付款。开启时，结账页面会在付款方式下方显示 测试模式：接受 Quickpay 测试卡。 默认：关闭。

Test API key：此按钮会使用经过身份验证的请求向 Quickpay 检查 API key 字段中输入的密钥（如果字段为空，则检查已保存的密钥），但不会保存该密钥。结果会显示 连接成功 — API 密钥有效。、Quickpay 拒绝了 API 密钥。、未配置 API 密钥。，或者 连接失败：后跟原因。

付款

Capture：何时从银行卡扣款。

Order status after payment：Quickpay 确认已扣款的付款之后，订单所处的状态。

高级

Debug log：写入模块文件夹中的 logs/qpg_debug.log.php。该文件无法通过网页打开。错误和警告（例如被拒绝的回调和 Quickpay API 错误）始终会被记录。开启后，还会记录每个请求和回调的详细信息。API 密钥、银行卡数据和顾客信息绝不会被记录。默认：关闭。

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

Delete data：开启时，卸载模块会删除网关设置和日志。订单数据（Quickpay 付款、退款、备注）和订单状态 Quickpay payment on hold 始终会被保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为带银行卡图标的 Quickpay）并确认。模块会为购物车以购物车币种创建 Quickpay 付款，并为购物车总额创建付款链接，然后将顾客转到 Quickpay 付款窗口。此时尚不存在订单。顾客在 Quickpay 付款窗口中使用您已启用的付款方式之一完成付款。顾客的电子邮件地址会传递给 Quickpay。当 Quickpay 提供顾客语言时，付款窗口会以该语言打开（丹麦语、德语、英语、西班牙语、芬兰语、法语、意大利语、荷兰语、挪威语、波兰语、瑞典语），否则以英语打开。

付款后，顾客返回您的店铺。返回本身不会将任何内容标记为已付款。只有在 Quickpay 确认后，订单才会被标记为已付款：当扣款金额和币种与购物车一致时，经过签名的回调会创建订单。随后，顾客会看到标准的订单确认页面。使用 Authorize only 时，订单会改为以 Quickpay payment on hold 状态创建，您稍后再扣款。如果顾客返回时回调尚未到达，Payment confirmation 页面会显示 Quickpay 正在确认您的付款。订单确认后，您将收到一封电子邮件。 并提供 Check again 和 Back to checkout 按钮。

如果顾客在付款窗口中取消，付款链接会在 Quickpay 中被删除，顾客会返回结账页面，并显示 付款已取消。您可以重试或选择其他付款方式。 如果银行卡被拒绝，提示为 付款未完成。您可以重试或选择其他付款方式。 购物车会被保留。新的尝试会使用购物车的 Quickpay 付款并生成新链接，因此旧链接永远无法被并行付款。当购物车的某笔付款已授权并等待扣款时，不会发起第二笔付款；顾客会看到 Payment confirmation 页面。

如果无法发起付款，顾客会停留在结账页面，并显示 无法发起 Quickpay 付款。请重试或选择其他付款方式。 技术原因会写入日志。如果缺少密钥，提示为 Quickpay 目前不可用。请选择其他付款方式。

即使店铺处于维护模式，回调仍然有效，并且不会受到店铺国家限制的阻挡。

本模块仅支持一次性付款。不支持订阅或定期付款、保存银行卡、部分扣款，也不会向 Quickpay 发送购物篮或发票明细，并且没有单独的 MobilePay、Apple Pay 或 Klarna 方式：顾客在您的 Quickpay 付款窗口提供的方式中进行选择。

订单与退款

订单状态

No order yet：顾客已被转到 Quickpay 但尚未付款，银行卡被拒绝，或付款已授权并等待自动扣款。此时仅存在购物车。

Payment accepted or Delivered：Quickpay 已确认金额和币种正确的已扣款付款。状态遵循 Order status after payment。付款会以 Quickpay 付款 ID 作为交易 ID 记录，备注中会显示该付款（测试付款会标记为 TEST）。

Quickpay payment on hold：付款仅已授权，正在等待 Capture Quickpay payment；或 Quickpay 报告的金额或币种与订单总额不同（例如，付款开始后购物车被修改，或在 Quickpay 管理后台扣除了不同的金额）；或自动扣款失败，金额仍仅为预留状态。备注会说明原因。当以不同金额完成扣款时，付款会以 Quickpay 实际扣款的金额记录在订单上。

Canceled：您取消了订单，或在 Quickpay 管理后台取消了保留订单的付款。

Refunded：付款已通过模块全额退款。

对于已付款、已取消或已退款的订单，如果收到新的付款，订单不会发生变化。备注会提醒您在 Quickpay 管理后台检查该付款，例如用于退还重复付款。

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

Quickpay 区块

订单页面会显示一个 Quickpay payment 区块，包含付款 ID、付款状态、金额和已退款金额、测试付款的 Test payment 标记、购物车的所有 Quickpay 付款列表（如果有多笔）、退款记录以及订单的 Quickpay notes。扣款和退款需要编辑订单的权限；无需访问模块页面。

扣款

使用 Authorize only 时，在 Quickpay 区块中点击 Capture Quickpay payment，并确认 通过 Quickpay 扣除订单总额？ 将扣除订单总额；不支持部分扣款。如果 Quickpay 立即确认，订单会被设置为 Order status after payment 的状态。否则，备注会说明已请求扣款，并在 Quickpay 回调确认后将订单标记为已付款。被拒绝的扣款会显示在区块中，并记录在订单备注中。

退款

在 Quickpay 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Quickpay。确认提示 通过 Quickpay 退还此金额？此操作无法撤销。 已扣款的付款支持全额和部分退款。退款以 Quickpay 实际扣款的金额和币种进行，因此在金额或币种不一致后，您最多只能退还顾客实际支付的金额，而不是订单总额。Quickpay 异步处理退款：退款记录会显示 requested，回调会将其更新为 confirmed 或 failed，并将结果添加到备注中。如果 Quickpay 立即拒绝退款，区块会显示错误，并且不会记录退款。全额退款会将订单设置为 Refunded；部分退款不会更改状态。从未扣款的已授权付款无法退款；请在 Quickpay 管理后台取消。

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

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

许可证密钥

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

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

一个密钥只能用于一个域名：即主店铺的域名，多店铺设置中亦然。从店铺中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

没有有效密钥时，结账页面不会向顾客显示 Quickpay。若仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法知道您已登录后台，因此该付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账页面进行测试。Modules > Module Manager 中的 Alerts 标签页会显示提醒。现有订单不受影响：已发起的付款仍会被核实和确认，扣款和退款也仍然可用。

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

故障排除

Quickpay 未出现在结账页面：请检查许可证是否有效、Enable/Disable 是否已开启，以及 API key 和 Private key 是否均已保存。两个密钥缺一不可，否则该付款方式会被隐藏。在 Payment > Preferences 中，检查该模块是否允许用于购物车币种、顾客所在国家和顾客所属客户组。

付款已完成，但未创建订单：Quickpay 回调未能到达您的店铺，或被拒绝。请检查您的店铺是否可从互联网访问（无密码保护），以及 Private key 是否为同一 Quickpay 账户的私钥。被拒绝的回调总会记录在模块页面的日志中。开启 Debug log 可查看每一次回调。

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

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

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

日志显示 Could not lock the cart 或 Cannot create the order：当时同一购物车的另一个回调正在处理，或订单无法创建（例如模块已禁用）。回调会收到错误响应，因此 Quickpay 会再次发送。

测试付款未将订单标记为已付款：Test payments 处于关闭状态。日志（如果订单已存在，还有备注）会显示测试付款未被接受。测试时请开启该设置，账户正式上线后再关闭。

付款后订单显示为 Quickpay payment on hold：请阅读 Quickpay 区块中的备注。付款可能仅已授权并等待 Capture Quickpay payment，已付金额或币种可能与订单不符，或扣款失败。请扣款、处理订单或退款。

Test API key 显示「Quickpay 拒绝了 API 密钥。」：密钥错误，或属于没有 API 权限的用户。请从 Quickpay 管理后台复制某个 API 用户的 API 密钥。

顾客看到「无法发起 Quickpay 付款。」：请查看模块页面上的 Log 字段。其中会显示 Quickpay 错误，例如您的 Quickpay 账户不接受的币种。

退款失败：订单必须有已扣款的 Quickpay 付款。提示 该订单的 Quickpay 付款尚未扣款 — 没有可退款的内容。 表示付款仅已授权；请在 Quickpay 管理后台扣款或取消。无效的退款金额：最多 … 表示金额超过了已扣款付款的剩余金额。

开发人员可以使用钩子 actionQpgQuickpayLinkData 修改 Quickpay 付款链接的参数。

卸载

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

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