VibeFox Hubtel for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本，并已安装 cURL 扩展。

货币：仅支持加纳塞地（GHS）。当订单货币不是 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，用于后台付款检查（参见 Configuration）。

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

安装

下载文件是一个 zip 压缩包，内含两个 OpenCart 版本的安装包。请将其解压到您的电脑上。其中包含 README.txt、OpenCart 3 安装包 wcp_hubtel_pay-oc3-(version).ocmod.zip 和 OpenCart 4 安装包 wcp_hubtel_pay.ocmod.zip。请只安装与您的 OpenCart 版本对应的安装包。两个版本使用相同的许可证密钥。

OpenCart 3

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

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

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

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

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

6. 将 Payment confirmation 部分显示的 cron URL 添加到您服务器的 cron 中。

7. 开启 Enable/Disable，然后点击 Save。每次付款时都会将回调 URL 发送给 Hubtel，因此无需在 Hubtel 后台进行任何配置。

OpenCart 4

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

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

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

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

全新安装时，付款方式默认关闭。

配置

所有设置都在扩展页面中：Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，如果 API ID、API Key 或商户账号缺失，或者商店的默认货币不是 GHS，页面会发出提示。在这两种情况下，结账时都会隐藏 Hubtel。如果 GHS 货币使用了超过 2 位小数，页面也会提示（请在 System > Localisation > Currencies 中设置）。如果您没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 不能为空，且最多 128 个字符（Enter a title for the payment method (1 to 128 characters).）；Sort Order 必须是整数；Total 必须是大于或等于 0 的数字；地理区域和订单状态必须存在；否则不会保存任何内容。如果在没有凭据的情况下开启了付款方式，设置仍会保存，但会显示警告。

Hubtel

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

Title：顾客在结账时看到的付款方式名称。它也是订单中保存的付款方式名称。默认：Mobile Money or card (Hubtel)。必填。

Description：顾客在 Confirm Order 步骤中、确认按钮上方、Mobile Money 和银行卡图标旁边看到的文字。默认：Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Sort Order：Hubtel 在结账页面付款方式中的排列位置。留空或输入一个整数。

Geo Zone：仅为所选地理区域内的付款地址提供 Hubtel。默认：All zones。地理区域在 System > Localisation > Geo Zones 中设置。

Total：订单需要达到的结账金额（以商店默认货币计），达到后才会提供 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. 只有在需要更改时才输入新值。要删除已保存的密钥，请勾选字段下方的 Clear saved API Key，然后点击 Save。

商户账号 (POS Sales ID)：付款将汇入此 Hubtel 账户，并与之核对。

付款确认

Callback URL：回调会告知您的商店已完成付款。每次付款时都会将此 URL 发送给 Hubtel，因此无需在 Hubtel 后台进行任何配置。OpenCart 3 中其格式类似 https://your-store/index.php?route=extension/payment/wcp_hubtel_pay/callback，OpenCart 4 中则为 https://your-store/index.php?route=extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.callback，由您 OpenCart 安装的前台地址生成。该地址必须可以从互联网访问：不能有密码保护，也不能有阻止 Hubtel 的防火墙。即使商店处于维护模式，回调仍然有效：OpenCart 3 会放行支付扩展的请求，而在 OpenCart 4 中，扩展会添加一个启动动作（startup action），使回调、cron URL 以及顾客从 Hubtel 的返回都能通过。

Hubtel 的回调没有签名。扩展仅从回调中获取付款参考号；该参考号必须属于您商店的一笔付款。状态、金额和交易 ID 始终来自 Hubtel Transaction Status API。只有该 API 确认付款及其金额后，订单才会被标记为已付款。

后台付款检查（cron）：带有秘密令牌的 cron URL，在安装扩展时生成。请通过服务器的 cron 每 5 分钟调用一次，例如使用 curl。未确认的付款随后会自动在 Hubtel 处重新检查：顾客被转到 Hubtel 后 20 分钟检查一次，如果付款仍未完成，一小时后再检查一次；如果无法连接 Hubtel，则以逐渐增长的间隔最多检查 5 次。在 OpenCart 4 中，cron URL 的路由为 extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.cron，而不是 extension/payment/wcp_hubtel_pay/cron；请完整复制设置中显示的 URL。请妥善保管此 URL。该 URL 会返回一行简短内容，例如 OK checked=0。

订单

OpenCart 在 Confirm Order 步骤中创建订单，此时没有状态（缺失订单）。只有在 Hubtel 确认付款后，订单才会获得状态。下面的每个字段都列出您的 OpenCart 订单状态。

Order status after payment：Hubtel 确认了以 GHS 计的订单精确金额的付款后设置的状态。默认：处理中。

Hubtel payment on hold status：当 Hubtel 报告的已付金额与订单总额不符，或订单不是以 GHS 计价时设置的状态。订单历史中的备注会对此加以说明。默认：待处理，因为 OpenCart 没有 On hold 状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

高级

Debug log：将 API 调用和回调记录到 OpenCart 日志文件夹（storage/logs）中的 hubtel_p_debug.log.php。该文件无法通过网页打开；达到 5 MB 时会被移动到 hubtel_p_debug.old.log.php。密钥和顾客数据不会被记录。即使此选项关闭，错误和警告也始终会被记录。默认：关闭。

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

Delete data on uninstall：开启时，卸载扩展会删除该扩展的设置和日志。为订单保存的 Hubtel 付款尝试记录始终会保留。默认：关闭。

导入 / 导出

Export：Download JSON 将设置保存为 JSON 文件。API Key 不会被导出。

Import：粘贴之前导出的 JSON，然后点击 Import 恢复设置。已保存的 API Key 会被保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Mobile Money or card (Hubtel)）。在 Confirm Order 步骤中，顾客会看到图标和您的描述。OpenCart 在此步骤创建订单，此时仍没有状态。顾客点击 Confirm Order 后，扩展会为以 GHS 计的订单总额创建 Hubtel 结账，并将顾客转到 Hubtel 付款页面。付款在该页面上显示为 Order #、订单号以及您的商店名称。在 Hubtel 页面上，顾客可以使用 MTN MoMo、Telecel Cash、AirtelTigo Money、Visa 或 Mastercard 银行卡，或 GhQR 付款。每次点击 Confirm Order 都会创建一次新的付款尝试，并带有自己的参考号，较早的 Hubtel 页面仍可付款。

在 OpenCart 4 中，顾客通过付款方式区块中的 Choose 按钮，在 Payment method options 窗口中选择付款方式，然后点击结账页面底部的 Confirm Order。

付款后，顾客会返回您的商店。只有在 Hubtel 通过 Transaction Status API 确认后，订单才会被标记为已付款：可通过回调确认、顾客返回时的检查确认、后台检查确认，或通过订单页面的按钮确认。回调和顾客返回同时到达时会依次处理，因此付款永远不会被应用两次。随后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的订单成功页面。如果订单被挂起，页面会显示 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 页面进行的付款仍会被接受。

在 OpenCart 4 上，关于已取消或失败付款的消息会显示在结账页面上方。OpenCart 3 会在每次显示 Confirm Order 步骤时创建一个新订单；OpenCart 4 则会更新结账中的订单，因此在取消或付款失败后，顾客会以新的付款尝试支付同一订单。在新的尝试之前，扩展会向 Hubtel 查询此订单以及同一购物车较早订单（过去 24 小时内）中未确认的付款尝试。如果其中某次付款已完成，则应用该付款，顾客会进入成功页面，而不会重复付款。购物车发生变化（包括数量变化）会被视为需要单独付款的新购物车。

OpenCart 4 会在显示成功页面之前，将订单保留在结账流程中。如果该订单在此期间未付款即已关闭（例如您取消了它），顾客会返回结账页面，并显示 The Hubtel payment was not completed. You can try again or choose another payment method.，下一次 Confirm Order 会支付一个新订单。如果订单已付款，而购物车现在包含新的购买，Confirm Order 会重新加载结账页面，下一次 Confirm Order 会支付一个新订单。已付款的订单绝不会对不同的购物车显示为已付款。

如果 Hubtel 无法发起付款，顾客会停留在 Confirm Order 步骤，并在按钮上方看到简短提示，例如 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. 详细信息会写入日志。

该扩展不支持从 OpenCart 退款，不支持订阅、保存的银行卡，也不支持在商店内选择付款渠道。

订单

订单状态

无状态（缺失订单）：顾客已被转到 Hubtel 但尚未付款，或者 Hubtel 尚未确认付款。在 Sales > Orders 中，此类订单只有在 Order Status 筛选器设为 Missing Orders 时才会显示。

Order status after payment（默认 Processing）：付款已按订单的精确 GHS 金额确认。备注会显示金额、Hubtel 交易、付款方式和参考号。

Hubtel payment on hold status（默认 Pending）：Hubtel 报告的已付金额与订单总额不符，或订单不是以 GHS 计价。订单未被标记为已付款，备注中会说明金额不符的原因。请在 Hubtel 后台核实付款，然后处理订单或手动退款。如果之后同一订单的另一次尝试以正确金额付款，订单将转为 Order status after payment。

如果已付款订单的另一次尝试也被支付，或者已付款购物车中的另一份订单被支付，已付款订单不会被更改。备注会提示您在 Hubtel 后台退还重复的付款。对于您已转为其他状态（例如已取消）的订单，如果收到付款，会添加备注，订单永远不会被自动重新打开。当 Hubtel 报告某笔付款已退款时，订单会添加备注。

备注是订单 History 中的记录，顾客看不到。

VibeFox Hubtel Pay Gateway 标签页

在 Sales > Orders 中打开一个使用 Hubtel 付款的订单。在订单页面底部，紧邻 History 和 Additional 的位置，VibeFox Hubtel Pay Gateway 标签页会列出该订单的 Hubtel payment attempts：日期、参考号和 Hubtel 结账页面、金额、Hubtel 状态、交易和结果。在尝试记录下方，会按从新到旧的顺序列出订单的 Hubtel notes。该标签页对有权访问扩展的用户显示。

Check Hubtel payment status 按钮会检查订单的最新尝试（最多 5 次，从新到旧，订单一旦付款即停止），应用结果，并为每次尝试的状态添加备注。结果会显示在标签页中。您需要具有修改订单的权限（Sales > Orders，在 System > Users > User Groups 中设置）。该按钮对无状态的订单同样有效。通过此按钮设置的状态会被直接写入，不会发送订单邮件，也不会更新库存；回调、顾客返回和 cron 则以标准方式设置状态。

退款

不支持从 OpenCart 退款。请在 Hubtel 后台退还付款，然后在 OpenCart 中记录退款。Sales > Returns 中的商品退货不会通过 Hubtel 退还款项。

许可证密钥

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

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

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

没有有效密钥时，结账时不会向顾客显示 Hubtel。如果仍然发起了付款，顾客会看到 This payment method is not available. Please choose another one. 在同一浏览器中登录后台的管理员用户仍会在商店中看到该付款方式，并标有 (unlicensed — visible to admins only)，因此您可以在购买密钥之前设置和测试扩展。在 OpenCart 4 上此预览不可用：商店无法看到后台的登录状态，因此在没有有效密钥的情况下，所有人都看不到该付款方式。打开一次 Edit 页面后，后台的 Dashboard 会出现一条提醒。点击 × 可将其关闭，关闭后 7 天内不再显示。现有订单不受影响：已发起的付款仍会被确认，包括通过后台检查确认。

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

故障排除

Hubtel 没有出现在结账页面：请检查许可证是否有效，Enable/Disable 是否已开启，API ID、API Key 和商户账号是否已填写，以及订单货币是否为 GHS。另请检查付款地址是否位于所选的 Geo Zone 中，以及订单是否达到设置中的 Total。如果凭据或货币有误，设置页面会显示警告。

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

回调返回 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。在开启 Delete data on uninstall 的情况下重新安装后，令牌会更换。

订单处于挂起状态：请阅读 VibeFox Hubtel Pay Gateway 标签页中的备注（参见订单状态），在 Hubtel 后台核实付款，然后处理订单或手动退款。

顾客在 Confirm Order 之后看到错误：请开启 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. This payment method is not available. Please reload the checkout page. 表示结账页面已与订单不匹配，或付款方式在此期间已被关闭。

面向开发者：OpenCart 事件 wcp_hubtel_pay_icon 用于更改付款方式图标，wcp_hubtel_pay_payment_description 用于更改 Hubtel 页面上的付款描述。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Hubtel Pay Gateway 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态总会被删除。OpenCart 总会删除扩展自身的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分中的订单状态，这些设置在重新安装后会恢复为默认值。扩展的 OpenCart 事件也会被删除（在 OpenCart 4 上，还包括其事件和启动动作，该动作使回调、cron URL 和顾客的返回在维护模式下仍可通过）。如果开启了 Delete data on uninstall，其余设置（标题、描述、API 凭据、cron 令牌、调试日志开关）和日志都会被删除；如果关闭，则会保留，以便日后重新安装时使用。订单的 Hubtel 付款尝试记录始终会保留，因此延迟的回调和检查在重新安装后仍可正常工作。现有订单会保留其付款备注。

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

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