VibeFox HyperPay for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本，并启用 OpenSSL 扩展（用于解密 Webhook）。缺少该扩展时，模块无法安装。

HyperPay 账户：商户账户开通时，HyperPay 会发放 Access Token 和 Entity ID。测试和正式凭据不同。您还需要在 HyperPay 控制面板中添加付款 Webhook，并获取其解密密钥（webhook key），该密钥显示在 Administration > Webhooks 下（参见配置）。

银行卡数据：银行卡仅在 HyperPay 小部件中输入，因此银行卡数据绝不会到达您的服务器（PCI DSS SAQ A）。

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

安装

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

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

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

4. 输入 HyperPay 发放的测试 Access Token、Entity ID 和 webhook key，并保持 Test Mode 开启。

5. 在 HyperPay 控制面板（Administration > Webhooks）中，使用 Webhook 部分显示的 URL 添加一个付款 Webhook，并将其解密密钥复制到相同模式的 webhook key 字段中。

6. 开启 Enable/Disable，点击 Save，并使用 HyperPay 测试卡完成一次测试付款。然后输入正式凭据，并关闭 Test Mode。

模块安装时会创建三个订单状态：Awaiting HyperPay payment、HyperPay payment authorized 和 HyperPay payment on hold。PrestaShop 会将新的付款模块与当时启用的币种、国家和客户组关联。之后启用的国家，必须在 Payment > Preferences 中允许。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure。每个部分都有各自的 Save 按钮，它会保存整个页面。当测试模式开启时，页面会在字段上方显示 Test mode is on: payments go to the HyperPay test system and no real money is charged.。如果当前模式缺少 Access Token 或 Entity ID，页面会发出警告（此时结账中不会显示该付款方式）；如果当前模式没有有效的 webhook key，页面也会发出警告（此时只有顾客返回商店时才会确认付款）。保存时，凭据中的空格会被去除；如果 webhook key 不是 64 位十六进制密钥，页面会发出警告。

HyperPay

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

Title：顾客在结账时看到的标题。它也是订单中保存的付款方式名称。默认：Credit/Debit Card (HyperPay)。必填。

Description：顾客在结账时看到的描述。默认：Pay securely using your credit or debit card.

API 凭据

Access Token、Entity ID 和 webhook key 由 HyperPay 在开通商户账户时发放。测试和正式凭据不同。webhook key 显示在 HyperPay 控制面板的 Administration > Webhooks 下。

Test Mode：使用 HyperPay 测试系统（eu-test.oppwa.com）和测试凭据。不会扣除真实资金。关闭后将使用正式凭据（eu-prod.oppwa.com）接收真实付款。默认：开启。开启期间，顾客会在付款方式下方看到 Test mode: no real payment will be made.

Test Access Token：您的 HyperPay 测试账户的 bearer token。

Test Entity ID：测试付款通道的 Entity ID。

Test Webhook Key：用于解密测试系统 Webhook 通知的 64 位十六进制密钥。

Live Access Token：您的 HyperPay 正式账户的 bearer token。

Live Entity ID：正式付款通道的 Entity ID。

Live Webhook Key：用于解密正式系统 Webhook 通知的 64 位十六进制密钥。

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

清除已保存的机密信息：勾选某个 token 或密钥，然后点击 Save 即可将其删除。字段留空则保留已保存的值。

Webhook

即使顾客在返回商店前关闭了浏览器，Webhook 也会将付款信息告知您的商店。在 HyperPay 控制面板（Administration > Webhooks）中，使用本部分 Webhook URL 显示的 URL 添加一个付款 Webhook。若启用了友好 URL，其形式如 https://your-shop/module/wcp_hyperpay_payment_gateway/webhook，前面可能带有语言代码，例如 /en/。请完全按照设置中显示的样子复制 URL。然后将 Webhook 解密密钥复制到相同模式的 Test Webhook Key 或 Live Webhook Key 中。

HyperPay 的 Webhook 是加密的（AES-256-GCM）。无法用您的密钥解密的 Webhook 会被拒绝。只处理付款通知，并且付款必须属于您某个购物车的付款会话，且该会话须与解密它的密钥属于同一模式。HyperPay 的测试通知会被确认。Webhook 还会报告在 HyperPay 控制面板中进行的扣款、冲正、退款和拒付（chargeback）（参见订单和退款）。如果没有 Webhook，只有顾客付款后返回商店时，付款才会被确认。

Payment

Transaction Type：银行卡的扣款方式。

Payment Brands：付款小部件中显示的品牌：VISA、Mastercard、mada、American Express、STC Pay、Apple Pay。默认：VISA 和 Mastercard。如果未勾选任何品牌，页面会发出警告，小部件将显示 VISA 和 Mastercard。请只选择 HyperPay 已为您的 Entity ID 启用的品牌；mada、STC Pay 和 Apple Pay 通常使用各自的独立 entity，本模块不支持。

Advanced

Enable Logging：将 API 请求和响应记录到模块文件夹中的 logs/hyperpay_p_debug.log.php。该文件无法通过网页打开。错误和警告始终会被记录。日志不包含银行卡数据、密钥或顾客数据。默认：关闭。

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

Delete Data on Uninstall：开启后，卸载模块时会删除设置、HyperPay 付款尝试表以及日志文件。订单和模块的订单状态会被保留。默认：关闭。

结账

在付款步骤中，顾客选择付款方式（默认为 Credit/Debit Card (HyperPay)）并确认订单。模块会以购物车总额和购物车币种创建一个 HyperPay 付款会话，并打开商店的 HyperPay payment 页面，其中包含 HyperPay 小部件和 Please complete your payment below: 提示。HyperPay 支持时，小部件使用顾客的语言。测试模式下，页面会显示 Test mode: use a HyperPay test card, no real payment will be made. 顾客在小部件中输入银行卡信息，或点击 Choose another payment method 返回结账页面。此时尚未创建订单。在购物车未发生变化的情况下，重新加载页面会在最多 25 分钟内复用同一个付款会话。

付款后，顾客返回您的商店。模块会检查该付款是否属于此购物车的某个付款会话，并以服务器对服务器的请求向 HyperPay 查询结果，查询使用创建该会话时的模式。只有当 HyperPay 确认付款（通过该查询或通过 Webhook）后，订单才会被标记为已付款。金额和币种必须与购物车一致。如果返回请求与 Webhook 同时到达，它们会依次处理，因此订单绝不会被创建两次。付款确认后，将创建订单，顾客会看到标准的订单确认页面。

如果付款未成功，顾客会返回结账页面，并看到提示：Payment failed: 以及 HyperPay 给出的原因，Payment was not completed. Please try again.，或 We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. 购物车会被保留，顾客可以再次付款；每次新的尝试都会获得新的 HyperPay 付款会话。如果无法准备付款表单，顾客会停留在结账页面，并看到一条简短提示，例如付款服务商未接受部分账单信息，或由于付款配置错误，付款表单不可用。技术原因会被写入日志。

根据 HyperPay API 的要求，金额以两位小数发送。对于三位小数的币种（KWD、BHD、JOD、OMR），购物车总额会四舍五入到两位小数。

即使商店处于维护模式，Webhook 仍可正常工作，并且不受商店国家限制的影响。

本模块不支持通过 PrestaShop 进行退款或撤销、不支持保存银行卡或令牌化、不支持订阅、不支持 Apple Pay 域名验证、不支持按品牌分别使用独立 Entity ID，也不支持 Tabby、Tamara 或其他先买后付方式。

订单和退款

订单状态

No order yet：顾客已被引导至付款页面但尚未付款，付款被拒绝，或 HyperPay 尚未确认付款。此时只存在购物车。

Payment accepted：借记付款已确认，或预授权已扣款。付款会以 HyperPay 付款 ID 作为交易 ID 记录，并且一条私人备注会显示 HyperPay 结果代码、说明和付款 ID。如果 HyperPay 将该付款标记为需要人工审核，备注会注明；发货前请在 HyperPay 控制面板中核实。

HyperPay payment authorized：金额已通过预授权预留。请在订单的 HyperPay 区块或 HyperPay 控制面板中扣款；扣款 Webhook 随后会将订单转为 Payment accepted。

Awaiting HyperPay payment：HyperPay 将付款报告为待处理。HyperPay 确认付款后，订单会转为 Payment accepted。

HyperPay payment on hold：HyperPay 报告的金额或币种与购物车或订单不一致（例如，在打开付款页面后修改了购物车），或者付款是在订单被取消之后到达的。备注会说明原因。请在 HyperPay 控制面板中核实该付款，然后完成订单或退款。

Canceled：预授权已在 HyperPay 控制面板中被撤销，撤销 Webhook 会取消已授权的订单。

被拒绝的结果绝不会更改现有订单。如果已付款的订单又收到另一笔成功付款，订单不会改变。备注会提示您在 HyperPay 控制面板中退还重复付款。对已退款订单收到的成功付款，只会添加一条备注。

HyperPay 付款区块

订单页面会显示一个 HyperPay payment 区块，包含付款 ID（扣款后还会显示扣款 ID）、交易类型、付款会话 ID、商户交易 ID、发送给 HyperPay 的金额、结果，以及测试付款的 Test mode 标记。模块的备注位于订单的私人消息中。

扣款

对于状态为 HyperPay payment authorized 的订单，该区块会显示带金额的 Capture payment。点击并确认 Capture the pre-authorized amount through HyperPay?。系统将以预授权时所用的模式扣除订单当前总额，因此该模式的 Access Token 和 Entity ID 必须已设置。您需要编辑订单的权限；无需访问模块页面。扣款成功后，订单转为 Payment accepted，扣款 ID 会添加到付款记录和备注中。如果 HyperPay 拒绝扣款，结果代码和说明会显示并添加到备注中，订单保持已授权状态。重复点击不会扣款两次。预授权的撤销（void）需在 HyperPay 控制面板中完成。

退款

不支持通过 PrestaShop 退款，PrestaShop 的标准退款按钮也不会通过 HyperPay 退回款项。请在 HyperPay 控制面板中退款，并在需要时通过部分退款或贷项单在 PrestaShop 中记录。在 HyperPay 中进行的退款和拒付会由 Webhook 作为备注添加到订单中；订单状态不会改变。

许可证密钥

本模块需要使用从 vibefox.net 获取的 VibeFox 许可证密钥。许可证区块 License — VibeFox HyperPay Payment Gateway 是 Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure 页面顶部的第一个区块，位于设置上方。请将密钥输入 License key，然后点击 Activate。之后，该区块会以遮蔽形式显示密钥，并显示状态（例如许可证有效期截止日期和您的域名），以及以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除该密钥）。其下方有一行 Product: presta-payment-hyperpay，以及 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 账户中释放该名额。

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

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

故障排除

结账时不显示 HyperPay：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否已设置其 Access Token 和 Entity ID：测试模式使用测试凭据，正式模式使用正式凭据。如果缺少这些凭据，设置页面会显示警告。在 Payment > Preferences 中，请确认模块已允许用于购物车币种、顾客所在国家和顾客所属客户组。

付款已完成，但未创建订单：Webhook 无法正常工作，并且顾客没有返回商店。请在 HyperPay 控制面板中确认您所用模式的付款 Webhook 已存在，其 URL 与 Webhook URL 中显示的完全一致，并且其解密密钥位于相同模式的 webhook key 字段中。请开启 Enable Logging，并查看模块页面上的 Log 字段。

Webhook 返回 Decryption failed：该 webhook key 属于另一个 Webhook 或另一种模式。请从 HyperPay 控制面板重新复制密钥。

Webhook 返回 Webhook key not configured：未设置有效的 webhook key。请将 64 位密钥粘贴到设置中。HyperPay 会重试该 Webhook。

Webhook 返回 Busy, retry later：该订单在同一时刻正被另一个请求处理，或订单无法创建（例如模块已被禁用）。HyperPay 会重试该 Webhook。原因记录在日志中。

日志显示 Webhook ignored：该付款不属于本商店的任何购物车，或者是在另一种模式下完成的。测试付款与正式付款是分开保存的。

Webhook URL 在浏览器中显示 Method not allowed：这是正常现象。该 URL 只接受来自 HyperPay 的 POST 请求。

付款表单无法加载：请查看日志。配置错误通常意味着当前模式的 Access Token 或 Entity ID 有误。关于账单信息的提示表示 HyperPay 未接受部分顾客数据。请确保所选的 Payment Brands 已为您的 Entity ID 启用。

订单处于 HyperPay payment on hold：请阅读订单备注（参见订单状态），在 HyperPay 控制面板中核实付款，然后完成订单或退款。

扣款失败：请阅读区块和备注中的结果代码与说明。扣款是以预授权的模式发送的，因此该模式的凭据必须已设置；否则区块会提示该模式的 Access Token / Entity ID 为空。

卸载

进入 Modules > Module Manager，打开 VibeFox HyperPay Payment Gateway 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete Data on Uninstall 已开启，设置、HyperPay 付款尝试表和日志文件都会被删除。如果已关闭，所有内容都会保留，以便日后重新安装。订单状态 Awaiting HyperPay payment、HyperPay payment authorized 和 HyperPay payment on hold 始终会被保留。现有订单会保留其付款备注和交易 ID。

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