How to Integrate Flutterwave: A Developer's Guide for Nigeria

Flutterwave is Nigeria's other major payment processing platform. While Paystack is the most popular for Nigerian-only products, Flutterwave shines for products that accept payments across multiple African countries. Many Nigerian companies use both.

Step 1: Create a Flutterwave account. Go to flutterwave.com and sign up. Complete the KYC verification process (BVN, business details) for live transactions. Test mode is available immediately.

Step 2: Get your API keys. In your Flutterwave dashboard, go to Settings, then API. You will find your public key, secret key, and encryption key. The encryption key is unique to Flutterwave and is used for certain direct charge operations. Store all keys securely. Never expose secret or encryption keys in client-side code.

Step 3: Understand the flow. Flutterwave's Standard payment flow works like this: your backend sends a payment request to Flutterwave's API, receives a payment link, redirects the user to that link, the user pays, Flutterwave redirects back to your site, and your backend verifies the payment. Alternatively, use the Inline checkout to embed Flutterwave's payment interface as a popup on your page.

The developer documentation is at developer.flutterwave.com. It is comprehensive and includes code examples for multiple languages.

Standard Payment (Redirect): Send a POST request to https://api.flutterwave.com/v3/payments with your transaction details. Required fields include tx_ref (your unique transaction reference), amount, currency (NGN for Nigeria), redirect_url (where to send the user after payment), and customer details (email, name). Flutterwave returns a link that you redirect the user to.

Inline Payment (Popup): Include the Flutterwave inline JavaScript library in your HTML. Call FlutterwaveCheckout() with your public key, transaction reference, amount, currency, customer details, and callback function. The checkout opens as a popup on your page without redirecting.

Key difference from Paystack: Flutterwave amounts are in the main currency unit (NGN), not the smallest unit. To charge NGN 5,000, you send 5000, not 500000. This is the opposite of Paystack's kobo-based amounts. This discrepancy is a common source of bugs for developers who switch between the two platforms.

Payment methods: Flutterwave supports cards (Visa, Mastercard, Verve), bank transfers, USSD, mobile money (for other African countries), and more. You can restrict available methods using the payment_options parameter. For Nigerian customers, card, banktransfer, and ussd cover the primary use cases.

After payment, verify the transaction on your backend. This is as critical in Flutterwave as it is in Paystack. Never trust client-side confirmation alone.

Endpoint: GET https://api.flutterwave.com/v3/transactions/:id/verify

Authentication: Include your secret key in the Authorization header as "Bearer FLWSECK-your_key".

What to verify: Check that the status is "successful," the amount matches what you expected, the currency matches, and the tx_ref matches your original transaction reference. If any of these do not match, do not fulfill the order.

Getting the transaction ID: After the redirect, the transaction ID is included in the redirect URL parameters. In the inline popup, it is available in the callback response. You can also use the tx_ref to verify by querying Flutterwave's transaction list endpoint filtered by your reference.

Idempotency: Same as with Paystack, ensure your fulfillment logic handles duplicate verification requests. If a user refreshes the redirect page, your server should recognize that the transaction has already been processed and not duplicate the order.

Flutterwave sends webhooks to notify your server about payment events. Configure your webhook URL in the Flutterwave dashboard under Settings, then Webhooks.

Webhook verification: Flutterwave uses a secret hash for webhook verification. You set this hash in your dashboard. When Flutterwave sends a webhook, it includes a verif-hash header. Compare this header value to your secret hash. If they match, the webhook is genuine. If not, reject it.

Note on verification method: This is different from Paystack's HMAC signature verification. Flutterwave uses a shared secret comparison, while Paystack uses HMAC SHA-512 of the request body. If you support both gateways, implement both verification methods.

Important events: The most critical webhook event is charge.completed, which fires when a payment succeeds. Handle this event to update your order status, send confirmation emails, and trigger any post-payment logic.

Best practice: Return a 200 status code immediately upon receiving the webhook, then process it asynchronously. If your server is slow to respond, Flutterwave will retry, potentially causing duplicate processing. Log all webhook events for debugging and auditing.

If you already know Paystack, here are the key differences to keep in mind when working with Flutterwave.

Amount format: Flutterwave uses main currency units (NGN 5,000 = 5000). Paystack uses the smallest unit (NGN 5,000 = 500000 kobo). This catches developers who switch between them.

Webhook verification: Flutterwave uses a shared secret hash. Paystack uses HMAC SHA-512 signature verification. Both serve the same purpose but are implemented differently.

Multi-country support: Flutterwave supports over 30 African countries. Paystack has been expanding but historically focused on Nigeria, Ghana, South Africa, and Kenya. If your product needs to collect payments in multiple African countries, Flutterwave may give you broader coverage.

API structure: Both are REST APIs with JSON request/response formats. The endpoint URLs, field names, and response structures differ, but the overall architecture is the same. A developer comfortable with one can integrate the other in a day.

For a detailed side-by-side comparison, read our Paystack vs Flutterwave comparison.

The best way to learn is by building. Create a simple project (a product checkout page or a donation form), integrate Flutterwave using test keys, and walk through the complete flow: initialize, pay, verify, handle webhook.

Start with the Flutterwave developer documentation at developer.flutterwave.com. Their quickstart guides walk through the integration step by step with code examples.

Once you have both Paystack and Flutterwave in your portfolio, you cover the two major Nigerian payment gateways. This combination makes you immediately relevant for the majority of Nigerian fintech and e-commerce projects.

For a structured learning path that includes payment integration architecture, McTaba's Full-Stack Software and AI Engineering course (KES 120,000, roughly NGN 140,000 to 220,000; exchange rates fluctuate, check current price at checkout) covers the foundational patterns. McTaba accepts NGN and card payments via Paystack. The webhook handling, verification, and idempotency patterns you learn apply to both Paystack and Flutterwave.