VibeFox Flutterwave for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without WooCommerce.

PHP: 8.0 or later. The plugin refuses to activate on older PHP.

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 order is always charged in the order currency. The plugin does not restrict countries or currencies; Flutterwave shows an error if your account does not support the currency.

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

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_flutterwave_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Flutterwave > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

6. Turn on Enable/Disable, test a payment in test mode, then tick Live mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Flutterwave. 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 store. In the list of payment methods, Flutterwave is marked as needing setup until the current mode has a secret key, and shows a test mode badge in test mode.

General

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

Title: the payment method title customers see during checkout. Default: Flutterwave.

Description: the text customers see 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. Test mode and live mode have different keys.

Live mode: Accept real payments (uncheck 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).

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

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

Webhook

The webhook confirms payments even when the customer does not return to your store. In the Flutterwave dashboard under Settings, Webhooks, enter the Webhook URL shown in this section and a secret hash of your choice, in test mode and in live mode. The URL looks like https://your-site/wc-api/flw_p_webhook/. The plugin 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. Webhooks without a valid secret hash are rejected. Without the webhook, a payment is confirmed only when the customer comes back to your store.

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.

Autocomplete Orders: Automatically mark orders as completed after successful payment. If enabled, orders are set to Completed instead of Processing after payment, with one status change. Default: off.

Advanced

Debug log: Log Flutterwave API events for debugging to WooCommerce > Status > Logs, source wcp_flutterwave_payment. Errors are always logged. Keys and customer data are never logged. Default: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Payment data saved on orders is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Flutterwave) and places the order. In test mode the checkout shows TEST MODE - no real payments will be processed. A valid billing e-mail is required. The plugin creates a Flutterwave payment for the order total in the order currency, with the customer's e-mail, phone and name, your site 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).

After paying, the customer returns to your store. The order is marked paid only after Flutterwave confirms it: by the webhook or by a server-side check when the customer returns. If the payment is not confirmed yet, for example a pending bank transfer, USSD or mobile money payment, the order received page shows Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. If the money arrived but the plugin put the order on hold for review, for example because the paid amount does not match the order, the page shows Your payment was received and your order is being reviewed. We will contact you if anything is needed.

If the payment is declined, the customer goes back to the checkout (or to the Pay for order page) with Your payment was declined. You can try again or choose another payment method. If the customer cancels on the Flutterwave page, an order placed at checkout is cancelled, an order created manually stays unpaid, and 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.

A customer can pay an unpaid order 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 sees a short message, for example Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS). The customer-facing texts are translated into French.

The plugin 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 an order can still be paid.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Flutterwave and has not paid yet, or the payment is still pending at Flutterwave.

Processing or Completed: the payment was confirmed. Completed is used when Autocomplete Orders is on (orders with only virtual downloadable products also become Completed, the WooCommerce default). The order note shows the amount, the payment method, the Flutterwave reference, the transaction and the mode. The transaction ID of the order is the Flutterwave reference.

On hold after payment: the verified amount or currency did not match the order, or the payment arrived after the order had been cancelled. The note explains it. Fulfil the order or refund the payment. A refunded or cancelled order is never reopened by a replayed webhook.

Failed: Flutterwave reported the latest payment attempt of a pending order as failed or cancelled. The note shows the reason.

Cancelled: the customer cancelled on the Flutterwave page after placing the order at checkout, or the order was cancelled by you or by the WooCommerce stock hold timeout.

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.

Refunds

Open the order, click Refund, enter the amount and click Refund via Flutterwave. Full and partial refunds are supported. 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, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the refund ID and status (completed, or initiated with the status reported by Flutterwave).

Refunds made in the Flutterwave dashboard are not synced back to WooCommerce. If needed, create a manual refund in WooCommerce without Refund via Flutterwave.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Flutterwave. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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.

The payment went through, but the order stays Pending payment: the webhook is not working. In the Flutterwave dashboard check that the webhook URL is exactly the one shown in the settings, in the mode you use (test or live), and that its secret hash is the same as Secret Hash in the plugin. Pending bank transfers, USSD and mobile money stay pending until Flutterwave confirms them. Turn on Debug log and look at WooCommerce > Status > Logs, source wcp_flutterwave_payment.

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

Webhook answers Verification failed or Busy, retry later: Flutterwave could not be reached to verify the payment, the transaction is not visible yet, or the order was being updated by another request. Flutterwave retries the webhook.

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 this store did not create. If the customer was charged, find the payment in the Flutterwave dashboard.

Flutterwave shows an error on its page: your Flutterwave account may not support the order currency or the selected payment options.

Order is On hold after payment: read the order note. The verified amount or currency did not match the order, or the payment arrived after the order had been cancelled. 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers, the plugin documentation lists the filters flw_p_payment_request (data sent to Flutterwave), flw_p_currency_decimals (currency precision) and flw_p_icon (checkout icon).

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Flutterwave data saved on orders is always kept. Existing orders keep their payment notes and transaction IDs.

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