Getting started

The package gives your Laravel app the whole Flutterwave v3 API behind one facade, plus a webhook route, Laravel events, artisan commands and frontend components.

Prefer a printable checklist?

The developer quickstart covers install, setup, a test payment, going live and troubleshooting in one document. Download the PDF (16 pages, A4) or open it in your browser.

Requirements

• PHP 8.1 or newer
• Laravel 9, 10, 11, 12 or 13
• A Flutterwave account. Test keys are on the dashboard under Settings > API keys.

Install

composer require abraham-flutterwave/laravel-payment

Laravel discovers the service provider and the Flutterwave facade on its own. Then run the installer:

php artisan flutterwave:install

It publishes config/flutterwave.php, adds the FLW_* keys to your .env, and prints the webhook URL to paste into your dashboard. Add a flag for anything else you need:

Flag	Publishes
--react, --vue or --svelte	Inertia components to resources/js/components/flutterwave (guide)
--billable	A migration for saving customers' cards (guide)
--force	Overwrites files you already published

Add your keys

Use the builder below, or fill the keys in by hand. The secret hash is any long random string: type the same value into Settings > Webhooks > Secret hash on the dashboard.

.env builder

Pick your settings and copy the block into .env. Nothing you type leaves this page, and defaults are left out so your file stays short.

Keys

Business nameDefault countryNGGHKEUGTZZARWCMCIZMUSGBDefault currencyNGNGHSKESUGXTZSZARRWFXAFXOFZMWUSDEURGBPTransaction prefixWebhook pathDashboard URL: https://your-app.com/flutterwave/webhookWebhook queueDedupe cache storeEmail on chargebackEmail on failed payout

Checksum on every checkout

.env

# Settings > API keys on the Flutterwave dashboard
FLW_PUBLIC_KEY=FLWPUBK_TEST-xxxxxxxx-X
FLW_SECRET_KEY=FLWSECK_TEST-xxxxxxxx-X
FLW_ENCRYPTION_KEY=FLWSECK_TESTxxxxxxxx

# The same value you type into Settings > Webhooks > Secret hash
FLW_SECRET_HASH=choose-a-long-random-string
FLW_ENVIRONMENT=staging

Test and live keys

Test keys contain _TEST. Keep both keys from the same mode, or flutterwave:doctor will flag it.

Check your setup

php artisan flutterwave:doctor

The doctor checks your keys, the webhook secret hash and URL, the cache used to dedupe webhooks, the webhook queue, the admin routes and, unless you pass --offline, that Flutterwave accepts your secret key.

Take a test payment

From the terminal:

php artisan flutterwave:pay customer@example.com 5000 --open

Or from a controller:

use Flutterwave\Payments\Facades\Flutterwave;

Route::post('/pay', fn () => Flutterwave::redirect([
    'amount' => 5000,
    'email' => auth()->user()->email,
]));

Pay with one of Flutterwave's test cards (see Testing in the Flutterwave docs), then head to Verifying payments to confirm it on your server.

Next steps

• Checkout: hosted page, inline modal and Inertia
• Webhooks: react to payments with Laravel events
• Service explorer: everything else the package can do