VibeFox HyperPay for WooCommerce — 帮助

系统要求

WordPress：6.0 或更高版本。

WooCommerce：8.0 或更高版本，已安装并启用。未安装时插件无法激活。

PHP：8.0 或更高版本。

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

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

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

安装

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

2. 点击 Activate。

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

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

5. 输入 HyperPay 提供的测试 Access Token、Entity ID 和 Webhook 密钥，并保持 Test Mode 开启。

6. 在 HyperPay 控制面板（Administration > Webhooks）中添加付款 Webhook，URL 使用设置中显示的地址，并将其解密密钥复制到相同模式的 Webhook key 字段中。

7. 开启 Enable/Disable，使用 HyperPay 测试卡进行一次测试付款。然后输入正式凭据，并关闭 Test Mode。

配置

所有设置都位于同一页面：WooCommerce > Settings > Payments > HyperPay。在字段上方，测试模式开启时页面会显示 测试模式已开启：付款将发送到 HyperPay 测试系统，不会扣除任何真实款项。 在测试模式开启期间会显示此信息。当前模式缺少 Access Token 或 Entity ID 时（此时该付款方式不会在结账时显示），以及当前模式没有有效 Webhook 密钥时（此时付款仅在顾客返回商店后确认），页面都会发出警告。在付款方式列表中，在当前模式填写 Access Token 和 Entity ID 之前，该网关会被标记为需要设置。保存时会删除凭据中的空格；如果 Webhook 密钥不是 64 位十六进制密钥，页面会显示错误。

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 密钥由 HyperPay 在您的商户账户开通时提供。测试和正式凭据不同。Webhook 密钥显示在 HyperPay 控制面板的 Administration > Webhooks 下。

Test Mode：Enable Test Mode 使用 HyperPay 测试系统（eu-test.oppwa.com）和测试凭据。不会扣除任何真实款项。关闭后将使用正式凭据接受真实付款（eu-prod.oppwa.com）。默认：开启。

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 位十六进制密钥。

Webhook

即使顾客在返回商店之前关闭了浏览器，Webhook 也会将付款信息通知您的商店。在 HyperPay 控制面板（Administration > Webhooks）中，使用设置本部分显示的 URL 添加一个付款 Webhook。URL 格式如下：https://your-site/wp-json/hyperpay-p/v1/webhook。然后将 Webhook 解密密钥复制到相同模式的 Test Webhook Key 或 Live Webhook Key 中。

HyperPay Webhook 经过加密（AES-256-GCM）。无法使用您的密钥解密的 Webhook 会被拒绝。仅处理付款通知，且付款必须属于您某个订单的付款会话，并且该会话须与解密该通知的密钥处于相同模式下创建。HyperPay 测试通知会被确认接收。该 Webhook 还会报告在 HyperPay 控制面板中进行的扣款、冲正、退款和拒付（chargeback）（参见「订单与退款」）。若没有 Webhook，只有在顾客付款后返回商店时，付款才会被确认。

付款

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

Payment Brands：付款小部件中显示的品牌：VISA、Mastercard、mada、American Express、STC Pay、Apple Pay。默认：VISA 和 Mastercard。请仅选择 HyperPay 已为您的 Entity ID 启用的品牌；mada、STC Pay 和 Apple Pay 通常使用其自有实体，本插件不支持。

高级

Enable Logging：Log API requests and responses。调试信息写入 WooCommerce > Status > Logs，来源为 wcp_hyperpay_payment_gateway。错误始终会被记录。日志不包含银行卡数据、密钥或顾客数据。默认：关闭。

Delete Data on Uninstall：Delete all plugin data when the plugin is uninstalled。删除插件时移除设置和日志文件。保存在订单中的 HyperPay 数据会被保留。默认：关闭。

结账

顾客选择付款方式（默认为 Credit/Debit Card (HyperPay)），然后点击 Continue to payment。系统会创建订单，顾客进入 Pay for order 页面。插件会在该页面以订单币种为订单总额准备一个 HyperPay 付款会话，并显示 HyperPay 小部件，提示 请在下方完成付款：。当 HyperPay 支持时，小部件会使用您网站的语言。在测试模式下，页面会显示 测试模式：请使用 HyperPay 测试卡，不会进行真实付款。 顾客在小部件中输入银行卡信息。

付款后，顾客返回您的商店。插件会检查付款是否属于该订单的某个付款会话，并通过服务器对服务器的请求向 HyperPay 查询结果。只有在 HyperPay 确认后（通过该请求或 Webhook），订单才会被标记为已付款。金额和币种必须与订单一致。返回与 Webhook 同时到达时会依次处理，因此订单绝不会被重复处理。付款确认后，顾客将进入「订单已接收」页面。

若付款未成功，顾客将返回 Pay for order 页面，并显示消息：付款失败：及 HyperPay 给出的原因，付款未完成。请重试。，或 我们尚无法确认您的付款。如果您已被扣款，订单将自动更新；否则请重试。顾客可在同一页面再次付款。若无法准备小部件，顾客会看到一条简短消息，例如部分账单信息未被付款服务商接受，并看到一个 Try Again 按钮。详细信息会添加到订单备注中。

金额按 HyperPay API 的要求以两位小数发送。对于 3 位小数的币种（KWD、BHD、JOD、OMR），订单总额将四舍五入到两位小数。

该付款方式适用于经典结账、购物车与结账区块以及 Pay for order 页面。在测试模式下，结账区块会显示 测试模式：不会进行真实付款。 兼容 WooCommerce 高性能订单存储（HPOS）。

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

订单与退款

订单状态

Pending payment：顾客尚未付款、未完成小部件操作，或 HyperPay 尚未确认付款。

Processing：借记付款已确认，或预授权已扣款。仅包含虚拟可下载商品的订单将变为「已完成」，即 WooCommerce 的默认行为。订单备注会显示 HyperPay 结果代码、描述和付款 ID。交易 ID 即 HyperPay 付款 ID。如果 HyperPay 将付款标记为需要人工审核，备注中会注明；发货前请在 HyperPay 控制面板中检查。

On hold（预授权）：金额已预留。请通过订单操作 Capture HyperPay payment 或在 HyperPay 控制面板中进行扣款；随后扣款 Webhook 会完成订单。

On hold after payment：HyperPay 报告的金额或币种与订单不一致（例如在付款页面打开后订单被修改），付款在 HyperPay 仍处于待处理状态，或付款在订单被取消后才到达。订单备注会说明原因。请在 HyperPay 控制面板中检查该付款，并完成或退款。

Failed：HyperPay 拒绝了该付款。原因写在订单备注中，并会显示给顾客。被拒绝的尝试绝不会改变已付款、已预留、保留或已取消的订单。

Cancelled：预授权已在 HyperPay 控制面板中被冲正，冲正 Webhook 会取消保留中的订单。

若已付款的订单又收到另一笔成功付款，订单不会改变。备注会提示您在 HyperPay 控制面板中对重复付款进行退款。对已退款订单的成功付款仅会添加备注。

扣款（Capture）

订单操作 Capture HyperPay payment 会出现在尚未扣款的预授权保留订单上。它会按预授权时所用模式，扣除 WooCommerce 中已记录的退款后，对当前订单总额进行扣款。扣款成功后，订单变为 Processing。若 HyperPay 拒绝扣款，将显示结果代码和描述，并添加到订单备注中。预授权的撤销（void）需在 HyperPay 控制面板中进行。

退款

不支持通过 WooCommerce 退款。请在 HyperPay 控制面板中退还付款，然后在 WooCommerce 中使用 Refund manually 进行记录。在 HyperPay 中进行的退款和拒付会由 Webhook 作为备注添加到订单中；订单状态不会改变。

许可证密钥

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

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

没有有效密钥时，结账时不会向顾客显示 HyperPay。若仍然发起付款，顾客会看到 此付款方式不可用。请选择其他方式。 已登录的商店管理员仍可看到该付款方式，并标注 (unlicensed — visible to admins only)，以便您在购买密钥前进行设置和测试。插件列表页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已开始的付款仍会被确认，扣款也可以正常进行。

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

故障排除

结账时未显示 HyperPay：请检查许可证是否有效、Enable/Disable 是否开启，以及当前模式是否具有 Access Token 和 Entity ID：测试模式使用测试凭据，正式模式使用正式凭据。若缺少凭据，设置页面会显示警告。

付款已完成，但订单仍为 Pending payment：Webhook 未正常工作，且顾客没有返回商店。请在 HyperPay 控制面板中检查您所用模式的付款 Webhook 是否存在、其 URL 是否与设置中显示的完全一致，以及其解密密钥是否位于相同模式的 Webhook key 字段中。查看 WooCommerce > Status > Logs，来源为 wcp_hyperpay_payment_gateway。

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

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

日志显示 Webhook ignored：该付款不属于本店铺的订单，或其所用模式不同。测试付款与正式付款会被分开处理。

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

订单为 On hold，并带有金额/币种不一致的备注：HyperPay 报告的付款与订单总额或币种不符，例如付款页面打开后订单被修改。请在 HyperPay 控制面板中检查该付款，并完成或退款。

扣款失败：请阅读订单备注中的结果代码和描述。扣款会以预授权的模式发送，因此该模式的凭据必须已设置。

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

面向开发者：过滤器 hyperpay_p_icon 可更改付款方式图标。

卸载

停用插件会保留所有数据。要移除插件，请先停用，然后在 Plugins 页面中删除。本插件的许可证密钥和许可证状态始终会被移除。网关设置、插件的临时数据和日志文件只有在 Delete Data on Uninstall 已开启时才会被移除；否则会保留，以便日后重新安装。保存在订单中的 HyperPay 数据始终会被保留。现有订单会保留其付款备注和交易 ID。

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