VibeFox Hubtel for PrestaShop — 帮助

系统要求

PrestaShop：8.0 至 9.x。

PHP：8.0 或更高版本并启用 cURL 扩展。缺少这些时模块将拒绝安装。

货币：仅支持加纳塞地（GHS）。对于其他货币，付款方式在结账时会被隐藏。请将 GHS 货币的小数位数保持为 2，因为 Hubtel 按整数 pesewa 收费。

Hubtel 账户：拥有 API 密钥（API ID 和 API Key）及商户账号（POS Sales ID）的 Hubtel 商业账户。密钥可在 Hubtel 商业后台 bo.hubtel.com 的 Programmable keys 下找到。

IP 白名单：Hubtel 只会响应来自白名单服务器 IP 地址的 Transaction Status API 请求。请联系 Hubtel（您的客户经理或 support@hubtel.com），要求将您 Web 服务器的公网 IP 地址加入白名单。在此之前，付款无法被确认，也不会创建订单。

无测试环境：Hubtel 没有公开的沙盒环境。所有付款均为真实交易。

Cron：建议在服务器上设置一个 cron 任务，每 5 分钟调用一次模块的 cron URL，以进行后台付款检查（参见"配置"）。

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

安装

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

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

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

4. 输入 API ID、API Key 和商户账号（POS Sales ID）。

5. 请 Hubtel 支持人员将您服务器的 IP 加入 Transaction Status API 的白名单。

6. 将 Configure 页面上显示的 cron URL 添加到服务器的 cron 中。

7. 开启 Enable/Disable 并点击 Save。回调 URL 会随每笔付款发送给 Hubtel，因此无需在 Hubtel 后台进行任何设置。

安装时，模块会创建订单状态 Hubtel payment on hold。PrestaShop 会为所有货币、国家和客户群组提供一个新的付款模块。您可以在 Payment > Preferences 中限制这些范围。

配置

所有设置都位于模块页面：Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，如果 API ID、API Key 或商户账号缺失，或商店的默认货币不是 GHS，页面会向您发出警告。在这两种情况下，Hubtel 都会在结账时被隐藏。如果 GHS 货币使用了超过 2 位小数，页面也会发出警告。

Hubtel

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

Title：顾客在结账时看到的付款方式名称。它也会作为付款方式名称保存在订单中。默认：Mobile Money or card (Hubtel)。必填：标题为空会出现错误 Enter a title for the payment method.

Description：结账时显示在付款方式下方的文字。默认：Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. 随后将您转到 Hubtel 完成付款。

Hubtel API 凭据

从您的 Hubtel 商业后台复制 API ID 和 API Key：bo.hubtel.com > Programmable keys。商户账号即您 Hubtel 账户的 POS Sales ID。本部分还会重复显示 IP 白名单的提示。

API ID (Client ID)：您 Hubtel 程序化密钥的 API ID。

API Key (Client Secret)：您 Hubtel 程序化密钥的 API Key。请妥善保密。已保存的密钥不会再次显示。该字段保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。

Merchant account number (POS Sales ID)：付款将被收入此 Hubtel 账户，并以此账户进行核对。

Clear saved API Key：勾选并点击 Save，即可删除已保存的 API Key。字段留空则保留已保存的值。

付款确认

Callback URL：回调会告知您的商店已完成付款。该 URL 会随每笔付款发送给 Hubtel，因此无需在 Hubtel 后台进行任何设置。使用友好 URL 时，它的形式类似 https://your-shop/module/wcp_hubtel_pay/callback，前面可能带有语言代码。该 URL 必须可从互联网访问：不能有阻止 Hubtel 的密码保护或防火墙。商店处于维护模式时回调仍然有效，且不受商店国家限制的影响。

Hubtel 回调未签名。模块只从回调中获取付款参考编号；该参考编号必须属于您商店的付款。状态、金额和交易 ID 始终来自 Hubtel Transaction Status API。只有在该 API 确认付款及其金额之后，订单才会以已付款状态创建。

后台付款检查（cron）：带有秘密令牌的 cron URL。请在服务器的 cron 中每 5 分钟调用一次，例如使用 curl。未确认的付款随后会自动与 Hubtel 复核：顾客被转到 Hubtel 20 分钟后复核一次；若付款仍未完成，一小时后再复核一次；若无法连接 Hubtel，则以逐渐增加的间隔最多重试 5 次。请妥善保管该 URL。

高级

Debug log：将 API 调用和回调记录到模块文件夹中的 logs/hubtel_p_debug.log.php。该文件无法通过网页打开。密钥和顾客数据不会被记录。即使此选项关闭，错误和警告仍会被记录。默认：关闭。

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

Delete data on uninstall：开启后，卸载模块时会删除该模块的设置和日志。为订单保存的 Hubtel 数据以及 Hubtel payment on hold 订单状态始终保留。默认：关闭。

结账

在付款步骤，顾客选择付款方式（默认为 Mobile Money or card (Hubtel)）并确认。模块会为购物车总额创建 GHS 金额的 Hubtel 结账，并将顾客带到 Hubtel 付款页面。付款在该页面上将显示为 Cart #、购物车编号以及您的商店名称。在 Hubtel 页面上，顾客使用 MTN MoMo、Telecel Cash、AirtelTigo Money、Visa 或 Mastercard 银行卡或 GhQR 付款。此时尚未创建订单。付款步骤中的每次确认都会创建一个带有独立参考编号的新付款尝试，同一购物车之前的 Hubtel 页面仍可继续付款。

付款后，顾客返回您的商店。只有在 Hubtel 通过 Transaction Status API 确认之后，订单才会被标记为已付款：可能是通过回调、顾客返回时的检查、后台检查，或订单页面的按钮。回调和顾客返回同时到达时会依次处理，因此订单绝不会被创建两次。随后顾客会看到标准的订单确认页面。如果订单被置为保留，页面会显示 Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

如果顾客返回时 Hubtel 尚未确认付款，将显示 Payment confirmation 页面，内容为 We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. 并带有 Check again 和 Back to checkout 按钮。Hubtel 一确认付款，订单就会创建。如果 Hubtel 已将此付款尝试报告为失败，顾客会带着 The Hubtel payment was not completed. You can try again or choose another payment method. 的提示返回结账页面。购物车将被保留。

如果顾客在 Hubtel 页面上点击 Cancel，模块会先检查付款是否仍然完成。若未完成，顾客会带着 The Hubtel payment was cancelled. You can try again or choose another payment method. 的提示返回结账页面。购物车将被保留。之后通过已取消的 Hubtel 页面完成的付款仍会被接受。

如果 Hubtel 无法发起付款，顾客会停留在结账页面并看到简短提示，例如 Could not connect to Hubtel. Please try again in a moment.、Hubtel could not start the payment. Please try again or choose another payment method.，或者在凭据错误时显示 Hubtel payments are not available at the moment. Please choose another payment method. 详细信息会写入日志。

本模块不支持通过 PrestaShop 退款、不支持订阅、不保存银行卡，也不支持在商店内选择支付通道。

订单

订单状态

No order yet：顾客已被转到 Hubtel 但尚未付款，或 Hubtel 尚未确认付款。此时只存在购物车。

Payment accepted：付款已按 GHS 购物车总额的精确金额得到确认。付款会以 Hubtel 交易 ID 记录，备注中会显示金额、Hubtel 交易、付款方式和参考编号。

Hubtel payment on hold：Hubtel 报告的已付金额与购物车总额不符，或购物车不是 GHS 货币。订单未被标记为已付款；Hubtel 实际收取的金额会作为付款记录，并附有说明差异的备注。请在 Hubtel 后台核实该付款，然后处理订单或手动退款。如果同一购物车的另一次尝试之后以正确金额付款，订单将变为 Payment accepted。

如果已付款订单的另一次尝试也被付款，订单不会改变。备注会提醒您在 Hubtel 后台退还重复付款。对已取消或已退款订单的付款会添加备注，订单绝不会被自动重新开启。当 Hubtel 报告某笔付款已退款时，订单中会添加一条备注。

Hubtel 付款模块

订单页面会显示 Hubtel payment 模块，其中列出该订单购物车的所有付款尝试：日期、参考编号、Hubtel 结账、金额、Hubtel 状态、交易和结果。在这些尝试下方，会按从新到旧的顺序列出该订单的 Hubtel notes。

Check Hubtel payment status 按钮会检查该订单的最新尝试（最多 5 次，从新到旧，订单一旦付款即停止），应用检查结果，并添加一条备注，记录每次尝试的状态。结果会显示在该模块中。您需要拥有编辑订单的权限；无需访问 Modules 页面。该按钮在订单存在后可用。没有订单的已付款购物车，将通过回调、顾客返回或 cron 进行确认。

退款

不支持通过 PrestaShop 退款。请在 Hubtel 后台退还付款，然后在 PrestaShop 中记录退款。订单页面上标准的 PrestaShop 退款按钮不会通过 Hubtel 退还款项。

许可证密钥

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

没有有效的密钥时，Hubtel 不会在结账时向顾客显示。如果仍然发起付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此该付款方式对您也会隐藏：您可以在购买密钥前设置模块，但无法在结账时测试它。Modules > Module Manager 中的 Alerts 选项卡会显示提醒。现有订单不受影响：已发起的付款仍会通过后台付款检查得到确认。

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

故障排除

结账时看不到 Hubtel：请检查许可证是否有效、Enable/Disable 是否开启、API ID、API Key 和商户账号是否已填写，以及购物车货币是否为 GHS。在 Payment > Preferences 中，请确认模块已允许 GHS、顾客所在国家和顾客所属群组。如果凭据或货币有误，设置页面会显示警告。

付款已完成，但未创建订单：付款无法被确认。请开启 Debug log，并查看模块页面上的 Log 字段。状态检查返回 HTTP 401 或 403，表示 API 密钥有误，或服务器 IP 未被 Hubtel 加入白名单。另请检查回调 URL 能否从互联网访问，以及 cron URL 是否被调用。一旦 Hubtel 作出响应，下一次回调、后台检查或顾客返回就会创建订单。

回调返回 Unknown reference：该付款参考编号不属于本商店的任何付款。

回调返回 Payment status unavailable：Transaction Status API 无法访问或拒绝了请求，或者该购物车当时正被另一个请求确认。该付款将在 5 分钟后于后台重新检查。

回调返回 Gateway not configured：API ID、API Key 或商户账号缺失。请补全；付款将在后台重新检查。

回调返回 Invalid request 或 Invalid ClientReference：请求中不包含有效的 Hubtel 回调。

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

Cron URL 返回 Forbidden：URL 中的令牌有误。请完全按照设置中显示的内容复制 cron URL。

订单状态为 Hubtel payment on hold：请阅读 Hubtel payment 模块中的备注（参见"订单"部分的订单状态），在 Hubtel 后台核实付款，然后处理订单或手动退款。

顾客选择 Hubtel 时出现错误：请开启 Debug log 并查看日志。API 密钥有误会显示 Hubtel payments are not available at the moment. 连接问题会显示 Could not connect to Hubtel. 其他货币的购物车会显示 Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

面向开发者：钩子 actionWcpHubtelPayIcon 可修改付款方式图标，actionWcpHubtelPayPaymentDescription 可修改 Hubtel 页面上的付款描述（最多 100 个字符）。

卸载

进入 Modules > Module Manager，打开 VibeFox Hubtel Pay Gateway 旁边的菜单，然后选择 Uninstall。本模块的许可证密钥和许可证状态始终会被删除。若 Delete data on uninstall 已开启，则会删除该模块的设置和日志。若关闭，则所有设置都会保留，以便之后重新安装。为订单保存的 Hubtel 数据和 Hubtel payment on hold 订单状态始终保留。现有订单会保留其付款备注和交易 ID。

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