Troubleshooting

For merchants

Logs

Flutterwave writes to Shopware's main log (var/log/<env>-<date>.log); every line starts with [Flutterwave]. Errors are always logged; enable Enable Detailed Logging in the configuration for more, per sales channel, and switch it off afterwards.

grep "\[Flutterwave\]" var/log/prod-*.log

For Shopware's logging setup see Shopware: Logging.

Installation problems

Not listed in Extensions → My extensions — bin/console plugin:refresh.

Composer: "could not find a version matching your minimum-stability" — use composer require "kommandhub/flutterwave-sw:^0.9@beta".

All settings are empty after upgrading from 0.9.0-beta.1 — the plugin was renamed to KmhFlutterwaveSW and its settings moved to KmhFlutterwaveSW.config.*. Re-enter keys and hashes — see Installation → Updating.

Pay with Flutterwave not offered at checkout — assign it to the sales channel (Sales Channels → (channel) → General → Payment methods), check it is active, and that any availability rule on it matches. The method is also blocked for carts with a total of zero.

Configuration problems

Checkout says "Flutterwave is not configured correctly for this shop…" — the Secret Key for the active mode is empty on this sales channel, or it does not match the mode: a test key (FLWSECK_TEST-…) with Enable Sandbox off, or a live key with it on. Check Enable Sandbox and the matching key, including per-sales-channel overrides.

Webhook problems

Webhooks return 403

The verif-hash header does not equal the Webhook Secret Hash for the active mode.

1. The hash is set in the plugin — webhooks are rejected while no hash is configured anywhere.
2. It is saved on All Sales Channels or on a sales channel — either is accepted.
3. It matches the dashboard exactly, for the same mode (test hash in Test configuration with sandbox on, live hash in Live configuration with sandbox off).
4. It is the value you chose under Settings → Webhooks, not an API key.

Customer paid, but the order stays unpaid

1. Webhook URL for the right mode: https://<your-shop-domain>/flutterwave/webhook.
2. The domain is configured on a Shopware sales channel — otherwise Shopware answers 400.
3. Flutterwave's webhook log shows the response code; the shop log shows [Flutterwave] warnings. 200 means the plugin handled (or deliberately ignored) the delivery.

Payment problems

Payment failed: amount or currency mismatch — Flutterwave reports a different amount or currency than the order, so it is not marked paid. The log shows expected and received values. This is a safety check.

Payment failed: transaction reference mismatch — the Flutterwave transaction belongs to a different order (its tx_ref is not this order transaction). The plugin refuses to reuse a payment for another order.

Payment shows Cancelled — the customer cancelled on Flutterwave's page. They can pay again from their account.

Refund problems

Refund button missing or refund refused:

Message / symptom	Cause
No Refund button	Enable Refunds is off, or your role lacks Process Flutterwave refunds
Transaction is not in a refundable state	Payment is not Paid / Partially paid / Partially refunded
This transaction has no Flutterwave transaction id	The payment was never verified by the plugin
Refund amount must be at least … / exceeds the refundable balance of …	Adjust the amount
Unable to verify the refundable balance	Flutterwave's refund history could not be loaded — try again later

Refund stays pending — normal for up to 3–15 working days. It completes when a refund.completed webhook arrives and the Flutterwave API confirms a final status. If it has been longer, check refund events are enabled for the webhook in Flutterwave.

Bank details problems

"only 044 is allowed" in sandbox — Flutterwave's sandbox only resolves bank code 044; the plugin substitutes it automatically while sandbox mode is on. Seeing this error means sandbox mode is off while you use test keys.

Account number rejected — the form requires exactly 10 digits (see Known issues).

"Please verify your account number before saving." — the account was not verified in this session, or the number or bank changed after verification. Verify again, then save.

"Too many verification attempts. Please try again later." — a customer can verify at most 10 accounts per hour.

Known issues

In version 0.9.0-beta.2:

Issue	Impact	Workaround
Payment Options is saved but not sent to Flutterwave.	All options on the account are offered.	Configure options in Flutterwave.
Session Duration, Max Retry Attempts and the Public Key fields are not used.	No effect.	—
Payment Method Logo sends a media ID where Flutterwave expects an image URL.	Logo unlikely to show.	—
Bank-details form accepts only 10-digit account numbers regardless of Bank Country.	Customers outside Nigeria may be unable to save.	—
The role permission ships without a translated label (no sw-privileges snippet).	Under Additional permissions the entry may show a raw snippet key instead of Flutterwave → Process Flutterwave refunds.	Tick the entry under the Flutterwave category; it is the flutterwave.refund permission.
BVN stored unencrypted.	Readable by Administration users with customer access.	Enable only if needed; restrict roles.

Still stuck? Contact support with versions and log lines.