VibeFox Flutterwave for WooCommerce — 帮助

系统要求

WordPress: 5.8 或更高版本。

WooCommerce: 7.0 或更高版本，且已安装并启用。没有 WooCommerce 时，本插件将拒绝启用。

PHP: 8.0 或更高版本。使用较旧的 PHP 时，本插件将拒绝启用。

Flutterwave 账户：需要您 Flutterwave 账户的秘密密钥，可在 Flutterwave 控制面板的 Settings、API keys 中获取：测试模式使用 FLWSECK_TEST-…，正式模式使用 FLWSECK-…。仅使用秘密密钥，不需要公钥和加密密钥。您还需要设置 Webhook，并自行指定秘密哈希值（参见“配置”）。

币种：订单始终按订单币种扣款。本插件不限制国家或币种；如果您的账户不支持该币种，Flutterwave 会显示错误。

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

安装

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

2. 点击 Activate。

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

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

5. 输入秘密密钥，在 Flutterwave 控制面板设置 Webhook，并在插件中输入相同的秘密哈希值（参见“配置”）。

6. 启用 Enable/Disable，在测试模式下测试付款，然后勾选 Live mode。

配置

所有设置均在同一页面：WooCommerce > Settings > Payments > Flutterwave。字段上方会显示 Live mode: real payments are accepted. 或 Test mode: no real money is charged. 当前模式的秘密密钥为空、正式模式下的正式密钥字段包含测试密钥（FLWSECK_TEST-…），或测试模式下的测试密钥字段包含正式密钥（FLWSECK-…）时，页面会发出警告；付款方式将在结账时隐藏，直到问题修正。未设置 Webhook 秘密哈希值时也会警告：此时 Webhook 会被拒绝，只有顾客返回店铺时才能确认付款。在当前模式配置秘密密钥之前，付款方式列表中的 Flutterwave 会标记为需要设置；测试模式下还会显示测试模式标记。

常规

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

Title: 顾客结账时看到的付款方式标题。默认值：Flutterwave。

Description: 顾客结账时看到的文字。默认值：Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API 密钥

从 Flutterwave 控制面板的 Settings、API keys 中复制秘密密钥。测试模式和正式模式使用不同的密钥。

Live mode: Accept real payments (uncheck for test mode)。测试模式使用测试秘密密钥，不会扣取真实资金。正式模式使用正式秘密密钥。默认值：off（测试模式）。

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

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

Webhook

即使顾客没有返回店铺，Webhook 也能确认付款。在 Flutterwave 控制面板的 Settings、Webhooks 中，分别为测试模式和正式模式输入本节显示的 Webhook URL，以及您自行选择的秘密哈希值。URL 的形式为 https://your-site/wc-api/flw_p_webhook/。插件响应以下事件：

其他事件会被忽略。

Secret Hash: Webhook 的秘密哈希值。它必须与 Flutterwave 控制面板的 Webhook 设置值一致。Flutterwave 会随每个 Webhook 发送该值。不包含有效秘密哈希值的 Webhook 会被拒绝。没有 Webhook 时，只有顾客返回店铺才会确认付款。

付款

Payment Options: 在 Flutterwave 页面显示的付款方式，以逗号分隔，例如 card, banktransfer, ussd, mobilemoney。留空则显示您账户中已启用的所有方式。保存时会清理列表。

Autocomplete Orders: Automatically mark orders as completed after successful payment。启用后，付款完成时订单将通过一次状态变更设为“已完成”，而非“处理中”。默认值：off。

高级

Debug log: Log Flutterwave API events for debugging，记录位置为 WooCommerce > Status > Logs，来源为 wcp_flutterwave_payment。错误始终会记录。密钥和顾客数据绝不会记录。默认值：off。

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted。停用插件绝不会删除任何内容。保存在订单中的付款数据始终保留。默认值：off。

结账

顾客选择付款方式（默认为 Flutterwave）并下单。测试模式下，结账页面会显示 TEST MODE - no real payments will be processed. 必须提供有效的账单电子邮箱。插件按订单币种为订单总额创建 Flutterwave 付款，附带顾客的邮箱、电话和姓名，以及您的网站名称和标志，然后将顾客转至 Flutterwave 结账页面。顾客在该页面使用您账户中已启用的方式（或 Payment Options 中列出的方式）付款。

付款后，顾客返回您的店铺。只有 Flutterwave 通过 Webhook，或在顾客返回时由服务器端检查确认付款后，订单才会标记为已付款。如果付款尚未确认，例如银行转账、USSD 或移动支付仍在等待中，订单已收到页面会显示 Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. 如果资金已到账，但插件将订单设为“保留”以供审核，例如实付金额与订单不符，页面会显示 Your payment was received and your order is being reviewed. We will contact you if anything is needed.

如果付款被拒绝，顾客将返回结账页面（或 Pay for order 页面），并看到 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.

顾客可以重新支付未付款的订单。每次尝试都有独立的参考编号，较早创建、后来才付款的链接仍会被接受。如果 Flutterwave 无法启动付款，顾客会看到简短提示，例如 Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

该付款方式适用于经典结账、结账区块和 Pay for order 页面。它兼容 WooCommerce High-Performance Order Storage（HPOS）。面向顾客的文字已翻译为法语。

本插件仅接受一次性付款。不支持在您的网站内嵌入结账表单或使用模态结账窗口，也不支持保存银行卡、订阅、拆分付款或付款计划。托管付款链接无法通过 Flutterwave API 取消，因此订单的旧链接仍可付款。

订单与退款

订单状态

Pending payment: 顾客已被转至 Flutterwave，尚未付款，或者付款在 Flutterwave 仍待处理。

Processing or Completed: 付款已确认。启用 Autocomplete Orders 时使用“已完成”（仅包含虚拟可下载商品的订单也会变为“已完成”，这是 WooCommerce 的默认行为）。订单备注会显示金额、付款方式、Flutterwave 参考编号、交易和模式。订单的交易 ID 是 Flutterwave 参考编号。

On hold after payment: 核实的金额或币种与订单不符，或在订单取消后才收到付款。备注会说明原因。请履行订单或退款。重复发送的 Webhook 绝不会重新打开已退款或已取消的订单。

Failed: Flutterwave 将待处理订单的最近一次付款尝试报告为失败或已取消。备注会显示原因。

Cancelled: 顾客在结账下单后于 Flutterwave 页面取消，或订单由您取消，或因 WooCommerce 库存保留超时而被取消。

如果已付款订单收到第二笔付款，订单不会更改。备注会要求您在 Flutterwave 控制面板退还重复付款。

退款

打开订单，点击 Refund，输入金额并点击 Refund via Flutterwave。支持全额和部分退款。退款使用付款时所处模式（测试或正式）的秘密密钥发送，因此必须设置该密钥。如果 Flutterwave 拒绝退款，WooCommerce 会显示错误且不会记录退款。成功的退款会添加到订单备注中，并附上退款 ID 和状态（已完成，或已发起并附上 Flutterwave 报告的状态）。

在 Flutterwave 控制面板中进行的退款不会同步回 WooCommerce。如有需要，请在 WooCommerce 中创建手动退款，不要使用 Refund via Flutterwave。

许可证密钥

插件使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区域位于 WooCommerce > Settings > Payments > Flutterwave 顶部。将密钥粘贴到 License key 并点击 Activate。该区域显示状态，例如许可证有效期截止日期和您的域名。使用 Check now 重新检查状态，使用 Change key 输入其他密钥，使用 Remove key 从此网站移除密钥。Manage licenses and domains in your account 链接会打开您的 vibefox.net 账户。

一个密钥可用于一个域名。从网站移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放名额。

没有有效密钥时，Flutterwave 不会在结账时向顾客显示。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. 已登录的店铺管理员仍可看到该付款方式，并带有 (unlicensed — visible to admins only) 标记，以便您在购买密钥前配置和测试插件。插件页面和 WooCommerce 页面会显示提醒。现有订单不受影响：已启动的付款仍会确认，退款功能也可使用。

许可证到期后，插件仍会继续运行，但更新和支持需要续订。状态会在后台自动重新检查。

故障排除

结账时未显示 Flutterwave：请检查许可证是否有效，Enable/Disable 是否开启，以及当前模式的秘密密钥是否已填写且与模式匹配：测试模式使用测试密钥（FLWSECK_TEST-…），正式模式使用正式密钥（FLWSECK-…）。否则设置页面会显示警告。

付款已成功，但订单仍为 Pending payment：Webhook 未正常工作。在 Flutterwave 控制面板中，检查所用模式（测试或正式）的 Webhook URL 是否与设置中显示的完全一致，以及秘密哈希值是否与插件中的 Secret Hash 相同。等待中的银行转账、USSD 和移动支付在 Flutterwave 确认前会一直等待。开启 Debug log，并查看 WooCommerce > Status > Logs，来源为 wcp_flutterwave_payment。

Webhook 返回 Invalid hash 或 Secret hash not configured：Flutterwave 控制面板中的秘密哈希值与插件中的不同，或插件尚未设置该值。请在两处输入相同值。

Webhook 返回 Verification failed 或 Busy, retry later：无法连接 Flutterwave 来验证付款、交易尚不可见，或订单正在由另一请求更新。Flutterwave 会重试该 Webhook。

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

顾客看到 We could not match this payment to an order：返回链接包含的参考编号并非由此店铺创建。如果顾客已被扣款，请在 Flutterwave 控制面板查找该付款。

Flutterwave 在其页面显示错误：您的 Flutterwave 账户可能不支持订单币种或选定的付款选项。

付款后订单为 On hold：请阅读订单备注。核实的金额或币种与订单不符，或在订单取消后才收到付款。请履行订单或退款。

退款失败并提示模式问题：付款是在测试或正式模式进行的，但该模式的秘密密钥尚未配置。请输入密钥后重试。

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

面向开发者的插件文档列出了过滤器 flw_p_payment_request（发送到 Flutterwave 的数据）、flw_p_currency_decimals（币种精度）和 flw_p_icon（结账图标）。

卸载

停用插件会保留全部数据。要移除插件，请在 Plugins 页面停用并删除。此插件的许可证密钥和许可证状态始终会被移除。只有启用了 Delete data on uninstall 时，才会移除支付网关设置和日志。否则会保留这些数据，以供日后重新安装使用。保存在订单中的 Flutterwave 数据始终保留。现有订单会保留付款备注和交易 ID。

Flutterwave 是其相应所有者的商标。本插件与 Flutterwave 无关联，也未获得 Flutterwave 的认可。