VibeFox Flutterwave for OpenCart — 帮助

系统要求

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

PHP：8.0 或更高版本。

Flutterwave 账户：您需要 Flutterwave 账户的密钥，它们位于 Flutterwave 面板的 Settings、API keys 下：测试模式使用 FLWSECK_TEST-…，正式模式使用 FLWSECK-…。仅使用密钥（Secret Key）。公钥和加密密钥无需填写。您还需要使用自选的密钥哈希（secret hash）设置一个 Webhook（参见设置）。

货币：订单始终以订单货币收取费用。扩展本身不限制国家或货币；如果您的账户不支持该货币，Flutterwave 会显示错误。您可以用 Geo Zone 和 Total 限制在何处提供 Flutterwave。

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

安装

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

OpenCart 3

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

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

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

4. 输入您的密钥，在 Flutterwave 面板中设置 Webhook，并在扩展中输入相同的密钥哈希（参见设置）。

5. 开启 Enable/Disable，然后点击 Save。在测试模式下测试一笔付款，然后开启 Live mode。

OpenCart 4

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

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

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

4. 按照 OpenCart 3 的步骤 3 至 5 输入许可证密钥、密钥和 Webhook。设置页面及其字段在两个版本中相同。仅 Webhook URL 不同（参见 Webhook）。

新安装时，付款方式默认关闭，并处于测试模式。

设置

所有设置都位于扩展页面：Extensions > Extensions > Payments > VibeFox Flutterwave Payment > Edit。各部分列在左侧；列表下方的 Save 按钮会保存整个页面。在设置上方，页面会显示 Live mode: real payments are accepted. 或 Test mode: no real money is charged. 当当前模式的密钥为空、正式模式下正式密钥栏中填入了测试密钥（FLWSECK_TEST-…）、或测试模式下测试密钥栏中填入了正式密钥（FLWSECK-…）时，它会发出警告；在问题解决之前，结账页面会隐藏该付款方式。当未设置 Webhook 密钥哈希时，页面也会发出警告：此时 Webhook 会被拒绝，付款只会在顾客返回您的店铺时确认。如果没有修改扩展的权限，页面可以显示设置，但无法保存。

保存时，Title 必须为 1 至 128 个字符，Sort Order 必须为空或整数，Total 必须为空或不小于 0 的数字，并且所选的地理区域和订单状态必须存在。否则不会保存任何内容，页面会显示需要更正的内容。密钥方面的问题不会阻止保存。

Flutterwave

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

Title：顾客在结账时看到的付款方式标题。订单中保存的付款方式名称也是它。默认：Flutterwave。必填，最多 128 个字符。

Description：在 Confirm Order 步骤中、确认按钮上方显示的付款方式说明。默认：Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

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

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

Total：订单必须达到的金额（以店铺默认货币计）才会提供 Flutterwave。留空则在任何金额下都提供 Flutterwave。

API 密钥

从 Flutterwave 面板的 Settings、API keys 下复制密钥（该部分有一个链接）。测试模式与正式模式使用不同的密钥。

Live mode：接受真实付款。若要使用测试模式，请关闭。测试模式使用测试密钥，不会扣除真实款项。正式模式使用正式密钥。默认：关闭（测试模式）。测试模式开启期间，顾客在 Confirm Order 步骤会看到 TEST MODE - no real payments will be processed.

Test Secret Key：您的 Flutterwave 测试密钥（FLWSECK_TEST-...）。

Live Secret Key：您的 Flutterwave 正式密钥（FLWSECK-...）。

已保存的密钥和密钥哈希不会再次显示。该字段将保持为空，并显示 Saved — leave empty to keep it. 只有在需要更改时才输入新值。要删除已保存的值，请勾选字段下方的 Clear the saved value，然后点击 Save。

Webhook

即使顾客没有返回您的店铺，Webhook 也会确认付款。请在 Flutterwave 面板的 Settings、Webhooks 中，分别在测试模式和正式模式下，填入本部分 Webhook URL 所显示的 URL 以及您自选的密钥哈希。在 OpenCart 3 中，该 URL 类似于 https://your-store/index.php?route=extension/payment/wcp_flutterwave_payment/webhook；在 OpenCart 4 中类似于 https://your-store/index.php?route=extension/wcp_flutterwave_payment/payment/wcp_flutterwave_payment.webhook，根据您店铺的地址生成。它必须能通过 HTTPS 从互联网访问。请完全按照设置中显示的内容复制该 URL。扩展会对以下事件作出响应：

其他事件将被忽略。

Secret Hash：Webhook 的密钥哈希。它必须与您 Flutterwave 面板中 Webhook 设置里的值一致。Flutterwave 会随每个 Webhook 发送该值，测试模式和正式模式使用同一个值。没有有效密钥哈希的 Webhook 会被拒绝。没有 Webhook 时，付款只会在顾客返回您的店铺后才会被确认。

付款

Payment Options：要在 Flutterwave 页面上显示的付款方式，以逗号分隔，例如 card、banktransfer、ussd、mobilemoney。留空则显示您账户中启用的所有方式。保存时会整理该列表（小写，去除重复项）。

Autocomplete Orders：已付款订单将获得 Complete Order Status，而不是 Paid Order Status。默认：关闭。

订单

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

Paid Order Status：确认付款后的订单状态。默认：处理中。

Complete Order Status：启用 Autocomplete Orders 时，确认付款后的订单状态。默认：已完成。

Awaiting Payment Status：顾客在付款仍在 Flutterwave 处于待处理状态时返回（银行转账、USSD、移动支付）。订单会保持此状态，直到 Webhook 确认付款。默认：待处理。

On Hold (Review) Status：金额或货币与订单不符的付款，或在订单被取消后到达的付款，会获得此状态以及一条说明原因的备注。默认：待处理，因为 OpenCart 没有「On hold」状态。您可以在 System > Localisation > Order Statuses 中创建自己的状态，并在此处选择。

Failed Status：等待中订单的待处理付款在 Flutterwave 失败。默认：失败。

Refunded Status：在订单页面将付款全额退款后设置。默认：已退款。

高级

Debug log：将 Flutterwave API 事件记录到 OpenCart 日志文件夹（storage/logs）中的 flwv_debug.log.php，用于调试。该文件无法通过网页打开，达到 5 MB 时会被移动到 flwv_debug.old.log.php。错误和警告始终会被记录。密钥、密钥哈希和顾客数据绝不会被记录。默认：关闭。

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

Delete data on uninstall：卸载扩展时，删除其设置和日志。订单中保存的付款数据始终保留。默认：关闭。

导入 / 导出

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

Import：粘贴先前导出的 JSON，然后点击 Import 恢复设置。已保存的密钥和密钥哈希会保留。

结账

在 Payment Method 步骤中，顾客选择付款方式（默认为 Flutterwave）。在 Confirm Order 步骤中，顾客会看到您的说明以及提示 You will be redirected to the Flutterwave checkout page. OpenCart 在此步骤创建订单，仍然不带状态。在 OpenCart 4 中，顾客通过付款方式区块的 Choose 按钮，在 Payment method options 窗口中选择付款方式，并点击结账页面底部的 Confirm Order。顾客点击 Confirm Order 后，扩展会以订单货币为订单总额创建一笔 Flutterwave 付款，其中包含顾客的电子邮件、付款地址中的电话和姓名、您的店铺名称和 Logo，以及带有订单号的 Payment for order，然后将顾客引导至 Flutterwave 结账页面。必须提供有效的电子邮件地址。顾客在该页面使用您账户中已启用的付款方式之一（或 Payment Options 中列出的方式）付款。

付款后，顾客返回您的店铺。只有在 Flutterwave 确认之后，订单才会被标记为已付款：通过 Webhook，或在顾客返回时进行服务器端检查。之后，订单会以 OpenCart 的标准方式获得状态，并发送常规订单邮件、更新库存，顾客会看到 OpenCart 的下单成功页面。如果付款仍处于待处理状态，例如银行转账、USSD 或移动支付，订单会获得 Awaiting Payment Status，页面还会显示 Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Flutterwave 确认付款后，订单会转为已付款状态，并通过电子邮件通知顾客。如果订单因例如已付金额与订单不符而被挂起以待审核，页面会显示 Your payment was received and your order is being reviewed. We will contact you if anything is needed. 如果待处理的付款之后失败，而顾客返回该订单，页面会显示 Your Flutterwave payment was not completed. Please contact us about this order.

如果顾客返回时无法连接 Flutterwave，Payment confirmation 页面会显示 Your payment is being confirmed by Flutterwave. Your order will be confirmed as soon as Flutterwave confirms it — please do not pay again.，并提供 Check again 和 Back to checkout 按钮。Webhook 一到达就会设置订单状态。

如果付款被拒绝，顾客会返回结账页面，并看到 Your payment was declined. You can try again or choose another payment method. 如果顾客在 Flutterwave 页面取消，提示为 Payment was cancelled. You can try again or choose another payment method. 如果付款未完成，提示为 The payment was not completed. You can try again or choose another payment method. 如果付款无法验证，提示为 Payment verification failed. Please contact support. 订单保持无状态，购物车会保留，顾客可以再次付款。在 OpenCart 4 中，这些提示会显示在结账页面上方。

在 OpenCart 3 中，每次显示 Confirm Order 步骤时都会创建一个新订单；OpenCart 4 则会更新结账中的订单，因此新的尝试会为同一订单付款。每次尝试都会获得自己的参考号。在发起新付款之前，会向 Flutterwave 检查该订单以及同一购物车在最近 24 小时内其他订单的未完成和待处理付款。如果其中某笔付款已完成，它会确认对应的订单，顾客会进入成功页面，而不是再次付款。如果同一购物车的另一个订单已通过 Flutterwave 付款，也不会发起新付款。较早的付款链接即使稍后才付款，仍会被接受。如果同一购物车被重复付款（例如在两个浏览器标签页中），则只有第一笔付款会为其订单设置状态：另一个订单保持无状态，已付款的订单会收到一条备注，提醒您在 Flutterwave 面板中退还第二笔付款。

OpenCart 4 会在显示成功页面之前，将订单保留在结账中。如果该订单在此期间未付款即被关闭（例如其待处理付款失败，或您取消了它），顾客会被带回结账页面，并显示关于付款被拒绝的提示，下一次点击 Confirm Order 时会为购物车支付一个新订单。如果您是在订单付款后将其关闭，提示为 This order can no longer be paid (it was closed by the store). Please confirm your order again. 如果该订单已付款，但之后购物车发生了变化（包括数量变化），提示为 Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. 已付款的订单绝不会被显示为其他购物车的已付款订单。

如果 Flutterwave 无法发起付款，顾客会停留在 Confirm Order 步骤，并看到一条简短提示，例如 Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. 技术原因会写入日志。

即使店铺处于维护模式，Webhook 和返回 URL 仍然有效，因为 OpenCart 3 会放行付款扩展的请求，并且扩展在 OpenCart 4 中会为其添加一个启动动作。

该扩展仅支持一次性付款。您的网站上没有嵌入式或弹窗式结账，也不支持保存银行卡、订阅、拆分付款或付款计划。托管的付款链接无法通过 Flutterwave API 取消，因此旧链接仍可能被支付。

订单与退款

订单状态

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

Paid Order Status（默认 处理中）或 Complete Order Status（默认 已完成）：付款已确认。启用 Autocomplete Orders 时使用 Complete Order Status。备注会显示金额、付款方式、Flutterwave 参考号、交易和模式。

Awaiting Payment Status（默认 待处理）：顾客在付款仍在 Flutterwave 待处理时返回。Flutterwave 确认付款后，订单会转为已付款状态。

On Hold (Review) Status（默认 待处理）：经核实的金额或货币与订单不符，或者付款是在订单被设置为无付款的状态（例如已取消）之后到达的。实际付款的金额和货币会被记录，备注会说明这一点。请处理订单或退还付款。如果订单已有其他处理状态，则仅添加备注。

Failed Status（默认 失败）：Flutterwave 报告等待中订单的最近一次付款尝试失败或已取消。备注会显示原因。较早的尝试和已付款的订单不会被更改。

Refunded Status（默认 已退款）：付款已通过该扩展全额退款。

如果已付款的订单又收到第二笔付款，订单不会被更改。备注会请您在 Flutterwave 面板中退还重复付款。

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

VibeFox Flutterwave Payment 选项卡

在 Sales > Orders 中打开一笔使用 Flutterwave 付款的订单。在订单页面底部，History 和 Additional 旁边的 VibeFox Flutterwave Payment 选项卡会显示 Transaction reference、Mode（Test 或 Live）、付款的 Status、Transaction ID、Flutterwave reference、Payment type、Paid / refunded 金额、退款表单、退款历史以及订单的 Flutterwave notes。该选项卡对有权访问该扩展的用户可见。

退款

在该选项卡中输入 Amount（会自动填入尚未退款的金额），可选填写 Reason (optional)，然后点击 Refund via Flutterwave。确认提问 Refund this amount through Flutterwave? This cannot be undone. 支持全额和部分退款。您需要修改该扩展的权限（在 System > Users > User Groups 中设置）。退款以 Flutterwave 实际扣款的金额和货币进行，因此在金额或货币不符的情况下，您最多只能退还顾客实付的金额，而不是订单总额。退款使用付款所在模式（测试或正式）的密钥发送，因此该密钥必须已设置。如果 Flutterwave 拒绝退款，该选项卡会显示错误，且不会记录任何退款。成功的退款会添加到退款历史和备注中，并附上退款 ID 和状态（已完成，或根据 Flutterwave 报告的状态已发起）。全额退款会将订单设为 Refunded Status，且不会通知顾客，也不会将商品退回库存，与手动更改状态相同。部分退款不会更改状态。Flutterwave 确认付款后即可进行退款。

Sales > Returns 中的商品退货不会通过 Flutterwave 退还款项。在 Flutterwave 面板中进行的退款不会同步回 OpenCart。如有需要，请手动更新订单状态。

许可证密钥

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

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

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

故障排除

结账时不显示 Flutterwave：请检查许可证是否有效、Enable / Disable 是否已开启、当前模式的密钥是否已填写且与模式相符（测试模式使用测试密钥 FLWSECK_TEST-…，正式模式使用正式密钥 FLWSECK-…）。否则设置页面会显示警告。另外还要检查付款地址是否位于所选的 Geo Zone 内，以及订单金额是否达到设置中的 Total。

付款已完成，但订单仍无状态：Webhook 无法正常工作。请在 Flutterwave 面板中检查 Webhook URL 是否与 Webhook URL 中显示的完全一致、是否与您所用的模式（测试或正式）一致，并且其密钥哈希与扩展中的 Secret Hash 相同。待处理的银行转账、USSD 和移动支付会一直保持待处理，直到 Flutterwave 确认它们。顾客付款后返回店铺时，订单也会获得状态。请开启 Debug log，并查看扩展页面上的 Log 字段。

Webhook 返回 Invalid hash 或 Secret hash not configured：Flutterwave 面板中的密钥哈希与扩展中的不同，或扩展中没有设置。请在两处输入相同的值。

Webhook 返回 Verification failed、Busy, retry later 或 Order could not be updated, retry later：无法连接 Flutterwave 以验证付款，交易尚不可见，订单正被另一个请求处理，或无法设置其状态。Flutterwave 会重试 Webhook。日志会显示原因。

Webhook URL 在浏览器中显示 Empty body：这是正常现象。该 URL 只接受来自 Flutterwave 的 Webhook。

顾客看到 Payment gateway is not properly configured：当前模式的密钥缺失，或属于另一种模式。

顾客看到 This payment method is not available：结账会话已与订单不再匹配，或付款方式在此期间已被关闭。顾客需要重新加载结账页面。

顾客看到 We could not match this payment to an order：返回链接不属于本订单的付款。如果顾客已被扣款，请在 Flutterwave 面板中查找该笔付款。

Flutterwave 页面上显示错误，或顾客看到 Flutterwave could not start the payment：您的 Flutterwave 账户可能不支持订单货币或所选的付款选项。

付款后订单处于挂起状态：请阅读 VibeFox Flutterwave Payment 选项卡中的备注（参见订单状态），然后处理订单或退还付款。

选项卡中没有退款表单：该选项卡会说明原因：付款尚未确认、已全额退款、您的用户组没有修改该扩展的权限，或付款模式的密钥未设置。

退款失败，并显示与模式相关的信息：付款是在测试或正式模式下完成的，而该模式的密钥未设置。请输入密钥后重试。

退款返回 Another operation on this payment is running：同一订单的另一笔退款正在发送。请稍候，检查退款历史，必要时再重试。

对于开发人员，该扩展会触发 OpenCart 事件 flwv_payment_request（发送给 Flutterwave 的数据）和 flwv_currency_decimals（货币精度）。

卸载

进入 Extensions > Extensions，选择类型 Payments，然后点击 VibeFox Flutterwave Payment 旁边的 Uninstall（红色 − 按钮）。该扩展的许可证密钥和许可证状态始终会被移除。OpenCart 始终会移除扩展自己的设置：Enable/Disable、Sort Order、Geo Zone、Total，以及 Orders 部分的订单状态，这些设置在重新安装时会恢复为默认值。该扩展的 OpenCart 事件也会被移除（在 OpenCart 4 中，还会移除其事件以及在维护模式下放行 Webhook 和返回 URL 的启动动作）。如果 Delete data on uninstall 已开启，其他设置（标题、说明、模式、密钥、密钥哈希、付款选项、自动完成、调试日志开关）和日志都会被删除。如果关闭，这些内容会保留，以便日后重新安装时使用。Flutterwave 的付款和退款记录始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注。

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

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