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"}}'

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.
• 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, 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)
POST /flutterwave/bank/verify	Resolve an account number (XHR)
POST /flutterwave/bank/save	Validate and store the details on the customer