Taking payments

For merchants

The customer's journey

1. The customer selects Pay with Flutterwave and places the order; payment status Open.
2. They are redirected to Flutterwave's hosted checkout, showing your configured Title and Description.
3. They pay with an option your Flutterwave account offers — or cancel.
4. Flutterwave sends them back to a one-time return URL of your shop (/flutterwave/return/…), which forwards them into Shopware's normal payment finalization — this also works after card 3-D Secure. The plugin fetches the transaction from the Flutterwave API and checks that it belongs to this order (reference), and that the amount and currency match.
5. The payment status changes:

Flutterwave result	Payment status in Shopware	Customer sees
successful, reference, amount and currency match	Paid	Order confirmation
failed	Failed	Payment-failed page; can retry or choose another method
reference, amount or currency mismatch	Failed	Payment-failed page
cancelled on Flutterwave's page	Cancelled	Payment-failed page
any other status	stays Open (reopened)	Order confirmation; the payment settles later via webhook

When the customer does not come back

Flutterwave sends a charge.completed webhook to https://<your-shop-domain>/flutterwave/webhook. The plugin uses only the transaction ID from it and re-fetches the real status from the Flutterwave API before changing anything, so the order is settled exactly as if the customer had returned. Deliveries are de-duplicated; a transaction already Paid is left alone. A declined payment is acknowledged (200) so Flutterwave stops retrying; the transaction is marked Failed.

Charges on your Flutterwave account that did not come from this shop (other integrations, payment links) are acknowledged and ignored.

What you see on the order

The order's Flutterwave tab in the Administration (Shopware: Orders) shows: amount charged, amount settled, Flutterwave reference, transaction ID, processing fee, payment channel and method, verification time, and the refund history.

The same values are stored as order-transaction custom fields (flutterwave_reference, flutterwave_transaction_id, flutterwave_amount_charged, flutterwave_amount_settled, …). flutterwave_reference is the tx_ref — the Shopware order transaction ID.

Amounts and currencies

Flutterwave charges the amount exactly as sent, in the currency's main unit (₦100.00 is sent as 100). Comparisons are done in the smallest unit using each currency's decimal places, so zero-decimal (RWF, UGX) and three-decimal (KWD) currencies are handled exactly. Add currencies in Shopware: Currencies and enable them on your Flutterwave account.

Zero-value orders

Pay with Flutterwave is blocked for carts with a total of zero (for example fully discounted orders) — Flutterwave cannot charge nothing. Offer another payment method for those.

Paying later

The payment method allows payment after order: a customer whose payment failed or was cancelled can pay again from the order in their account.