HTTP endpoints & webhooks

For developers

POST /flutterwave/webhook

Scope	Storefront (no Shopware authentication)
Authentication	verif-hash header equal to the configured Webhook Secret Hash for the active mode
Handled events	charge.completed, refund.completed

Status	Body	When
200	{"status":"success"}	Handled, deduplicated, or an event type the plugin ignores
400	{"status":"error","message":"Bad request"}	Malformed body
403	{"status":"error","message":"Access denied"}	Missing or wrong verif-hash, or no hash configured
500	{"status":"error","message":"Internal server error"}	Unexpected failure; Flutterwave retries

curl -i https://shop.example.com/flutterwave/webhook \
  -H "Content-Type: application/json" \
  -H "verif-hash: $FLW_TEST_SECRET_HASH" \
  -d '{"event":"charge.completed","data":{"id":123456,"tx_ref":"0190f5b2c8f47c2a9d3a1b2c3d4e5f60"}}'

GET /flutterwave/return/{orderTransactionId}/{nonce}

The redirect_url sent to Flutterwave. Storefront scope, no authentication. The nonce is generated per payment attempt and compared with hash_equals; an unknown transaction or wrong nonce answers 404. On success it redirects to Shopware's payment-finalize URL, forwarding status and transaction_id (also read from the JSON response query parameter Flutterwave uses after 3-D Secure). Not meant to be called directly.

POST /api/_action/flutterwave/refund

Scope	Admin API (Bearer token)
Permission	flutterwave.refund

Request body:

Field	Required	Description
orderTransactionId	yes	Shopware order transaction ID
amount	no	Main-unit amount in the order currency. Omit to refund the whole remaining balance.
comments	no	Passed to Flutterwave

Responses:

• 200 — Flutterwave's refund response. A pending Shopware refund has been created — or completed right away if Flutterwave already reports the refund completed.
• 400 — {"error": "<message>"}, for example Order transaction id is required, Refundable transaction not found, Refund feature is currently disabled, Transaction is not in a refundable state, This transaction has no Flutterwave transaction id and cannot be refunded, Unable to resolve the order currency for this transaction, Refund amount must be a positive number, Refund amount must be at least …, Refund amount exceeds the refundable balance of …, Unable to verify the refundable balance. Please try again., or Flutterwave's message.
• 403 — missing permission.

Storefront bank-details routes

Only when Enable Bank Data Collection is on, only for logged-in customers.

Method & path	Purpose
GET /flutterwave/bank/list	Banks for the configured Bank Country (XHR). 404 when the feature is off, 502 when Flutterwave cannot be reached.
POST /flutterwave/bank/verify	Resolve an account number (XHR; body account_number, bank_code). Rate limited to 10 requests per customer per hour (429); 400 on failed resolution, 502 when the service is unavailable. The verified account is remembered in the session.
POST /flutterwave/bank/save	Validate and store the details on the customer. Only an account verified in the same session is saved, with the name Flutterwave returned. Form post; redirects to the profile page with a flash message.