Flutterwave API Overview
Flutterwave provides a REST API at https://api.flutterwave.com/v3. Authentication uses a secret key in the Authorization: Bearer FLWSECK-xxxxxxxx header. The API covers payments, transfers, beneficiaries, subaccounts, transactions, and identity verification. Every response includes a status field (success or error), a message field, and a data object. Rate limit is 150 requests per second per API key.
Standard Payment Flow
The standard flow has four steps: POST to /payments with transaction details, redirect the customer to the returned checkout URL, handle the callback with transaction_id and status, then verify server-side with GET /transactions/:id/verify. Never trust callback parameters alone. The hosted checkout page handles card, bank transfer, USSD, and mobile money payments.
Rave to Flutterwave Migration
If you maintain an older Rave integration, migrate to Flutterwave v3. Update your base URL from https://api.ravepay.co to https://api.flutterwave.com/v3. The charge endpoint moved to /v3/charges?type=card and verification moved to /v3/transactions/:id/verify. Plan for two weeks of development and testing.
BVN Verification for KYC
BVN verification is mandatory for CBN KYC compliance. Send a POST to /v3/bvn/verifications with the customer’s BVN number. The API returns first name, last name, phone number, date of birth, and bank registration date. Compare returned details with customer-provided information. Flutterwave also supports NIN and passport verification.
Subaccount and Split Payment Management
Create subaccounts via /v3/subaccounts with business details, settlement bank, and split percentage. Pass the subaccounts array in payment payloads to distribute funds. Flutterwave supports percentage-based and fixed-amount splits. Specify the fee bearer using the fee_bearer field.
Currency Support and Multi-Currency Handling
Flutterwave supports payments in NGN, USD, GBP, EUR, and over 30 African currencies. Specify the three-letter ISO 4217 currency code in the currency field. The API returns amounts in both requested and settlement currencies. Multi-currency wallets are supported for diaspora payments.
Transaction Status Handling
Transaction statuses include pending, successful, failed, and requires validation. Pending transactions (bank transfers, USSD) need clear user messaging. Failed reasons include insufficient funds, expired cards, and declined by issuer. Transactions requiring validation need additional steps like PIN or OTP entry.
Webhook Implementation
Configure your webhook URL in the Flutterwave dashboard. Events include charge.completed, transfer.completed, and subscription.completed. Verify the verif-hash header using HMAC-SHA256 with your configured hash. Respond with HTTP 200 and process asynchronously. Flutterwave retries with backoff up to 72 hours.
Frequently Asked Questions
How do I integrate Flutterwave into a Nigerian app?
Sign up for a Flutterwave business account, obtain your API keys, install the Flutterwave SDK, implement the standard payment flow using the Flutterwave checkout modal or direct charge API, and set up webhook URLs to handle payment callbacks.
What is the difference between Flutterwave and Rave?
Rave was Flutterwave's earlier product name. The current Flutterwave API v3 replaced Rave. Use the current v3 endpoints instead of deprecated Rave v2 endpoints.
What currencies does Flutterwave support?
Flutterwave supports payments in NGN, USD, GBP, EUR, KES, GHS, ZAR, XOF, XAF, and over 30 additional African and international currencies.
How does Flutterwave BVN verification work?
Flutterwave provides BVN verification through its identity API. You send the customer's BVN and the API returns the associated name, phone number, and date of birth for CBN KYC compliance.