VibeFox HyperPay for OpenCart — 帮助

系统要求

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

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 购买。一个密钥只能用于一个域名。

安装

下载的是一个 zip 文件，内含适用于两个 OpenCart 版本的安装包。请在您的计算机上解压。其中包含 README.txt、OpenCart 3 安装包 wcp_hyperpay_payment_gateway-oc3-(版本).ocmod.zip 和 OpenCart 4 安装包 wcp_hyperpay_payment_gateway.ocmod.zip。只需安装适用于您 OpenCart 版本的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

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

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

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

OpenCart 4

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

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

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

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

新安装时，付款方式默认关闭，测试模式默认开启。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox HyperPay Payment Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，只要测试模式开启，页面就会显示 Test mode is on: payments go to the HyperPay test system and no real money is charged. 如果当前模式缺少 Access Token 或 Entity ID（此时结账时不会显示该付款方式），或者当前模式没有有效的 Webhook 密钥（此时只有顾客返回商店后才会确认付款），页面都会提示您。如果您没有修改扩展的权限，页面会显示设置，但无法保存。

保存时，Title 不能为空，且最多 128 个字符；Transaction Type 必须有效；Sort Order 必须是整数；Total 必须是大于或等于 0 的数字；地区（geo zone）和订单状态必须存在；否则不会保存任何内容。凭据中的空格会被去除。如果某个 Webhook 密钥不是 64 位十六进制密钥，或者未勾选任何支付品牌，设置仍会保存，但会显示警告。

HyperPay

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

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

Description: 顾客在 Confirm Order 步骤中、确认按钮上方、银行卡图标下方看到的文字。默认：Pay securely using your credit or debit card.

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

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

Total: 订单必须达到的结账金额（以商店默认货币计）才会提供 HyperPay。留空则对任何金额都提供 HyperPay。

API 凭据

Access Token、Entity ID 和 Webhook 密钥都是在商户账户设置完成后由 HyperPay 提供的。测试和正式凭据是不同的。Webhook 密钥显示在 HyperPay 控制面板的 Administration > Webhooks 下。该部分包含指向 HyperPay 网站和开发者文档的链接。

Test Mode：使用 HyperPay 测试系统（eu-test.oppwa.com）和测试凭据。不会扣除真实款项。关闭后，将使用正式凭据（eu-prod.oppwa.com）接受真实付款。默认：开启。开启期间，顾客在 Confirm Order 步骤会看到 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 密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value on save，然后点击 Save。

Webhook

即使顾客在返回商店之前关闭了浏览器，Webhook 也会将付款信息通知给您的商店。在 HyperPay 控制面板（Administration > Webhooks）中，添加一个付款 Webhook，URL 使用本部分 Webhook URL 中显示的地址。在 OpenCart 3 中，该地址的格式类似 https://your-store/index.php?route=extension/payment/wcp_hyperpay_payment_gateway/webhook；在 OpenCart 4 中为 https://your-store/index.php?route=extension/wcp_hyperpay_payment_gateway/payment/wcp_hyperpay_payment_gateway.webhook。该地址由您的 OpenCart 安装的店铺前台地址生成。请完全按照设置中显示的内容复制 URL。然后将 Webhook 解密密钥复制到对应模式的 Test Webhook Key 或 Live Webhook Key 中。

HyperPay 的 Webhook 是加密的（AES-256-GCM）。无法用您的密钥解密的 Webhook 会被拒绝。只处理付款通知，并且付款必须属于您某个订单的结账记录，且创建时所用模式与解密该通知的密钥一致。HyperPay 的测试通知会被确认。Webhook 还会报告在 HyperPay 控制面板中进行的扣款、撤销、退款和拒付（参见订单和退款）。如果没有 Webhook，只有在顾客付款后返回商店时，付款才会被确认。即使商店处于维护模式，Webhook 仍然有效：OpenCart 3 会放行付款扩展的请求，而在 OpenCart 4 中，本扩展会添加一个启动动作，放行 Webhook 以及顾客从 HyperPay 返回的请求。

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 通常使用各自独立的实体，而本扩展不支持这些实体。

订单

OpenCart 在 Confirm Order 步骤创建订单时没有状态（即缺失订单）。只有在 HyperPay 确认付款后，订单才会获得状态。被拒绝或放弃的付款会使订单保持无状态，购物车也会保留。下面每个字段都列出了您的 OpenCart 订单状态。OpenCart 没有 On hold 状态，因此其中三项默认为待处理；您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Order Status After Payment：当 HyperPay 确认金额和币种正确的扣款，或预授权被扣款时设置。默认：处理中。

Authorized (Capture Required) Status：预授权已预留金额；请在订单选项卡中进行扣款。在 HyperPay 控制面板中进行撤销时，只要订单处于此状态，订单就会被取消。默认：待处理。

Awaiting Payment Status：HyperPay 报告付款正在等待确认；Webhook 会在稍后确认。默认：待处理。

On Hold (Review) Status：已付金额或币种与订单不一致，或者付款是在订单取消后到达的。备注会说明原因。默认：待处理。

Canceled Status：在 HyperPay 中撤销预授权时设置。针对此状态订单的付款会将其置于挂起状态，而不是重新打开。默认：已取消。

Refunded Status：针对此状态订单收到的付款只会被记录，订单不会被更改。默认：已退款。

高级

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

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

Delete Data on Uninstall：开启后，卸载扩展时会删除设置和日志文件。订单和 HyperPay 付款记录始终会保留，因为延迟到达的 Webhook 和已有订单的扣款需要用到它们。默认：关闭。

导入 / 导出

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

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

结账

在 Payment Method 步骤，顾客选择付款方式（默认为 Credit/Debit Card (HyperPay)）。在 Confirm Order 步骤，顾客会看到您的说明。OpenCart 在此步骤创建订单，仍然没有状态。顾客点击 Confirm Order 后，扩展会按订单金额和订单币种准备一个 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 分钟；超过后将准备新的结账会话。

在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。默认情况下，OpenCart 4 不会要求填写付款地址；此时扩展会将配送地址作为账单地址发送给 HyperPay。

付款后，顾客返回您的商店。扩展会核实该付款属于此订单的某个结账会话，并以创建结账会话时所用的模式，通过服务器对服务器的请求向 HyperPay 查询结果。只有在 HyperPay 确认后，订单才会被标记为已付款：无论是通过该请求还是通过 Webhook。金额和币种必须与订单一致。同一时刻到达的返回请求与 Webhook，以及同一购物车两个订单的结果，都会依次处理，因此付款绝不会被重复应用。随后，订单按 OpenCart 的标准方式获得状态，并发送常规的订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。

如果付款未完成，顾客会返回结账页面并看到提示：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. 购物车会被保留，顾客可以再次付款。如果无法准备付款表单，顾客会停留在 Confirm Order 步骤，并看到一条简短提示，例如付款服务商不接受部分账单信息，或由于付款配置错误而无法使用付款表单。技术原因会写入日志。

在 OpenCart 4 中，这些提示会显示在结账页面上方。OpenCart 3 每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账的订单，因此付款被拒绝后，顾客会用新的付款尝试支付同一订单。如果同一购物车已通过另一个订单付款，顾客将被引导至成功页面，而不会再次付款。购物车的任何更改（包括数量变化）都会被视为需要单独付款的新购物车。

OpenCart 4 会将订单保留在结账中，直到显示成功页面。如果该订单期间未付款即已关闭（例如您取消了它），顾客会被送回结账页面并显示 Payment failed. Please try again or use another card. 如果该订单已付款，随后被取消或退款，提示为 Your previous order was closed by the store. Please confirm the order again to pay with a new order. 如果订单已付款，而购物车现在包含新的商品，提示为 Your previous order #(编号) has already been placed. Your cart has changed: please confirm the new order to pay for it. 在每种情况下，下一次 Confirm Order 都会为购物车支付一个新订单。已付款的订单绝不会被显示为已为其他购物车付款。

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

本扩展不支持从 OpenCart 进行退款或撤销，不支持保存银行卡或令牌化，不支持订阅，不支持 Apple Pay 域名验证，不支持按品牌设置独立实体，也不支持 Tabby、Tamara 或其他先买后付（buy now, pay later）方式。

订单和退款

订单状态

No status (missing order)：顾客已被引导至付款页面但未付款，付款被拒绝，或 HyperPay 尚未确认付款。在 Sales > Orders 中，此类订单只会在 Order Status 筛选器设置为 Missing Orders 时显示。

Order Status After Payment (default Processing)：借记付款已确认，或预授权已扣款。备注会显示 HyperPay 的结果代码、描述和付款 ID。如果 HyperPay 将付款标记为需要人工审核，备注会注明；发货前请先在 HyperPay 控制面板中查看。

Authorized (Capture Required) Status (default Pending)：金额已由预授权预留。请在订单选项卡或 HyperPay 控制面板中进行扣款；扣款 Webhook 随后会将订单转入 Order Status After Payment。

Awaiting Payment Status (default Pending)：HyperPay 将付款报告为待处理。HyperPay 确认后，订单会转入 Order Status After Payment。

On Hold (Review) Status (default Pending)：HyperPay 报告的金额或币种与订单不一致（例如，在付款页面打开后购物车被修改），或者付款是在订单取消后到达的。备注会说明情况。请在 HyperPay 控制面板中检查付款，然后完成订单或退款。

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

被拒绝的结果绝不会更改已有状态的订单。如果已付款订单又收到另一笔成功付款，或者同一已付款购物车中的另一个订单被付款，则已付款订单不会被更改。备注会提示您在 HyperPay 控制面板中对重复付款进行退款。针对 Refunded Status 订单的成功付款只会添加一条备注。

备注是订单 History 中的条目，顾客看不到。

VibeFox HyperPay Payment Gateway 选项卡

在 Sales > Orders 中打开一个通过 HyperPay 付款的订单。在订单页面底部、History 和 Additional 旁边，VibeFox HyperPay Payment Gateway 选项卡会显示付款 ID（扣款后还会显示扣款 ID），测试付款会带有 Test mode 标签，并显示交易类型、结账 ID、商户交易 ID、发送给 HyperPay 的金额、结果以及订单的 HyperPay notes。该选项卡仅显示给有权访问该扩展的用户。

扣款

对于尚未扣款的预授权订单，选项卡会显示 Capture payment 及金额。点击后确认 Capture the pre-authorized amount through HyperPay?。将以预授权时所用的模式扣除当前订单总额，因此该模式的 Access Token 和 Entity ID 必须已设置。您需要具备修改扩展的权限（在 System > Users > User Groups 中设置）。扣款成功后，订单会获得 Order Status After Payment，扣款 ID 会添加到选项卡和备注中。状态会被直接写入，不发送订单邮件，也不更新库存。如果 HyperPay 拒绝扣款，会显示结果代码和描述，并添加到备注中，订单保持已授权状态。双击不会扣款两次。预授权的撤销（void）需在 HyperPay 控制面板中进行。

退款

不支持从 OpenCart 退款。Sales > Returns 中的商品退货不会通过 HyperPay 退还款项。请在 HyperPay 控制面板中退款。在 HyperPay 中进行的退款和拒付会由 Webhook 作为备注添加到订单中；订单状态不会改变。如有需要，请手动更新。

许可证密钥

本扩展需要配合来自 vibefox.net 的 VibeFox 许可证密钥使用。许可证区块 License — VibeFox HyperPay Payment Gateway 位于 Extensions > Extensions > Payments > VibeFox HyperPay Payment Gateway > Edit 页面，是设置上方的第一个区块。将密钥粘贴到 License key 中，然后点击 Activate。之后，该区块会以掩码形式显示密钥、状态（例如许可证有效期截止日期以及您的域名），并提供以下按钮：Check now（重新检查状态）、Change key（输入其他密钥）和 Remove key（从本商店移除密钥）。其下方有一行 Product: opencart-payment-hyperpay，以及一个链接 Manage licenses and domains in your account，点击后会打开您的 vibefox.net 账户。只有拥有该扩展 Modify 权限的管理员用户才能更改密钥。该区块的文字跟随管理后台语言（包括英文和俄文）。

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

一个密钥只能用于一个域名：即 OpenCart 配置中的商店地址。从商店中移除密钥并不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。

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

许可证过期后，扩展仍可继续运行，但更新和支持需要续订。打开后台的 Dashboard 或 Edit 页面时会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载扩展时总会删除许可证密钥和许可证状态。

故障排除

结账时不显示 HyperPay：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式是否已填写 Access Token 和 Entity ID：测试模式使用测试凭据，正式模式使用正式凭据。如果缺少这些信息，设置页面会显示警告。另外请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到了设置中的 Total。

付款已完成，但订单仍无状态：Webhook 没有生效，而且顾客没有返回商店。请在 HyperPay 控制面板中检查您所用模式的付款 Webhook 是否存在，其 URL 是否与 Webhook URL 中显示的完全一致，以及其解密密钥是否位于同一模式的 Webhook 密钥字段中。开启 Enable Logging，并查看扩展页面上的 Log 字段。

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

Webhook 返回 Webhook key not configured：未设置有效的 Webhook 密钥。请将 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 启用。

顾客看到 The payment session was not found. Please confirm the order again.：该订单的付款页面链接已失效。顾客需在结账页面重新确认订单。

Order is in the on hold status：请阅读订单选项卡中的备注（参见订单状态），在 HyperPay 控制面板中检查付款，然后完成订单或退款。

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

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox HyperPay Payment Gateway 旁边的 Uninstall（红色的 − 按钮）。该扩展的许可证密钥和许可证状态始终会被删除。OpenCart 始终会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。在 OpenCart 4 中，还会移除该扩展的事件及其启动动作（维护模式下放行 Webhook 和顾客返回请求的动作）。如果 Delete Data on Uninstall 已开启，其余设置（标题、说明、测试模式、凭据、Webhook 密钥、交易类型、品牌、日志）和日志文件都会被删除。如果未开启，这些内容会保留，以便之后重新安装时使用。HyperPay 付款记录始终会保留，因此延迟到达的 Webhook 以及已有订单的扣款在重新安装后仍然有效。已有订单会保留其付款备注。

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

HyperPay 是其各自所有者的商标。本扩展与 HyperPay 无关联，也未获得 HyperPay 的认可或背书。