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".

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.

Configuration problems

Checkout shows a configuration error — the Secret Key for the active mode is empty on this sales channel. 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 it is empty.
2. It is saved on All Sales Channels — webhook verification ignores per-sales-channel values.
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 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 with a final status arrives. 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).

Known issues

In version 0.9.0-beta.1:

Issue	Impact	Workaround
Webhooks are verified with the secret hash on All Sales Channels only.	Webhooks from an account with a different hash are rejected.	Use one hash for all sales channels.
Payment Options is saved but not sent to Flutterwave.	All options on the account are offered.	Configure options in Flutterwave.
Session Duration and Max Retry Attempts are not used.	No effect.	—
Payment Method Logo sends a media ID where Flutterwave expects an image URL.	Logo unlikely to show.	—
refund.completed takes the refund status from the webhook body without re-checking the API.	Anyone holding the webhook secret hash could complete or fail a pending refund in Shopware (money at Flutterwave is unaffected).	Keep the hash long, random and private; rotate it if exposed.
Bank-details form accepts only 10-digit account numbers regardless of Bank Country.	Customers outside Nigeria may be unable to save.	—
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.