PAYMENT INTEGRATION • NIGERIA

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.

You want to accept payments online — and Paystack is not your only option.

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."

Quick answer:

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
Important: Live payments require a fully verified Flutterwave account. Verification typically takes 1 to 3 business days and requires a valid ID, business registration (if business account) and bank details.

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)
Currency note: Flutterwave supports NGN, USD, GBP, EUR, KES, GHS, ZAR, and more. Your WooCommerce or plugin currency must be set to one of these. If your store currency is unsupported, Flutterwave will not appear at checkout.

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:

https://yourdomain.com/?wc-api=WC_Gateway_Flutterwave

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.

  1. In your WordPress plugin settings, uncheck "Test Mode".
  2. Paste your Live Public Key, Live Secret Key and Live Encryption Key into the corresponding fields.
  3. Save your changes.
  4. Verify Flutterwave still appears as a payment option on your checkout page.
  5. 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 Audit

This 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.

Ready to build your website? See packages and get a free mockup →