ABA Editorial · Aug 1, 2025 · 12 min read
Flutterwave is one of the most widely used payment infrastructure providers in Africa, supporting cards, bank transfers, mobile money, USSD, and bank account payouts across multiple African countries. This guide walks through the practical integration path for Flutterwave v3: dashboard registration, API key management, the Standard Checkout flow, transaction verification, webhook handling, and the transition from test to live mode. Written for engineering teams building their first Flutterwave integration.
If you are building a product that accepts payments from customers in Nigeria, Ghana, Kenya, South Africa, Uganda, Rwanda, Tanzania, Zambia, or several other African countries, Flutterwave is one of the two or three payment infrastructure providers you will probably consider. The Flutterwave API supports cards (local and international), bank transfers, mobile money, USSD, Apple Pay, Google Pay, and payouts to bank accounts, all through a single integration layer. This guide walks through the practical steps to get from zero to a working test integration using Flutterwave v3, which is the current production API as of early 2026. Flutterwave has announced a v4 API in public beta, but v3 remains the stable production path for most new integrations. This guide is written for engineering teams approaching Flutterwave for the first time.
Start by creating a free Flutterwave account on the Flutterwave dashboard. Once registered, make sure you are in test mode. The mode toggle is visible in the sidebar of the settings page, and the distinction matters: test mode lets you simulate payment flows without real money, while live mode handles actual customer transactions. Switching between modes also switches the API keys shown.
Under Settings, find the API Keys section. Flutterwave issues three types of keys when you create an account: a Public Key (safe for client-side use, for example in a browser-side Flutterwave Inline integration), a Secret Key (grants full access to your account, use it only in secure server-side environments, never expose it publicly), and an Encryption Key (required for encrypting payloads when using direct card charge endpoints). Test keys always have the prefix _TEST, for example FLWPUBK_TEST-32193bba8dab..., which is a useful sanity check when you are debugging authentication issues.
Copy the three keys into environment variables in your application (FLW_PUBLIC_KEY, FLW_SECRET_KEY, FLW_ENCRYPTION_KEY). Do not commit these to version control.
For most first-time integrations, Standard Checkout is the right choice. Standard Checkout generates a Flutterwave-hosted payment page that handles card input, 3D Secure authentication, mobile money flows, bank transfer flows, and everything else through a single URL. Your application redirects the customer to that URL, the customer completes payment on the hosted page, and Flutterwave redirects the customer back to a URL you specify with the transaction result. This approach offloads almost all PCI compliance concerns to Flutterwave.
Direct Card Charge, by contrast, lets your application collect card details directly and submit them to Flutterwave over an encrypted payload. This gives you more control over the user experience but requires your application to handle PCI DSS compliance for card data. Unless you have a specific reason to build your own checkout UI and have the compliance capacity to handle card data responsibly, start with Standard Checkout.
The Standard Checkout endpoint is POST /v3/payments on the base URL api.flutterwave.com. You send a JSON payload with your transaction details (reference, amount, currency, customer email, customer phone, redirect URL, payment options, customizations for the branded checkout page) and your Secret Key in an HTTP Bearer Authorization header. The response contains a checkout URL, and your application redirects the customer to that URL.
The critical field to pay attention to is the transaction reference. This must be unique for each payment attempt. Many integration problems come from applications reusing a reference for a retried transaction, which Flutterwave rejects. Generate a new UUID or timestamped reference for every payment attempt rather than reusing one.
Flutterwave provides official SDKs for Node.js, Python, PHP, Ruby, Go, and Java that handle the header construction and payload serialization. If you are working in one of these languages, use the SDK rather than building raw HTTP calls. The flutterwave-node-v3 npm package is a common starting point for JavaScript backends and handles collections (card, account, mobile money, bank transfers, USSD), payouts, recurring payments, refunds, chargebacks, and identity verification helpers.
The most common security mistake in Flutterwave integrations is relying solely on the redirect URL parameters to determine whether a payment succeeded. A customer or an attacker can tamper with the redirect URL. The correct approach is that after the redirect, your application must call the Flutterwave transaction verification endpoint to confirm the transaction status server-side using your Secret Key.
The verification endpoint is GET /v3/transactions/{id}/verify, where {id} is the Flutterwave transaction ID returned in the redirect. Check that the response contains a status of "successful," that the amount matches what you expected the customer to pay, that the currency matches, and that the transaction reference matches the one you generated. Only after all four checks pass should your application deliver value (mark an order as paid, ship a product, grant access to a subscription).
Webhooks are Flutterwave's mechanism for notifying your server when transactions settle asynchronously, particularly for bank transfer and USSD flows that may complete minutes or hours after the customer starts the payment. Configure your webhook URL in the Flutterwave dashboard under Settings, and add a secret hash that Flutterwave will send in the verif-hash header of every webhook request. Your webhook handler must verify that incoming requests carry the expected hash before processing them; without this check, any attacker can send fake webhook events to your endpoint.
Webhook handlers should be idempotent, return a 200 status code quickly (do your processing after acknowledging receipt), and handle retries gracefully because Flutterwave will retry failed webhook deliveries several times.
Flutterwave provides test card numbers, test bank accounts, and test mobile money credentials that let you simulate successful transactions, failed transactions, 3D Secure challenges, insufficient funds errors, and other edge cases. Test every scenario your application needs to handle before switching to live mode. Common scenarios to test: successful card payment, declined card, 3D Secure authentication success and failure, bank transfer with delayed settlement, mobile money flow, refunds, chargebacks, and webhook delivery reliability.
When you are ready to go live, switch the mode toggle in your dashboard, update your application's environment variables with the live API keys (which will not have the _TEST prefix), and run a small live transaction as a final verification before opening the integration to real customers.
Flutterwave integration is well-documented but benefits from experienced guidance, particularly around webhook reliability, transaction reconciliation, and multi-currency settlement. ABA's Solutions & Services marketplace includes Flutterwave integration specialists, pan-African payment infrastructure consultants, and fintech engineering firms with production Flutterwave experience across multiple African markets.
Important notice: This guide is provided as general information and orientation only. It is not legal, regulatory, technical, or financial advice. API specifications, endpoint structures, authentication flows, and pricing change regularly, and Flutterwave's official documentation at developer.flutterwave.com should always be treated as the authoritative source. Before implementing a production integration, readers should consult the current official Flutterwave documentation and qualified integration professionals. Need verified guidance or hands-on support? ABA's Solutions & Services marketplace connects businesses with vetted professional services providers across Africa, including Flutterwave integration specialists and pan-African payment infrastructure consultants. ABA and its contributors accept no liability for actions taken on the basis of this guide.