VibeFox Hubtel for WooCommerce — 帮助

系统要求

WordPress：6.2 或更高版本。

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

PHP：8.0 或更高版本。

货币：仅支持加纳塞地（GHS）。对于其他货币，该付款方式在结账时会被隐藏。请将 WooCommerce 小数位数保持为 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 没有公开的沙盒环境。所有付款均为真实交易。

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

安装

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

2. 点击 Activate。

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

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

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

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

7. 开启 Enable/Disable。回调 URL 会随每笔付款发送给 Hubtel，因此无需在 Hubtel 控制面板中进行额外配置。

配置

所有设置均位于同一页面：WooCommerce > Settings > Payments > Hubtel。当 API ID、API Key 或商户账号缺失，或者店铺货币不是 GHS 时，页面会在字段上方显示警告。在这两种情况下，Hubtel 在结账时均会被隐藏。如果店铺使用超过 2 位小数，页面也会发出警告。在付款方式列表中，网关会一直被标记为需要设置，直到凭据填写完整。

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

Title: 顾客在结账时看到的付款方式名称。默认：Mobile Money or card (Hubtel)。

Description: 结账时付款方式下方显示的文字。默认：Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

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。请妥善保管，切勿泄露。

Merchant account number (POS Sales ID): 款项将结算至该 Hubtel 账户并以此进行核对。

付款确认

回调用于告知您的店铺付款已完成。本节显示的回调 URL 会随每笔付款发送给 Hubtel，因此无需在 Hubtel 控制面板中配置。其格式形如 https://your-site/wc-api/hubtel_pay/。它必须能够从互联网公开访问：不能处于维护模式、不能有密码保护或阻止 Hubtel 访问的防火墙。

Hubtel 回调未签名。插件仅从回调中获取付款参考编号；该编号必须属于您店铺的某个订单。状态、金额和交易 ID 始终来自 Hubtel Transaction Status API。只有在 API 确认付款及其金额后，订单才会被标记为已付款。如果无法连接 Hubtel，系统会在后台自动复核付款，您也可以在订单页面通过 Order actions > Check Hubtel payment status 手动检查。

高级

Debug log: 将 Log API calls and callbacks 记录到 WooCommerce > Status > Logs，源为 wcp_hubtel_pay，日志中不包含密钥或顾客数据。错误日志始终记录。默认：关闭。

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept)。默认：关闭。

结账

顾客选择该付款方式（默认为 Mobile Money or card (Hubtel)）并提交订单。插件将按订单的 GHS 总额创建 Hubtel 结账会话，并将顾客引导至 Hubtel 付款页面。该笔付款在页面上显示为 Order #、订单编号及您的站点名称。在 Hubtel 页面上，顾客可以使用 MTN MoMo、Telecel Cash、AirtelTigo Money、Visa 或 Mastercard 卡或 GhQR 进行付款。每次点击 Place order 或 Pay 都会创建一次具有独立参考编号的全新付款尝试，且同一订单先前生成的 Hubtel 页面仍可支付。

付款完成后，顾客将返回至订单已收到页面。订单只有在 Hubtel 通过 Transaction Status API 确认后才会被标记为已付款：可通过回调、顾客返回时的即时检查、后台定时检查或订单操作进行确认。同时到达的回调与顾客返回会依次处理，确保订单绝不会被重复完成。如果 Hubtel 尚未确认付款，页面将显示：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. 如果订单被置为保留状态，页面将显示：Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

如果顾客在 Hubtel 页面上点击 Cancel，插件会首先检查顾客是否实际上已完成付款。若未付款，顾客将返回到 Pay for order 页面，并看到提示消息：The Hubtel payment was cancelled. You can try again or choose another payment method.

如果 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. 详细信息将记录在日志中。

该付款方式适用于经典结账、结账区块以及 Pay for order 页面。与 WooCommerce 高性能订单存储（HPOS）完全兼容。

本插件不支持通过 WooCommerce 进行退款、不支持订阅、不支持保存银行卡，也不支持在 WooCommerce 内部选择支付通道。

订单

订单状态

Pending payment: 顾客已被引导至 Hubtel 且尚未付款，或者 Hubtel 尚未确认该笔付款。

Processing: 付款已确认。仅包含虚拟可下载商品的订单将转为 WooCommerce 默认的已完成状态。订单备注中会显示金额、Hubtel 交易号、付款方式以及参考编号。交易 ID 即为 Hubtel 交易 ID。

On hold: Hubtel 报告的已付金额与订单总额不符，或者订单货币不是 GHS（备注为 Hubtel amount/currency mismatch）；亦或是已取消的订单收到了付款。订单不会被标记为已付款。请在 Hubtel 控制面板中核查付款，并手动完成该订单或为其退款。

Failed: Hubtel 报告等待付款订单的最近一次付款尝试失败，且 Transaction Status API 确认其未付款。顾客可以在订单中重新尝试付款。仅由回调报告的失败绝不会直接导致订单失败。

如果已付款订单的另一次付款尝试也完成了付款，订单状态不会更改。备注会提示您在 Hubtel 控制面板中为重复付款进行退款。已取消或已退款的订单绝不会自动重新开启。当 Hubtel 报告某笔付款已退款时，订单中会添加相应备注。

付款检查

在顾客被引导至 Hubtel 约 20 分钟后，后台定时任务（WooCommerce Action Scheduler）会向 Hubtel 查询付款状态，以防回调丢失且顾客未返回店铺。未付款的尝试会在 1 小时后再次复查。当无法连接 Hubtel API 时，系统会以递增的时间间隔重试最多 5 次。

订单操作 Check Hubtel payment status 会检查订单的最近尝试记录（最多 5 次，从最新记录开始），应用查询结果并添加包含每次尝试状态的备注。

退款

不支持从 WooCommerce 直接发起退款。请在 Hubtel 控制面板中为付款退款，然后在 WooCommerce 中手动录入退款记录。

许可证密钥

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

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

未绑定有效密钥时，Hubtel 在结账时不会向顾客展示。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍可看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，以便在购买密钥前配置和测试插件。在插件页面和 WooCommerce 相关页面上会显示提示。现有订单不受影响：已发起的付款仍会正常确认。

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

故障排除

Hubtel 未在结账页面显示：请检查许可证是否有效、Enable/Disable 是否开启、API ID、API Key 和商户账号是否已填写，以及货币是否为 GHS。在 Pay for order 页面以订单本身的货币为准。若凭据或货币不正确，设置页面会显示警告。

付款已成功，但订单仍保持等待付款状态：付款未能确认。请打开 WooCommerce > Status > Logs，源为 wcp_hubtel_pay。状态检查返回 HTTP 401 或 403 表示 API 密钥错误，或服务器 IP 未被 Hubtel 加入白名单。此外还要检查回调 URL 是否可从外网访问。修复问题后，打开订单并执行 Order actions > Check Hubtel payment status。一旦 Hubtel 正常响应，后台检查也会自动确认订单。

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

回调返回 Payment status unavailable：无法连接 Transaction Status API 或请求被拒绝。系统将在后台重新检查付款状态。

订单处于保留状态并带有金额或货币不匹配备注：Hubtel 报告的已付金额与订单总额不符，或订单货币不是 GHS。请在 Hubtel 控制面板中核查付款，并手动完成订单或退款。

顾客在下单时看到错误：开启 Debug log 并查看日志。API 密钥错误会显示 Hubtel payments are not available at the moment. 连接问题会显示 Could not connect to Hubtel.

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

面向开发者：hubtel_p_icon 过滤器可修改付款方式图标，hubtel_p_payment_description 过滤器可修改 Hubtel 页面上的付款描述（最多 100 个字符）。

卸载

停用插件会保留所有数据；仅未完成的后台付款检查会被取消。若要彻底移除，请在 Plugins 页面先停用然后再删除。本插件的许可证密钥和许可证状态始终会被删除。仅当开启了 Delete data on uninstall 时，网关设置、插件自身选项、待处理的后台检查和日志才会被删除。否则它们将保留以供日后重新安装。订单上存储的 Hubtel 数据属于付款记录，始终予以保留。现有订单将保留其付款备注和交易 ID。

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