Installation

For merchants

From zero to a verified test payment, then live.

Requirements

• Shopware 6.6 or 6.7, PHP 8.2+.
• A Flutterwave account (dashboard).
• Your shop on HTTPS with a public domain configured on a sales channel, so Flutterwave can reach the webhook URL.
• A database backup before installing on a live shop.

1. Install the plugin

Option A — Composer (recommended)

composer require "kommandhub/flutterwave-sw:^0.9@beta"

@beta is required while the plugin is in beta. Background: Shopware: extension management.

Option B — ZIP upload

1. Get the release ZIP for version 0.9.0-beta.2.
2. Extensions → My extensions → Upload extension (Shopware: My extensions), select the ZIP.

2. Activate

bin/console plugin:refresh
bin/console plugin:install --activate KmhFlutterwaveSW
bin/console cache:clear

Or Install and switch it active in Extensions → My extensions.

Activation creates the payment method Pay with Flutterwave (technical name kommandhub_flutterwave_payment), not yet assigned to any sales channel, and customer custom fields for bank details. No migrations, no background worker.

3. Collect keys and choose a webhook hash

In the Flutterwave dashboard, test mode:

1. Settings → API Keys — copy the Public Key (FLWPUBK_TEST-…) and Secret Key (FLWSECK_TEST-…).
2. Settings → Webhooks:
   • URL: https://<your-shop-domain>/flutterwave/webhook
   • Secret hash: a long random value you make up, e.g. openssl rand -hex 32. It is not an API key.
   • Enable the events for successful charges and refunds. Save.

The domain must be configured on a Shopware sales channel — Shopware rejects requests for unknown domains with 400. Basic auth or maintenance mode in front of the shop blocks webhooks.

4. Configure the essentials

Extensions → My extensions → Flutterwave → ⋯ → Configure, on All Sales Channels, Test configuration card:

1. Enable Sandbox — on.
2. Public Key, Secret Key — the test keys. In sandbox mode the secret key must be a test key (FLWSECK_TEST-…), in live mode a live key — otherwise checkout is blocked.
3. Webhook Secret Hash — exactly the value from the dashboard.
4. Save.

Optionally set the Title and Description shown on Flutterwave's page — see Configuration.

5. Offer the payment method

1. Sales Channels → (your storefront) → General → Payment methods: add Pay with Flutterwave.
2. Rename it or add an image under Settings → Shop → Payment methods if you like (Shopware: Payment methods).

6. Verify

1. Place an order with Pay with Flutterwave and pay with a Flutterwave test card.
2. You return to the order confirmation; in the Administration the payment status is Paid and the Flutterwave tab shows the transaction.
3. Cancel test: start another payment and cancel on Flutterwave's page — the payment becomes Cancelled.
4. Webhook test: in the Flutterwave dashboard's webhook log the delivery shows 200.

If a step fails, see Troubleshooting.

7. Go live

1. Fill in Live configuration: live Public Key, Secret Key, and a new live Webhook Secret Hash.
2. In Flutterwave live mode, set the same webhook URL and the live hash.
3. Turn Enable Sandbox off.
4. Grant Process Flutterwave refunds to staff roles — Refunds.
5. Turn off Enable Detailed Logging if you used it.
6. Make and refund a small real payment.

Updating

composer update kommandhub/flutterwave-sw
bin/console plugin:refresh
bin/console plugin:update KmhFlutterwaveSW
bin/console cache:clear

ZIP installs: upload the new ZIP, then Update. Always run the update step — it re-applies the payment method and custom fields. Update only this package, not all dependencies.

Upgrading from 0.9.0-beta.1: the plugin was renamed

In 0.9.0-beta.2 the technical name changed from KommandhubFlutterwaveSW to KmhFlutterwaveSW, so Shopware treats it as a new plugin and plugin:update does not apply:

1. Uninstall the old plugin (KommandhubFlutterwaveSW).
2. Install and activate the new one: bin/console plugin:refresh, bin/console plugin:install --activate KmhFlutterwaveSW, bin/console cache:clear.
3. Re-enter the plugin settings — API keys and webhook secret hashes. They are now stored under KmhFlutterwaveSW.config.*.

The Pay with Flutterwave payment method and existing orders are kept. Bank details that customers saved under beta.1 (kommandhub_flutterwave_* fields) are not carried over and must be entered again. Several fixes in beta.2 are security-relevant, so upgrading is strongly recommended — see the changelog.

Uninstalling

Extensions → My extensions → ⋯ → Uninstall, or bin/console plugin:uninstall KmhFlutterwaveSW.

• Pay with Flutterwave is deactivated, not deleted.
• Flutterwave data on orders stays.
• Without keep plugin data, the bank-details custom fields and all saved bank details (including BVNs) are removed.