VibeFox Flutterwave for Adobe Commerce — सहायता

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

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 charged in the order currency, the currency the customer sees at checkout. The module does not restrict currencies itself; 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-flutterwave-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/FlutterwavePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_FlutterwavePayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open Flutterwave Payment. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, 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 Webhook Secret Hash (see Configuration). Set Enable to Yes and click Save Config. Test a payment in test mode, then set Live Mode to Yes.

The module adds the Flutterwave payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Flutterwave payment attempts, their events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Flutterwave Payment, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is set in the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: Flutterwave title is required and must not exceed 128 characters., Sort order must be a whole number. or, for Minimum Order Total and Maximum Order Total, Order total must be a number, 0 or greater. Amounts are entered with a dot, for example 9.99.

When Enable is Yes, Magento shows warnings after Save Config: Flutterwave credentials are missing or belong to the wrong mode: followed by the problem (test_empty or live_empty when the secret key of the current mode is empty, test_key_in_live when a test key FLWSECK_TEST-… is used in live mode, live_key_in_test when a live key FLWSECK-… is used in test mode), and Flutterwave webhook Secret Hash is empty. Webhooks will be rejected. While a key problem exists, Flutterwave is hidden at checkout. The warnings check the Default Config values.

Enable: shows or hides Flutterwave at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Flutterwave. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Live Mode: Yes takes real payments with the live secret key. No is test mode: the test secret key is used and no real money is charged. Default: No (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-...).

Webhook Secret Hash: the webhook secret hash. It must match the value in the webhook settings of your Flutterwave dashboard. Flutterwave sends it with every webhook, and the same value is used for test and live mode.

The note under the three secret fields says Encrypted. Leave ****** to retain; clear this field to remove saved credentials. Magento stores the keys and the secret hash encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key or the secret hash, clear the field and click Save Config.

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

Autocomplete Orders: paid orders get the state and status Complete instead of Processing. Default: No.

Payment from Applicable Countries: All Allowed Countries offers Flutterwave for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Flutterwave only for billing addresses in these countries.

Minimum Order Total: offer Flutterwave only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum Order Total: offer Flutterwave only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Debug Log: writes Flutterwave API events for debugging to var/log/flwv_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. Keys, the secret hash, return tokens and e-mail addresses are never logged. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Flutterwave payment history and refunds always stay, so old orders can still be refunded. Default: No.

Below the fields the page shows the Webhook URL of your store and the log: its size, the latest entries and the Clear log button, which empties it.

Webhook

The webhook confirms payments even when the customer does not return to your store. In the Flutterwave dashboard under Settings, Webhooks, enter the URL shown in Webhook URL on the settings page and a secret hash of your choice, in test mode and in live mode. The URL is the storefront address of the default store view and looks like https://your-store/wcpflutterwavepayment/checkout/webhook/. Copy the URL exactly as the settings show it. Enter the same secret hash in Webhook Secret Hash, in the Default Config or for the website of the store. The module reacts to this event:

Other events are ignored. Webhooks without a valid secret hash are rejected. Without the webhook, a payment is confirmed when the customer comes back to your store, or by the Magento cron, which checks open Flutterwave payments every 5 minutes.

Checkout

At the payment step the customer chooses the payment method (by default Flutterwave) and sees the description, the test mode note if test mode is on, and You will be redirected to Flutterwave. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Flutterwave payment for the order total in the order currency, with the customer's e-mail, the name and phone of the billing address, your store name and the order number, 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), such as cards, bank transfer, USSD or mobile money.

After paying, the customer returns to your store. The order is marked paid only after Flutterwave confirms it: the module reads the transaction from Flutterwave on your server, after the webhook, when the customer comes back or by the cron check, and compares the reference, the amount and the currency with the order. Magento then creates the invoice with the Flutterwave reference as the transaction ID and sends the order e-mail. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If the payment is still pending, for example a bank transfer, USSD or mobile money payment, the order stays in Pending Payment and the customer sees a Flutterwave payment confirmation page with Your payment is being confirmed. Please check again. and a Check again link. The webhook or the cron check confirms the order as soon as Flutterwave reports the payment. If the payment needs your review, the page says Your Flutterwave payment needs manual review. Contact the store.

If the payment is declined or the customer cancels on the Flutterwave page, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your Flutterwave payment was not completed. Please try again or choose another method. in the cart. If Flutterwave refuses to start the payment, the order is cancelled and the cart is restored in the same way, with The Flutterwave payment was not completed. Please try again or choose another method. If the answer of Flutterwave is unclear, for example after a timeout, the order is not cancelled, because the payment may still exist: the customer sees Flutterwave could not start or an earlier payment is still pending. Contact the store before retrying. The technical reason is written to the log.

One cart is paid only once: while an earlier payment of the same cart is pending or unclear, a new payment is not started. A payment link paid after its order was cancelled is not lost: the order gets a note for your review.

The module works with the standard Magento checkout. It takes one-time payments only. It has no inline or modal checkout on your site, no saved cards, subscriptions, split payments or payment plans. Flutterwave is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Flutterwave, but Flutterwave has not confirmed the payment yet, or a bank transfer, USSD or mobile money payment is still pending. There is no invoice.

Processing or Complete: the payment was confirmed. Complete is used when Autocomplete Orders is Yes. The invoice is created with the Flutterwave reference (flw_ref) as the transaction ID, and a note shows the amount and how the payment was verified (webhook, return or cron).

On Hold: Flutterwave reported a different amount or currency than the order total. No invoice is created. The note shows the amount paid. Check the payment, then fulfil the order or refund the payment (see Refunds).

Canceled: the payment was declined, cancelled or could not be started, or the order was cancelled in Magento. If Flutterwave reports a payment for a cancelled order later, the order stays cancelled and a note asks for manual review.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for an order that is already paid, the order is not changed. A note and the payment history show it, and you can refund it (see Refunds). The notes are order comments that the customer does not see.

Flutterwave payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title, Flutterwave reference, Environment (test or live) and, while the payment waits, Payment status: Awaiting Flutterwave confirmation. The Information tab also shows Flutterwave payment history: each payment attempt with its reference, mode, requested and captured amount and status, and the Refund history.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Flutterwave. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Flutterwave.

The refund is made in the currency Flutterwave charged, up to the amount it charged minus the amounts already refunded. 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. When Flutterwave reports the refund as completed, Magento creates the credit memo with the Flutterwave refund ID (FLWV-R-…) as the transaction ID. A full refund closes the order.

If Flutterwave accepts the refund but reports it as pending, Magento shows Flutterwave refund is pending or uncertain. No Credit Memo was committed. Verify its dashboard before manual reconciliation. and no credit memo is created. The refund appears in the Refund history of the order. Check it in the Flutterwave dashboard. When it is completed, tick I verified this refund is completed in the Flutterwave dashboard and click Reconcile refund: Magento creates the credit memo without sending the refund again. Until then, no other online refund of this payment is possible. If Flutterwave rejects the refund, Magento shows the error and the credit memo is not created.

A payment that was not invoiced (On Hold after a mismatch, a second payment, a late payment) is refunded in the Flutterwave payment history of the order: enter the amount in Refund actual captured money and click Request refund. The refund and the credit memo buttons need the Admin right to create credit memos.

Refunds made in the Flutterwave dashboard are not synced back to Magento. Create a credit memo with Refund Offline or update the order 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 row of the Flutterwave Payment group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-flutterwave and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees The Flutterwave payment was not completed. Please try again or choose another method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Flutterwave does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the secret key of the current mode is set and matches the mode: a test key (FLWSECK_TEST-…) in test mode, a live key (FLWSECK-…) when Live Mode is Yes. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. Flutterwave is not offered for an order total of 0.

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 Webhook URL, in the mode you use (test or live), and that its secret hash is the same as Webhook Secret Hash in the Default Config or for the website of the store. Pending bank transfers, USSD and mobile money stay pending until Flutterwave confirms them. The order is also confirmed when the customer returns to the store and by the cron check every 5 minutes, so check that the Magento cron is running. Turn on Debug Log and look at the log on the settings page.

Webhook answers unauthorized: the secret hash in the Flutterwave dashboard differs from Webhook Secret Hash, or the module has none. Enter the same value in both places.

Webhook answers busy, retry, notfound, error or unconfigured: the order was being processed by another request at the same moment, Flutterwave could not be reached to verify the payment, the transaction is not visible at Flutterwave yet, or the secret key of the payment's mode is missing. Flutterwave retries the webhook, and the cron check also confirms the payment. Webhooks with an unknown reference are answered with unknown and ignored.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Flutterwave retries the webhook later, and the order is also confirmed when the customer returns or by the cron check.

The customer is back in the cart with The Flutterwave payment was not completed after Place Order: turn on Debug Log and look at the log. A wrong key, a currency your Flutterwave account does not support or unsupported payment options make Flutterwave refuse the payment. The order total must also fit the precision of the order currency: whole numbers for currencies without decimals, such as XOF, XAF, UGX and RWF, three decimals for BHD, KWD and similar currencies. Otherwise the payment is not started. The order of that attempt is cancelled.

The customer sees Flutterwave could not start or an earlier payment is still pending: Flutterwave did not answer clearly when the payment was created, or an earlier payment of the same cart is still open. Check the payment in the Flutterwave dashboard and the Flutterwave payment history of the order. The cron check confirms the payment if it was made.

The customer sees Invalid Flutterwave return: the return link does not belong to the order. If the customer was charged, find the payment in the Flutterwave dashboard.

Order is On Hold after payment: read the order notes and the Flutterwave payment history (see Order statuses), then fulfil the order or refund the payment.

Refund fails with The original Flutterwave credentials are missing: the payment was made in test or live mode, and the secret key of that mode is not set. Enter it and try again.

Refund fails with A Flutterwave refund is pending or uncertain: an earlier refund of this payment is pending or its result is unknown. Check it in the Flutterwave dashboard and reconcile it in the Refund history (see Refunds). When a refund has no Flutterwave refund ID, it cannot be reconciled: refund in the Flutterwave dashboard, then create a credit memo with Refund Offline.

Refund fails with The Flutterwave order changed. Reload the Credit Memo before requesting a refund.: the order was changed by another refund while the credit memo page was open. Open the credit memo again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) is refunded in the Flutterwave payment history.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

For developers, the README of the module lists the events flwv_payment_request (data sent to Flutterwave) and flwv_currency_decimals (currency precision).

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_FlutterwavePayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_FlutterwavePayment to remove the data, then bin/magento module:disable Vibefox_FlutterwavePayment, delete the folder app/code/Vibefox/FlutterwavePayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Flutterwave payment history and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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