VibeFox Flutterwave for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Flutterwave account: you need the secret keys of your Flutterwave account, from the Flutterwave dashboard under Settings, API keys: FLWSECK_TEST-… for test mode and FLWSECK-… for live mode. Only the secret keys are used. The public and encryption keys are not needed. You also set up a webhook with a secret hash of your choice (see Configuration).

Currencies: the cart is always charged in the cart currency. The module does not restrict countries or currencies itself; Flutterwave shows an error if your account does not support the currency. You can limit currencies, countries and customer groups in Payment > Preferences.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Flutterwave Payment in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter your secret keys, set up the webhook in the Flutterwave dashboard and enter the same secret hash in the module (see Configuration).

5. Turn on Enable/Disable and click Save. Test a payment in test mode, then turn on Live mode.

On install the module creates two order statuses, Awaiting Flutterwave payment and Flutterwave payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows Live mode: real payments are accepted. or Test mode: no real money is charged. It warns you when the secret key of the current mode is empty, when the live key field contains a test key (FLWSECK_TEST-…) in live mode, or when the test key field contains a live key (FLWSECK-…) in test mode; the payment method is then hidden at checkout until this is fixed. It also warns you when no webhook secret hash is set: webhooks are then rejected and payments are confirmed only when the customer returns to your shop. The title of the first section shows the current mode, TEST or LIVE.

Flutterwave

Enable/Disable: Enable Flutterwave Payment turns the payment method on or off. Default: off.

Title: the payment method title customers see during checkout. It is also the payment method name stored in the order. Default: Flutterwave. Required.

Description: the text customers see under the payment method during checkout. Default: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

API keys

Copy the secret keys from the Flutterwave dashboard under Settings, API keys (the section has a link). Test mode and live mode have different keys.

Live mode: accept real payments. Turn it off for test mode. Test mode uses the test secret key and no real money is charged. Live mode uses the live secret key. Default: off (test mode). While test mode is on, customers see TEST MODE - no real payments will be processed. under the payment method.

Test Secret Key: your Flutterwave test secret key (FLWSECK_TEST-...).

Live Secret Key: your Flutterwave live secret key (FLWSECK-...).

Saved keys and the secret hash are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Webhook

The webhook confirms payments even when the customer does not return to your shop. In the Flutterwave dashboard under Settings, Webhooks, enter the URL shown in Webhook URL in this section and a secret hash of your choice, in test mode and in live mode. With friendly URLs the URL looks like https://your-shop/module/wcp_flutterwave_payment/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it. The module reacts to this event:

Other events are ignored.

Secret Hash: the webhook secret hash. It must match the value in your Flutterwave dashboard webhook settings. Flutterwave sends it with every webhook, and the same value is used for test and live mode. Webhooks without a valid secret hash are rejected. Without the webhook, a payment is confirmed only when the customer comes back to your shop.

Clear saved secrets: tick Test Secret Key, Live Secret Key or Secret Hash and click Save to remove it. An empty field keeps the saved value.

Payment

Payment Options: comma-separated payment methods to show on the Flutterwave page, for example card, banktransfer, ussd, mobilemoney. Leave empty for all methods enabled on your account. The list is cleaned up when you save (lower case, no duplicates).

Autocomplete Orders: paid orders get the status Delivered instead of Payment accepted, with one status change. Default: off.

Advanced

Debug log: logs Flutterwave API events for debugging to logs/flwv_debug.log.php in the module folder. The file cannot be opened from the web. Errors and warnings are always logged. Keys, the secret hash and customer data are never logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: removes the module settings and logs when the module is uninstalled. Payment data saved on orders is always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Flutterwave) and confirms. A valid e-mail address is required. The module creates a Flutterwave payment for the cart total in the cart currency, with the customer's e-mail, the phone and name of the invoice address, your shop name and logo, and sends the customer to the Flutterwave checkout page. There the customer pays with one of the methods enabled on your account (or listed in Payment Options). No order exists yet at this point.

After paying, the customer returns to your shop. The order is marked paid only after Flutterwave confirms it: by the webhook or by a server-side check when the customer returns. The order is then created and the customer sees the standard order confirmation page. If the payment is still pending, for example a bank transfer, USSD or mobile money payment, the order is created in Awaiting Flutterwave payment and the page shows Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. If the order was put on hold for review, for example because the paid amount does not match the cart, the page shows Your payment was received and your order is being reviewed. We will contact you if anything is needed. If a pending payment later fails and the customer opens the confirmation page again, it shows Your Flutterwave payment was not completed. Please contact us about this order.

If Flutterwave cannot be reached when the customer comes back, a Payment confirmation page says Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. with the buttons Check again and Back to checkout. The webhook creates the order as soon as it arrives.

If the payment is declined, the customer is back at checkout with Your payment was declined. You can try again or choose another payment method. If the customer cancels on the Flutterwave page, the message is Payment was cancelled. You can try again or choose another payment method. If the payment was not completed, the message is The payment was not completed. You can try again or choose another payment method. The cart is kept, and the customer can pay again. Every attempt has its own reference, and an older payment link that is paid later is still accepted.

If Flutterwave cannot start the payment, the customer stays at checkout with a short message, for example Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. The technical reason is written to the log.

If the cart changes between the payment and its confirmation, for example in another browser tab, the amounts no longer match and the order goes to Flutterwave payment on hold with a note.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module takes one-time payments only. It has no inline or modal checkout on your site, no saved cards, subscriptions, split payments or payment plans. Hosted payment links cannot be cancelled through the Flutterwave API, so an old link of a cart can still be paid.

Orders and refunds

Order statuses

No order yet: the customer was sent to Flutterwave and has not paid, or Flutterwave has not confirmed the payment yet. Only the cart exists.

Payment accepted or Delivered: the payment was confirmed. Delivered is used when Autocomplete Orders is on. The payment is recorded with the Flutterwave reference (flw_ref) as the transaction ID, and a note shows the amount, the payment method, the reference, the transaction and the mode.

Awaiting Flutterwave payment: the customer came back while the payment was still pending at Flutterwave. The order moves to the paid status when Flutterwave confirms the payment, by the webhook or when the customer opens the return link from Flutterwave again.

Flutterwave payment on hold: the verified amount or currency did not match the cart, or the payment arrived after the order had been cancelled. The payment is recorded with the amount actually paid (not when Flutterwave charged another currency). The note explains it. Fulfil the order or refund the payment. A refunded or cancelled order is never reopened by a repeated webhook.

Payment error: Flutterwave reported the latest payment attempt of an awaiting order as failed or cancelled. The note shows the reason.

Canceled: set by you. If Flutterwave reports a payment for a canceled order later, the order goes to Flutterwave payment on hold (see above).

Refunded: the payment was fully refunded through the module.

If a second payment is received for an order that is already paid, the order is not changed. A note asks you to refund the duplicate in the Flutterwave dashboard.

Flutterwave payment block

The order page shows a Flutterwave payment block with the reference (tx_ref), the transaction ID and Flutterwave reference, the mode, the status and payment method, the amount paid and refunded, a Test mode badge for test payments, the refund history and the Flutterwave notes of the order.

Refunds

In the Flutterwave payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Flutterwave. Confirm the question Refund this amount through Flutterwave? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. Refunds are made in the amount and currency Flutterwave charged, so after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total. The refund is sent with the secret key of the mode the payment was made in (test or live), so that key must be set. If Flutterwave rejects the refund, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the refund ID and status (completed, or initiated with the status reported by Flutterwave). A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once Flutterwave has confirmed the payment.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Flutterwave.

Refunds made in the Flutterwave dashboard are not synced back to PrestaShop. Update the order status manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Flutterwave Payment is the first block on Modules > Module Manager > VibeFox Flutterwave Payment > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-flutterwave and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Flutterwave is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Flutterwave does not appear at checkout: check that the license is active, Enable/Disable is on and the secret key of the current mode is filled in and matches the mode: a test key (FLWSECK_TEST-…) in test mode, a live key (FLWSECK-…) in live mode. The settings page shows a warning otherwise. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the webhook is not working. In the Flutterwave dashboard check that the webhook URL is exactly the one shown in Webhook URL, in the mode you use (test or live), and that its secret hash is the same as Secret Hash in the module. Pending bank transfers, USSD and mobile money stay pending until Flutterwave confirms them. The order is also created when the customer returns to the shop after paying. Turn on Debug log and look at the Log field on the module page.

Webhook answers Invalid hash or Secret hash not configured: the secret hash in the Flutterwave dashboard differs from the one in the module, or the module has none. Enter the same value in both places.

Webhook answers Verification failed, Busy, retry later or Order could not be created, retry later: Flutterwave could not be reached to verify the payment, the transaction is not visible yet, the cart was being processed by another request, or the order could not be created (for example, the module is disabled). Flutterwave retries the webhook. The log shows the reason.

The webhook URL shows Empty body in the browser: this is normal. The URL accepts only webhooks from Flutterwave.

The customer sees Payment gateway is not properly configured: the secret key of the current mode is missing or belongs to the other mode.

The customer sees We could not match this payment to an order: the return link carries a reference that does not belong to the customer's cart. If the customer was charged, find the payment in the Flutterwave dashboard.

Flutterwave shows an error on its page, or the customer sees Flutterwave could not start the payment: your Flutterwave account may not support the cart currency or the selected payment options.

Order is Flutterwave payment on hold after payment: read the notes in the Flutterwave payment block (see Order statuses), then fulfil the order or refund the payment.

Refund fails with a message about the mode: the payment was made in test or live mode, and the secret key of that mode is not configured. Enter it and try again.

Refund answers Another operation on this payment is running: another refund of the same order was being sent at that moment. Wait a moment, check the refund history and try again if needed.

For developers, the README of the module lists the hooks actionWcpFlutterwavePaymentRequest (data sent to Flutterwave) and actionWcpFlutterwaveCurrencyDecimals (currency precision).

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Flutterwave Payment and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Flutterwave payment data and refunds of orders and the order statuses Awaiting Flutterwave payment and Flutterwave payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

Flutterwave is a trademark of its respective owner. This module is not affiliated with or endorsed by Flutterwave.