VibeFox Flutterwave for PrestaShop — 帮助
系统要求
PrestaShop：8.0 至 9.x。
PHP：8.0 或更高版本。模块拒绝安装在较旧的 PHP 版本上。
Flutterwave 账户：您需要 Flutterwave 账户的秘密密钥，位于 Flutterwave 控制面板的 Settings, API keys 下：测试模式使用 FLWSECK_TEST-…，正式模式使用 FLWSECK-…。模块只使用秘密密钥，不需要公开密钥和加密密钥。您还需要设置一个带有您自选秘密哈希值的 Webhook（参见配置）。
币种：购物车始终按购物车币种扣款。模块本身不限制国家或币种；如果您的账户不支持该币种，Flutterwave 会显示错误。您可以在 Payment > Preferences 中限制币种、国家和顾客群组。
VibeFox 许可证密钥：在 vibefox.net 购买。一个密钥只能用于一个域名。
安装
1. 在后台依次进入 Modules > Module Manager，点击 Upload a module，选择模块的 ZIP 文件。
2. 上传完成后，点击 Configure；或者之后在模块列表中找到 VibeFox Flutterwave Payment，然后点击 Configure。
3. 在 Configure 页面顶部的许可证区块中，将您的 VibeFox 许可证密钥输入 License key 字段，然后点击 Activate（参见许可证密钥）。
4. 输入您的秘密密钥，在 Flutterwave 控制面板中设置 Webhook，并在模块中输入相同的秘密哈希值（参见配置）。
5. 开启 Enable/Disable 并点击 Save。先在测试模式下测试一笔付款，然后开启 Live mode。
安装时，模块会创建两个订单状态：Awaiting Flutterwave payment 和 Flutterwave payment on hold。PrestaShop 会为所有币种、国家和顾客群组提供一个新的支付模块。您可以在 Payment > Preferences 中限制它们。
配置
所有设置都在模块页面中：Modules > Module Manager > VibeFox Flutterwave Payment > Configure。每个部分都有自己的 Save 按钮，点击后会保存整个页面。在字段上方，页面会显示 Live mode: real payments are accepted. 或 Test mode: no real money is charged. 当当前模式的秘密密钥为空、正式密钥字段在正式模式下包含测试密钥（FLWSECK_TEST-…），或测试密钥字段在测试模式下包含正式密钥（FLWSECK-…）时，页面会发出警告；此时付款方式在结账时会被隐藏，直到问题修正为止。当未设置 Webhook 秘密哈希值时，页面也会发出警告：此时 Webhook 会被拒绝，付款只有在顾客返回您的店铺时才会被确认。第一个部分的标题会显示当前模式，即 TEST 或 LIVE。
Flutterwave
Enable/Disable：Enable Flutterwave Payment 用于开启或关闭该付款方式。默认：关闭。
Title：顾客在结账时看到的付款方式标题。它也是保存在订单中的付款方式名称。默认：Flutterwave。必填。
Description：顾客在结账时在付款方式下方看到的文字。默认：Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.
API 密钥
从 Flutterwave 控制面板的 Settings, API keys 中复制秘密密钥（该部分有一个链接）。测试模式和正式模式使用不同的密钥。
Live mode：接受真实付款。若要使用测试模式，请将其关闭。测试模式使用测试秘密密钥，不会扣除任何真实款项。正式模式使用正式秘密密钥。默认：关闭（测试模式）。测试模式开启时，顾客会在付款方式下方看到 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. 只有在您想更改时才输入新值。
Webhook
即使顾客没有返回您的店铺，Webhook 也能确认付款。请在 Flutterwave 控制面板的 Settings, Webhooks 中，输入本部分 Webhook URL 所显示的 URL，并在测试模式和正式模式下分别输入您自选的秘密哈希值。使用友好 URL 时，地址形如 https://your-shop/module/wcp_flutterwave_payment/webhook，可能还带有语言代码，例如 /en/。请完全按照设置页面显示的内容复制 URL。模块会响应以下事件：
其他事件将被忽略。
Secret Hash：Webhook 的秘密哈希值。它必须与您 Flutterwave 控制面板中 Webhook 设置里的值一致。Flutterwave 会随每个 Webhook 发送该值，测试模式和正式模式使用同一个值。没有有效秘密哈希值的 Webhook 会被拒绝。没有 Webhook 时，只有在顾客返回您的店铺后，付款才会被确认。
Clear saved secrets：勾选 Test Secret Key、Live Secret Key 或 Secret Hash，然后点击 Save 即可删除它。空字段会保留已保存的值。
付款
Payment Options：要在 Flutterwave 页面上显示的付款方式，用英文逗号分隔，例如 card、banktransfer、ussd、mobilemoney。留空则显示您账户中启用的所有方式。保存时会整理该列表（转为小写，去除重复项）。
Autocomplete Orders：已付款订单会获得 Delivered 状态，而不是 Payment accepted，且只经历一次状态变更。默认：关闭。
高级
Debug log：将 Flutterwave API 事件记录到模块文件夹中的 logs/flwv_debug.log.php，用于调试。该文件无法通过网页打开。错误和警告始终会被记录。密钥、秘密哈希值和顾客数据绝不会被记录。默认：关闭。
Log：显示日志的大小和最新条目。点击 Clear log 可清空日志。
Delete data on uninstall：卸载模块时删除模块设置和日志。保存在订单上的付款数据始终保留。默认：关闭。
结账
在付款步骤中，顾客选择付款方式（默认为 Flutterwave）并确认。需要有效的电子邮件地址。模块会按购物车币种为购物车总额创建一笔 Flutterwave 付款，并附上顾客的电子邮件、账单地址中的电话和姓名、您的店铺名称和徽标，然后将顾客带到 Flutterwave 付款页面。顾客在那里使用您账户中启用的任意方式付款（或 Payment Options 中列出的方式）。此时尚未生成订单。
付款后，顾客返回您的店铺。只有在 Flutterwave 确认付款后，订单才会被标记为已付款：可能通过 Webhook，也可能通过顾客返回时进行的服务器端检查。随后订单会被创建，顾客会看到标准的订单确认页面。如果付款仍在等待中，例如银行转账、USSD 或移动支付，订单会以 Awaiting Flutterwave payment 状态创建，页面会显示 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. 如果等待中的付款之后失败，顾客再次打开确认页面时，会看到 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 created as soon as it is confirmed — 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. 购物车会保留，顾客可以再次付款。每次尝试都有自己的参考编号，较早创建、后来才付款的付款链接仍会被接受。
如果 Flutterwave 无法启动付款，顾客会停留在结账页面，并看到一条简短提示，例如 Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. 技术原因会写入日志。
如果在付款与确认之间购物车发生了变化，例如在另一个浏览器标签页中修改，金额将不再一致，订单会进入 Flutterwave payment on hold 状态并附带备注。
即使店铺处于维护模式，Webhook 仍然有效，并且不受店铺国家限制的阻止。
本模块仅接受一次性付款。不支持在您的网站内嵌入结账表单或使用弹窗结账，也不支持保存银行卡、订阅、拆分付款或付款计划。托管付款链接无法通过 Flutterwave API 取消，因此购物车的旧链接仍可能被付款。
订单与退款
订单状态
尚无订单：顾客已被转到 Flutterwave，但尚未付款，或 Flutterwave 尚未确认付款。此时只存在购物车。
Payment accepted or Delivered：付款已确认。当 Autocomplete Orders 开启时使用 Delivered。付款会以 Flutterwave 参考编号（flw_ref）作为交易 ID 记录，备注中会显示金额、付款方式、参考编号、交易和模式。
Awaiting Flutterwave payment：顾客在 Flutterwave 上的付款仍在等待时返回了店铺。当 Flutterwave 确认付款后，订单会转为已付款状态。
Flutterwave payment on hold：经核实的金额或币种与购物车不符，或付款是在订单被取消之后到达的。付款会按实际支付的金额记录（而非 Flutterwave 以其他币种扣除的金额）。备注会说明原因。请处理订单或对付款进行退款。已退款或已取消的订单绝不会因重复的 Webhook 而被重新打开。
Payment error：Flutterwave 报告，等待中订单的最近一次付款尝试失败或已取消。备注会显示原因。
Canceled：由您设置。如果 Flutterwave 之后报告了已取消订单的付款，订单会转为 Flutterwave payment on hold（见上文）。
Refunded：付款已通过模块全额退款。
如果已付款订单又收到第二笔付款，订单不会改变。备注会提示您在 Flutterwave 控制面板中退还重复付款。
Flutterwave payment 区块
订单页面会显示一个 Flutterwave payment 区块，其中包含参考编号（tx_ref）、交易 ID 和 Flutterwave 参考编号、模式、状态和付款方式、已付金额和已退金额、测试付款的 Test mode 标记、退款记录以及订单的 Flutterwave notes。
退款
在 Flutterwave payment 区块中输入金额（会自动填入尚未退款的金额），可选填写原因，然后点击 Refund via Flutterwave。确认提示 Refund this amount through Flutterwave? This cannot be undone. 支持全额和部分退款。您需要具备编辑订单的权限；无需访问模块页面。退款金额和币种与 Flutterwave 实际扣款一致，因此在金额或币种不符的情况下，您最多只能退还顾客实际支付的金额，而非订单总额。退款会使用付款时所处模式（测试或正式）的秘密密钥发送，因此必须已设置该密钥。如果 Flutterwave 拒绝退款，该区块会显示错误，且不会记录任何退款。退款成功后，会将其添加到退款记录和备注中，包括退款 ID 和状态（completed，或 initiated 并附带 Flutterwave 报告的状态）。全额退款会将订单设为 Refunded。部分退款不会改变订单状态。Flutterwave 确认付款后，才可以退款。
模块不会创建信用单。订单页面上标准的 PrestaShop 退款按钮不会通过 Flutterwave 退款。
在 Flutterwave 控制面板中进行的退款不会同步回 PrestaShop。如有需要，请手动更新订单状态。
许可证密钥
模块使用来自 vibefox.net 的 VibeFox 许可证密钥。许可证区块 License — VibeFox Flutterwave Payment 是 Modules > Module Manager > VibeFox Flutterwave Payment > Configure 页面中位于设置上方的第一个区块。将密钥输入 License key，然后点击 Activate。之后，该区块会显示遮蔽后的密钥、状态（例如许可证有效期截止日期和您的域名），以及按钮 Check now（重新检查状态）、Change key（输入另一个密钥）和 Remove key（从此商店移除密钥）。它们下方是 Product: presta-payment-flutterwave 这一行，以及打开您 vibefox.net 账户的链接 Manage licenses and domains in your account。只有拥有该模块 Configure 权限的员工才能更改密钥。该区块的文字跟随后台语言显示（包含英文和俄文）。
如果密钥未被接受，该区块会说明原因，例如 Key not found、This key belongs to another product、Domain limit reached，或带有日期的 License expired on。商店地址更改后，或在您的账户中释放了一个域名名额后，请点击 Check now。如果无法连接许可证服务器，模块将继续按最后已知的状态运行。
一个密钥只能用于一个域名：即主商店的域名，多店铺设置中也是如此。从商店中移除密钥不会释放其域名名额。请在您的 vibefox.net 账户中释放该名额。
没有有效密钥时，结账时不会向顾客显示 Flutterwave。如果仍然启动了付款，顾客会看到 This payment method is not available. Please choose another one. PrestaShop 前台无法得知您已登录后台，因此付款方式对您也会被隐藏：您可以在购买密钥之前设置模块，但无法在结账时测试它。提醒会出现在 Modules > Module Manager 的 Alerts 选项卡中。现有订单不受影响：已发起的付款仍会被确认，退款也仍然可用。
许可证过期后，模块仍会继续运行，但更新和支持需要续期。在您于后台工作时，系统会自动重新检查状态：输入密钥后的前 14 天每天一次，之后每周一次。无需 cron 任务。卸载或重置模块总会删除许可证密钥和许可证状态。
故障排除
结账时不显示 Flutterwave：请检查许可证是否有效，Enable/Disable 是否已开启，以及当前模式的秘密密钥是否已填写且与模式相符：测试模式使用测试密钥（FLWSECK_TEST-…），正式模式使用正式密钥（FLWSECK-…）。否则设置页面会显示警告。在 Payment > Preferences 中，请检查模块是否允许购物车币种、顾客所在国家和顾客所属群组。
付款已完成，但未创建订单：Webhook 无法正常工作。请在 Flutterwave 控制面板中检查 Webhook URL 是否与 Webhook URL 中显示的完全一致，并且是您所使用模式（测试或正式）中的 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 created, retry later：无法连接 Flutterwave 以验证付款，交易尚不可见，购物车正被另一个请求处理，或者无法创建订单（例如模块已被禁用）。Flutterwave 会重试该 Webhook。日志会显示原因。
Webhook URL 在浏览器中显示 Empty body：这是正常的。该 URL 只接受来自 Flutterwave 的 Webhook。
顾客看到 Payment gateway is not properly configured：当前模式的秘密密钥缺失，或属于另一种模式。
顾客看到 We could not match this payment to an order：返回链接中携带的参考编号不属于顾客的购物车。如果顾客已被扣款，请在 Flutterwave 控制面板中查找该笔付款。
Flutterwave 页面上显示错误，或顾客看到 Flutterwave could not start the payment：您的 Flutterwave 账户可能不支持购物车币种或所选的付款选项。
付款后订单处于 Flutterwave payment on hold：请阅读 Flutterwave payment 区块中的备注（见订单状态），然后处理订单或对付款进行退款。
退款失败并显示与模式相关的消息：付款是在测试或正式模式下进行的，而该模式的秘密密钥未设置。请输入该密钥后重试。
退款返回 Another operation on this payment is running：当时正在发送同一订单的另一笔退款。请稍候，检查退款记录，必要时再重试。
对于开发者，模块的 README 列出了钩子 actionWcpFlutterwavePaymentRequest（发送给 Flutterwave 的数据）和 actionWcpFlutterwaveCurrencyDecimals（币种小数位精度）。
卸载
进入 Modules > Module Manager，打开 VibeFox Flutterwave Payment 旁边的菜单，然后选择 Uninstall。该模块的许可证密钥和许可证状态始终会被删除。如果 Delete data on uninstall 已开启，模块设置和日志将被删除。如果已关闭，所有设置都会保留，以便日后重新安装。订单中的 Flutterwave 付款数据和退款，以及 Awaiting Flutterwave payment 和 Flutterwave payment on hold 订单状态始终会保留，因此之前已付款的订单在重新安装后仍可退款。现有订单会保留其付款备注和交易 ID。
Flutterwave 是其各自所有者的商标。本模块与 Flutterwave 无关联，也未获得 Flutterwave 的认可。