Flutterwave Standard — setup and reference

Module and release scope

This guide covers Flutterwave Standard 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Sandbox, live = Live
secret_key — V3 secret API key	secret	Yes	Use the account-specific value described below.
webhook_secret — Webhook secret hash	secret	Yes	Use the secret hash configured in Flutterwave V3 webhook settings (verif-hash header).
currencies — Approved invoice currencies	text	Yes	Comma-separated currencies approved for this merchant. No currency conversion is performed.

Creates a Flutterwave Standard hosted payment link using the V3 API. Supported two-decimal invoice currencies: NGN, USD, EUR, GBP, AUD, CAD, ZAR, KES, GHS, TZS and MWK. Configure only currencies and collection methods Flutterwave has approved for your merchant country. Zero-decimal currencies are intentionally excluded from this version.

Configure

1. Obtain a V3 secret key from the appropriate Flutterwave dashboard environment. This module uses FLWSECK_TEST- keys in sandbox and V3 live secret keys in live mode; V4 OAuth credentials do not work here.
2. Grant hosted payment creation and transaction list/verification and refund-read access. Test makes an authenticated GET /v3/transactions for a future date range. It creates no payment and discards transaction data.
3. Under Settings → Webhooks, enter the exact saved connection callback URL and choose a strong secret hash. Copy that exact value to Webhook secret hash. Enable charge completion notifications (charge.completed). This is the documented V3 verif-hash shared-secret header, not the V4 flutterwave-signature scheme. Because that header does not sign the body, every notification is independently verified by an authenticated transaction query before it can settle an invoice.
4. Enter approved invoice currencies, run Test and enable the connection after a sandbox payment and webhook check. API requests use api.flutterwave.com/v3; hosted redirects use checkout.flutterwave.com (legacy sandbox ravesandboxapi.flutterwave.com is allowed only in sandbox).

The transaction must be successful with the exact merchant reference, application metadata, invoice amount and currency. Pending, failed, partial and reported-refunded payments remain unpaid. Standard return status is never settlement evidence. This module does not use V4 or collect card details.

Installation and activation

The package contains generic product code only. Installation leaves the module disabled and does not create, enable or populate a merchant account. In System → Payments → Provider library, enable the module only when ready, add a connection, enter your own credentials, run Test and explicitly enable that connection. Keep sandbox and live accounts separate. Existing enabled gateways are unaffected.

Use the exact HTTPS webhook URL displayed on that saved connection; do not enter the storefront home page. One connection endpoint can serve invoices across storefront domains because payment attempts retain their connection and invoice identity. Keep it reachable without login or a browser challenge. Return URLs are generated and signed by the application per invoice; do not replace them with a static merchant callback.

The module never collects PAN, CVV or customer wallet credentials. Checkout creation is submitted once, with a unique attempt reference; a timeout requires reconciliation, not an automatic second charge. Browser success parameters never prove payment. Final amount, currency, checkout identity and application metadata are checked against authenticated provider reads. Notifications use stable payment IDs for duplicate protection. A partial or ambiguous payment stays under billing review.

No currency conversion is performed. Only the listed two-decimal invoice currencies are accepted, and only those explicitly entered under Approved invoice currencies are offered. Availability of cards, wallets and local methods remains subject to the merchant account, shopper location and provider checkout; installing a module does not enable provider payment products. Refund creation, recurring billing and token charging operations are not implemented. A read-only refund query prevents a previously refunded transaction from being newly allocated; any refund record keeps the checkout under billing review.

Validation

Run php tests/gateway-growth.php for isolated HTTP fixtures covering checkout creation, server verification, signed notifications, exact amounts, identity mismatches, invalid URLs, incomplete billing profiles and no checkout POST retries. These checks do not certify credentials, merchant underwriting or a live payment. Complete a provider sandbox checkout and callback test before enabling live traffic.

Official implementation references

Reviewed 2026-10-21. Provider contracts may change; recheck these sources before changing API versions.

• https://developer.flutterwave.com/docs/flutterwave-standard-1
• https://developer.flutterwave.com/reference/verify-transaction-with-tx_ref
• https://developer.flutterwave.com/reference/get-all-transactions
• https://developer.flutterwave.com/v3.0.0/docs/webhooks
• https://developer.flutterwave.com/reference/get-all-refunds