Flutterwave

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Supported input

Notification delivery

• Repeated deliveries are recognized by event, data.id and data.status for v3 webhooks (Flutterwave's own suggestion; v3 has no event or delivery id); webhook_id (or id) for v4 webhooks; Flutterwave documents that notifications can be delivered more than once.
• Delivery order: not documented by the provider.
• Flutterwave may send the same webhook more than once and retries (when enabled) 3 times, 30 minutes apart. Make the handler idempotent on the event, transaction id and status, and verify the transaction (GET /transactions/{id}/verify) or the transfer before giving value.

Known limitations

• The v3 payment error table is an embedded view that could not be read. v3 errors and declines are decoded only from documented message texts (27 error messages, 3 failure processor_response values, 6 transfer complete_message values and 8 card velocity trigger errors), case-insensitively and by prefix where the message has variable text. Any other text is shown as received, with an unknown category.
• v3 data.status values are not enumerated by Flutterwave. Only successful, failed, pending, success-pending-validation and pending-capture are interpreted; other values are shown as unknown. The envelope status (success or error) is about the API call, not the payment.
• A v3 refund with status completed has been initiated and is waiting for disbursement; it is shown as pending. Only the completed-* statuses are shown as finished. A disburse_status in the refund webhook meta is shown but not interpreted.
• A v3 void response reports status successful; it is shown as a void (not a payment success) only when processor_response says Charge voided.
• Mobile money, bank transfer, USSD, QR and similar flows stay pending until a later webhook or verify response shows the final state.
• v3 webhooks have no event or delivery id. Repeated deliveries are recognized by event, data.id and data.status, as Flutterwave suggests; the v3 refund webhook has no event key and gets no delivery key.
• v3 objects carry only their creation time (created_at). It is used as the event time, so several states of one transaction share one time and keep the order of the input. Webhook delivery order is not documented.
• v3 transfer.completed also reports wallet funding and payout sub-account inflows (narration WALLET FUNDING or debit_currency PSA); those are shown as stage other, not as payouts. Transfer retries get a new id and the reference <original>_RETRY_<n>; retries are linked to the original by that reference.
• v3 chargeback webhooks link to the charge only through flw_ref. Refund webhooks link through TransactionId. v3 numeric ids and v4 prefixed ids cannot be linked to each other.
• v4 error codes are decoded by the pair error.code and error.type, because v4 reuses numbers across tables (for example 301404 and 209400 have two meanings each). A code whose type is missing or unknown is decoded with possible confidence only when it has a single meaning.
• v4 card processor_response is decoded by its type; the timeout example uses type pending with code 02, outside the documented list, so a code alone is never trusted. The v4 payout provider_response type invalid_wallet_currency has no documented meaning.
• v4 webhook ids are documented as webhook_id (schema) and id (webhooks page); both are read. Whether a retried v4 webhook keeps its id is not documented. The payload of order.authorization is not documented and is shown without interpretation; v4 chargeback webhooks are not documented.
• Signatures are never verified or copied: the v3 verif-hash header carries the merchant's secret hash itself and the v4 flutterwave-signature header is an HMAC of the body. A pasted webhook is never treated as authentic.
• Customer, card, bank and device fields (names, e-mail addresses, phone numbers, card digits and tokens, account numbers, IP addresses, device fingerprints, narration, redirect URLs, merchant account ids) are never copied.
• v3 HTML error pages, the v3 transaction events timeline, redirect query parameters, non-payment v3 webhooks (subscription, BVN, bill payment, tokenization, quote), virtual card notifications and the v2 API are not analyzed.
• Category and retry guidance per code or message are PandaPayLens suggestions; where Flutterwave gives advice (verify before retrying after a timeout, do not retry failed card charges automatically) it is reflected.

Examples

• Flutterwave: refund initiated, then completed: A refund reported as completed that is only initiated until the refund webhook confirms it.
• Flutterwave: preauthorization voided: A held payment that is voided; the void is not shown as a payment success.

Provider documentation

• v3 common errors
• v3 handling error timeouts
• v3 webhooks
• v3 transaction verification
• v3 direct card charge
• v3 preauthorization
• v3 refunds
• v3 chargebacks
• v3 transfers
• v3 testing
• v4 errors and code tables
• v4 webhooks
• v4 charge schema
• v4 transfer schema
• v4 testing and issuer responses

PandaPayLens is not affiliated with Flutterwave. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.