Skip to main content

​
Overview

Flutterwave provides payment processing for African currencies and international transactions. TelemanAI supports Flutterwave for subscription payments with support for multiple currencies.

​
Prerequisites

  • Flutterwave business account
  • API keys (Public and Secret)
  • Webhook secret hash

​
Configuration

​
Environment Variables

Add these variables to your .env file: 
# Flutterwave Configuration
FLW_PUBLIC_KEY=FLWPUBK-your-public-key
FLW_SECRET_KEY=FLWSECK-your-secret-key
FLW_SECRET_HASH=your-webhook-secret
FLW_CURRENCY=NGN
FLUTTERWAVE=YES
​
FLW_PUBLIC_KEY
string
required
Your Flutterwave public key for client-side operations
​
FLW_SECRET_KEY
string
required
Your Flutterwave secret key for server-side API calls
​
FLW_SECRET_HASH
string
required
Secret hash for verifying webhook signatures
​
FLW_CURRENCY
string
Default currency code (NGN, GHS, KES, UGX, ZAR, etc.)
​
FLUTTERWAVE
string
Set to YES to enable, NO to disable

​
Supported Currencies

Flutterwave supports multiple African and international currencies:
  • NGN - Nigerian Naira
  • GHS - Ghanaian Cedi
  • KES - Kenyan Shilling
  • UGX - Ugandan Shilling
  • ZAR - South African Rand
  • USD - US Dollar
  • EUR - Euro
  • GBP - British Pound

​
Setup Steps

1

Create Flutterwave Account

Sign up at flutterwave.com and complete business verification.
2

Get API Credentials

Navigate to Settings → API in your Flutterwave dashboard to retrieve your keys.
Use test keys for development. Switch to live keys only in production.
3

Configure Environment

Add the credentials to your .env file as shown above.
4

Set Up Webhooks

Configure webhook URL in Flutterwave dashboard:
https://your-domain.com/flutterwave/callback
Copy the webhook secret hash and add it to FLW_SECRET_HASH.
5

Enable Gateway

Set FLUTTERWAVE=YES and clear application cache:
php artisan config:clear
php artisan cache:clear
6

Test Payment

Make a test payment using Flutterwave test cards:
  • Card Number: 5531886652142950
  • CVV: 564
  • Expiry: 09/32
  • PIN: 3310
  • OTP: 12345

​
Payment Flow

  1. User selects subscription package
  2. Chooses Flutterwave as payment method
  3. Redirected to Flutterwave payment page
  4. Completes payment with card/mobile money
  5. Redirected back to TelemanAI
  6. Webhook verifies payment
  7. Subscription activated

​
Webhook Configuration

Flutterwave sends payment notifications to your webhook URL. The system automatically verifies webhook signatures using FLW_SECRET_HASH.

​
Webhook Events

  • charge.completed - Payment successful
  • charge.failed - Payment failed
  • charge.pending - Payment pending

​
Testing

​
Test Cards

Card NumberTypeCVVPINOTP
5531886652142950Mastercard564331012345
4187427415564246Visa828331012345

​
Test Mode

Ensure you’re using test keys during development: 
FLW_PUBLIC_KEY=FLWPUBK_TEST-your-test-key
FLW_SECRET_KEY=FLWSECK_TEST-your-test-key

​
Troubleshooting

  • Verify API keys are correct
  • Check that FLUTTERWAVE=YES in .env
  • Ensure currency code is supported
  • Clear application cache
  • Verify webhook URL is accessible publicly
  • Check webhook secret hash matches
  • Review Flutterwave webhook logs
  • Ensure HTTPS is enabled in production
  • Set FLW_CURRENCY to match your Flutterwave account
  • Ensure package prices use the same currency
  • Some currencies require account approval

​
Security Best Practices

Never expose your secret key in client-side code or commit it to version control.
  • Store keys in .env file
  • Use test keys for development
  • Verify webhook signatures
  • Enable HTTPS in production
  • Regularly rotate API keys
  • Monitor transactions for fraud

​
Mobile Money Support

Flutterwave supports mobile money payments in supported countries:
  • M-Pesa (Kenya)
  • Ghana Mobile Money
  • Uganda Mobile Money
  • Zambia Mobile Money
Mobile money is automatically available when configured with the appropriate currency.

​
Next Steps

Payment Overview

View all payment gateways

Subscription Packages

Configure pricing packages

Payment Gateways

Learn about payment processing

Stripe Integration

Alternative payment gateway

Build docs developers (and LLMs) love

Get started for freeTalk to us