How to Add Flutterwave to a Nigerian Business Website
Step-by-step guide to adding Flutterwave to your Nigerian business website — API keys, plugin setup, webhooks, test cards and fixing common errors.
Flutterwave is one of the most widely used payment gateways in Africa. It supports card payments, bank transfers, USSD, mobile money, and multiple currencies. It is especially useful for Nigerian businesses that sell to customers outside Nigeria or that want a wider range of payment methods.
This guide walks you through integrating Flutterwave on a WordPress website — including the webhook step that determines whether your orders update automatically or stay stuck on "Pending."
To add Flutterwave to your website: (1) create a Flutterwave account and complete verification, (2) get your Public and Secret API keys from the dashboard, (3) install the Flutterwave plugin for your site type (WooCommerce, Rave, or donation plugin), (4) enter your Test API keys and enable Test Mode, (5) configure the webhook URL, (6) test with a Flutterwave test card, and (7) switch to Live keys when ready.
The most common mistake is skipping the webhook — without it, orders may not update after successful payment.
Flutterwave vs Paystack: Which Should You Use?
Both are excellent Nigerian payment gateways. Most businesses can use either. Here is how they compare so you can choose the right one for your situation.
| Factor | Flutterwave | Paystack |
|---|---|---|
| Coverage | 34+ African countries | Mostly Nigeria, Ghana, Kenya, South Africa |
| Currencies | NGN, USD, GBP, EUR, KES, GHS, ZAR, and more | NGN, USD, GHS, KES, ZAR |
| Transaction fee (local) | 1.4% + ₦100 (capped at ₦2,000) | 1.5% + ₦100 (capped at ₦2,000) |
| Payment methods | Card, bank transfer, USSD, mobile money, Barter | Card, bank transfer, USSD, QR code |
| Payout speed | T+1 to T+2 (usually 1 to 2 days) | T+1 (usually next day) |
| Best for | Cross-border sales, multi-currency, international customers | Nigerian local sales, simpler checkout |
Simple rule: If your customers are mostly Nigerian, either works. If you sell to customers abroad and want to accept USD, GBP or EUR, Flutterwave is usually the better choice. Many businesses integrate both as a fallback.
If you have already read our guide on how to add Paystack to WordPress, you will find many steps here similar. The main differences are the API keys, plugin names and webhook URL.
Before You Start: What You Need
Make sure you have all of the following ready. Missing any one of these will block your integration.
- A WordPress website with admin access
- A Flutterwave account (personal or business) — sign up at flutterwave.com
- A Nigerian bank account linked to your Flutterwave account
- HTTPS (SSL certificate) active on your domain — Flutterwave requires secure endpoints
- The correct Flutterwave plugin for your site type
- Access to your Flutterwave dashboard to retrieve API keys
Which Flutterwave Plugin Do You Need?
Flutterwave offers multiple plugins depending on what you are selling. Choose the right one for your use case.
| What You Are Selling | Plugin to Use | Best For |
|---|---|---|
| Physical products (WooCommerce store) | Flutterwave WooCommerce Plugin | Online stores, boutiques, supermarkets |
| Simple payments, donations, event tickets | Flutterwave Rave Payment Forms | Simple payment pages, fundraisers, tickets |
| Digital downloads | Flutterwave Easy Digital Downloads | Ebooks, music, software, templates |
| Charity and church donations | GiveWP Flutterwave Gateway | NGOs, churches, mosques, fundraisers |
| Custom payments (developers) | Flutterwave Inline JS or Standard API | Custom integrations on any WordPress site |
For most Nigerian businesses, the WooCommerce plugin or Rave Payment Forms plugin covers 90% of use cases.
Step 1: Get Your Flutterwave API Keys
1 Log Into Your Flutterwave Dashboard
Go to dashboard.flutterwave.com and log in. If you do not have an account yet, sign up at flutterwave.com first.
2 Switch Between Test and Live Mode
At the top of your dashboard, you will see a toggle for Test Mode and Live Mode. Use Test Mode while setting up. Switch to Live Mode when you are ready for real payments.
3 Retrieve Your API Keys
Go to Settings > API Keys. You will see:
- Test Public Key (starts with FLWPUBK_TEST-)
- Test Secret Key (starts with FLWSECK_TEST-)
- Test Encryption Key (starts with FLWSECK_TEST-)
- Live Public Key (starts with FLWPUBK-)
- Live Secret Key (starts with FLWSECK-)
- Live Encryption Key (starts with FLWSECK-)
Copy the keys you need. Treat your Secret Key and Encryption Key as passwords. Never share them publicly or post them in forums.
Step 2: Install the Flutterwave Plugin
1 Log Into Your WordPress Dashboard
Go to yourdomain.com/wp-admin and log in.
2 Install the Plugin
Navigate to Plugins > Add New. In the search box, type the name of the Flutterwave plugin you identified earlier (for example, "Flutterwave WooCommerce" or "Rave Payment Forms").
Find the plugin published by Flutterwave (look for the verified blue icon). Click Install Now, then Activate.
3 (WooCommerce Users Only)
If you are using WooCommerce, ensure WooCommerce is installed and activated before Flutterwave. The Flutterwave WooCommerce plugin will not work without it.
Step 3: Configure Flutterwave Settings
The exact menu location depends on which plugin you installed. Here are the settings to configure.
For WooCommerce Users
Go to WooCommerce > Settings > Payments. Find Flutterwave and click Manage.
For Rave Payment Forms Users
Go to the Rave menu in your WordPress sidebar and click Settings.
Configure the following:
- Enable Flutterwave: Check the box so it appears at checkout
- Title: What customers see (e.g., "Pay with Card, Bank Transfer or USSD")
- Description: A short explanation of the option
- Test Mode: Enable this while testing
- Test Public Key: Paste your FLWPUBK_TEST- key
- Test Secret Key: Paste your FLWSECK_TEST- key
- Test Encryption Key: Paste your FLWSECK_TEST- encryption key
- Live Public Key, Live Secret Key, Live Encryption Key: Leave blank for now; fill in when going live
- Payment Options: Choose which payment methods to enable (Card, Bank Transfer, USSD, Mobile Money)
Step 4: Set Up the Webhook
The webhook is what tells your WordPress site when a payment has completed — even if the customer closes the browser before returning to your site. Without it, orders may stay stuck on "Pending" even after payment succeeds.
1 Copy Your Webhook URL
In your WordPress Flutterwave plugin settings, look for a Webhook URL or Secret Hash field. The exact URL format depends on the plugin. For WooCommerce, it typically looks like:
For Rave Payment Forms, the webhook is handled by the plugin and you mainly set a Secret Hash — a unique string you create (for example, your business name plus random numbers). Copy both the webhook URL and the Secret Hash if your plugin shows them.
2 Paste It in Your Flutterwave Dashboard
Go to your Flutterwave dashboard. Navigate to Settings > Webhooks. Paste the webhook URL in the Webhook URL field and the Secret Hash in the Secret Hash field. Click Save.
3 Verify the Webhook Works
After making a test purchase, check your Flutterwave dashboard for webhook logs. You should see successful deliveries for the transaction. If deliveries are failing, double-check that your site URL is correct and that HTTPS is working.
Step 5: Test in Test Mode
Never go live without testing. Flutterwave provides test cards that simulate successful and failed payments without using real money.
Common Test Cards
- Successful payment (Mastercard): 5531 8866 5214 2950, CVV 564, PIN 3310, OTP 12345
- Successful payment (Visa): 4242 4242 4242 4242, any future expiry, any CVV
- Insufficient funds: 5258 5858 5858 5858
- Declined: Use the successful card with a wrong CVV or OTP
Card numbers and test flows can change. Always check the current test cards in the Flutterwave developer documentation before testing .
What to Check After a Test Payment
- The order status in WordPress updates from Pending to Processing (WooCommerce)
- The transaction appears in your Flutterwave dashboard under Test Mode
- The webhook log shows a successful delivery
- The customer receives a confirmation email (if configured)
If the order stays on "Pending" after payment, the webhook or Secret Hash is the most likely problem. Re-check both in your plugin settings and in your Flutterwave dashboard.
Step 6: Switch to Live Mode
Once testing works, you are ready to accept real payments.
- In your WordPress plugin settings, uncheck "Test Mode".
- Paste your Live Public Key, Live Secret Key and Live Encryption Key into the corresponding fields.
- Save your changes.
- Verify Flutterwave still appears as a payment option on your checkout page.
- Make one real small transaction (for example, ₦100) to confirm everything works end-to-end.
After that first live transaction succeeds and the order status updates correctly, your Flutterwave integration is complete.
Troubleshooting Common Flutterwave Errors
These are the most common issues Nigerian WordPress users encounter with Flutterwave.
Flutterwave Not Showing at Checkout
Check three things: (1) the "Enable Flutterwave" box is ticked, (2) your API keys are entered correctly for the current mode, and (3) your store currency is supported (NGN, USD, GBP, EUR, KES, GHS, ZAR).
Order Stays "Pending" After Payment
This is usually a webhook or Secret Hash problem. Verify the Webhook URL and Secret Hash exactly match what is in your Flutterwave dashboard. Confirm your site uses HTTPS.
"Invalid Encryption Key" Error
The Encryption Key is different from the Secret Key. Copy the exact value from your Flutterwave dashboard — do not confuse the two. If you use a payment form plugin, you may not need the Encryption Key.
Payment Deducted but No Order Created
This means the webhook failed and the customer was not redirected back. Check the Flutterwave dashboard to confirm the payment. Manually mark the order as paid, and fix the webhook before the next order.
Plugin Conflict
If Flutterwave disappears after installing a caching or security plugin, temporarily deactivate the other plugin. Adjust its settings to exclude the checkout page from caching or script optimisation.
"Verification Required" Error
You cannot accept live payments until your Flutterwave account is fully verified. Complete the verification process in your dashboard: upload ID, bank details and business documents.
Mobile Money Not Showing
Mobile Money is only available in certain currencies and countries. If your store currency is NGN, Mobile Money options are limited. For USD or GHS stores, more mobile money options are available.
Outdated Plugin
If the plugin has not been updated in over 12 months, it may not work with the latest WooCommerce or WordPress. Update it, or switch to the official Flutterwave plugin.
Frequently Asked Questions
Do I need a business account to use Flutterwave on WordPress?
For live payments, yes. You need a fully verified Flutterwave business account with a linked Nigerian bank account. You can use a personal account for testing.
How much does Flutterwave charge per transaction?
For local Nigerian transactions, Flutterwave charges approximately 1.4% + ₦100, capped at ₦2,000. International transactions have different rates. Check the Flutterwave website for current fees.
Can I use Flutterwave without WooCommerce?
Yes. The Flutterwave Rave Payment Forms plugin works on any WordPress site without WooCommerce. It is ideal for donations, event tickets and single-product sales.
What is the difference between Paystack and Flutterwave?
Both are Nigerian payment gateways. Paystack focuses heavily on Nigeria and is slightly cheaper for local transactions. Flutterwave has broader African and international coverage, more currencies, and is better for cross-border sales.
Can I use both Paystack and Flutterwave on the same site?
Yes, and many businesses do. Having both gives customers a fallback option if one gateway is down. You can also direct local customers to Paystack and international customers to Flutterwave.
Does Flutterwave work for recurring payments or subscriptions?
Yes. Flutterwave supports recurring payments through its subscription API and through plugins like Paid Memberships Pro with a Flutterwave gateway.
Do I need SSL before using Flutterwave?
Yes. Flutterwave requires HTTPS on your website. Without SSL, payments may fail and webhooks will not deliver.
How long does Flutterwave verification take?
Usually 1 to 3 business days if all documents are submitted correctly. Providing accurate details (business registration, ID, bank details) speeds the process.
Can I test Flutterwave without a live account?
Yes. You can use Test Mode with test API keys on an unverified account. Live Mode requires full verification.
Need Flutterwave Set Up on Your Website?
ClickStartNG builds affordable, mobile-first WordPress websites for Nigerian businesses — starting at ₦50,000 plus ₦10,000 for domain and technical setup. We can integrate Flutterwave, Paystack, or both, with full webhook configuration and testing.
Start Your Website Project View Portfolio Ask Us a Question Get Free AuditThis article provides general information about integrating Flutterwave with WordPress. Plugin settings, test cards and Flutterwave dashboard options may change. Always refer to official Flutterwave documentation for the most current setup instructions.
