Flutterwave Integration

For Coding Agents: Start Here

Before reading any examples or framework guides, you MUST read:

Agent Execution Spec

This file defines the payment safety contract and execution order that must be followed to prevent fraud and incorrect implementations. Start by identifying what you are trying to implement:

• If implementing frontend popup/redirect → read references/one-time-payments.md
• If implementing backend verification → read references/express-implementation.md or references/nextjs-implementation.md
• If implementing webhooks → read references/webhooks.md
• If implementing subscriptions → read references/subscriptions.md
• If implementing mobile money (M-Pesa, MTN, Airtel) → read references/mobile-money.md
• If implementing bank transfers/payouts → read references/bank-transfers.md
• If unsure about responsibilities or safety → read references/AGENT_EXECUTION_SPEC.md first
• If debugging issues → read references/troubleshooting.md
• If you need v3 vs v4 migration or enckey handling → read references/flutterwave-specific.md

If you are unsure about responsibilities, safety, or execution order, read: references/AGENT_EXECUTION_SPEC.md first.

Condensed Payment Safety Rules

• Generate unique tx_ref FIRST, store in DB with status=pending, THEN call Flutterwave.
• Always convert and store amounts in smallest currency unit (kobo/pesewas/cents).
• Never trust client-side success callbacks; always verify on backend.
• Webhook handlers must verify signature (verif-hash header OR HMAC-SHA256) before processing.
• Verify that the verified amount exactly matches the expected DB amount before fulfilling.
• Handle success-pending-validation status (wait for webhook confirmation).
• Ensure idempotency: if order.status == 'paid', exit immediately.

Table of Contents (all contained in ./references/)

0. Agent Execution Spec - READ FIRST
1. Quick Reference
2. Payment Flow Overview
3. Core Implementation
4. Webhook Essentials
5. Framework Guides
6. Deployment Checklist
7. Quick Troubleshooting
8. Database example
9. Local webhook testing with ngrok

Quick Reference

Environment Variables

# Backend (NEVER expose these)
FLW_SECRET_KEY=FLWSECK_TEST-xxxx   # or FLWSECK-xxxx for production
FLW_SECRET_HASH=your_webhook_hash   # Set in Dashboard → Settings → Webhooks

# Frontend (safe to expose)
FLW_PUBLIC_KEY=FLWPUBK_TEST-xxxx   # or FLWPUBK-xxxx for production

# Optional
FLW_ENCRYPTION_KEY=FLWSECK_TESTxxxx  # For direct card charges only

API Configuration

const FLW_BASE_URL = 'https://api.flutterwave.com/v3';

const headers = {
  Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`,
  'Content-Type': 'application/json',
};

tx_ref Generation (CRITICAL)

import crypto from 'crypto';

// ALWAYS generate tx_ref BEFORE calling Flutterwave
function generateTxRef(prefix = 'FLW'): string {
  const timestamp = Date.now().toString(36);
  const random = crypto.randomBytes(4).toString('hex');
  return `${prefix}_${timestamp}_${random}`.toUpperCase();
}

// Example: FLW_LK5J2M8_A1B2C3D4

Flow:

1. Generate unique tx_ref
2. Store in database with status=pending
3. Call Flutterwave /v3/payments with this tx_ref
4. Redirect user to returned link
5. Webhook events will contain this same tx_ref

Unlike Paystack, YOU generate the reference before calling the API.

Currency Units (CRITICAL)

function toSmallestUnit(amount: number): number {
  return Math.round(amount * 100);
}

Supported Payment Channels

type FlutterwaveChannel =
  | 'card'
  | 'banktransfer'
  | 'ussd'
  | 'credit'
  | 'mobilemoneyghana'
  | 'mobilemoneyuganda'
  | 'mobilemoneyrwanda'
  | 'mobilemoneyzambia'
  | 'mobilemoneytanzania'
  | 'mobilemoneyfranco'
  | 'mpesa'
  | 'barter';

Payment Flow Overview

One-Time Payment Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────▶│   Backend   │────▶│ Flutterwave │────▶│   Backend   │
│  (initiate) │     │ (initialize)│     │  (payment)  │     │  (verify)   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
      │                    │                   │                   │
      │  1. Request        │  2. POST          │  3. Pay via       │  4. GET
      │     payment        │     /v3/payments  │     hosted page   │     /v3/transactions
      │                    │                   │                   │     /:id/verify
      │                    │  Returns:         │  Returns:         │
      │                    │  link (hosted)    │  tx_ref, flw_ref  │  Returns:
      │                    │                   │  transaction_id   │  status: successful

Decision: Hosted vs Inline

Core Implementation

TypeScript Interfaces

interface FlutterwaveResponse<T> {
  status: 'success' | 'error';
  message: string;
  data: T;
}

interface InitializePaymentData {
  link: string;  // Hosted payment page URL
}

interface VerifyTransactionData {
  id: number;
  tx_ref: string;
  flw_ref: string;
  status: 'successful' | 'pending' | 'failed' | 'success-pending-validation';
  amount: number;
  currency: string;
  charged_amount: number;
  app_fee: number;
  customer: {
    id: number;
    email: string;
    name: string;
    phone_number: string;
  };
  card?: {
    first_6digits: string;
    last_4digits: string;
    type: string;
    expiry: string;
  };
  meta?: Record<string, unknown>;
  created_at: string;
}

interface WebhookEvent {
  event: string;
  data: VerifyTransactionData;
}

Initialize Transaction

interface InitializeParams {
  tx_ref: string;           // YOUR unique reference (required)
  amount: number;           // In smallest unit
  currency: string;         // NGN, GHS, KES, etc.
  redirect_url: string;     // Where to redirect after payment
  customer: {
    email: string;
    name?: string;
    phonenumber?: string;
  };
  customizations?: {
    title?: string;
    description?: string;
    logo?: string;
  };
  payment_options?: string; // Comma-separated: "card,banktransfer,ussd"
  meta?: Record<string, unknown>;
}

async function initializePayment(params: InitializeParams): Promise<string> {
  const response = await fetch(`${FLW_BASE_URL}/payments`, {
    method: 'POST',
    headers,
    body: JSON.stringify(params),
  });

  const result: FlutterwaveResponse<InitializePaymentData> = await response.json();

  if (result.status !== 'success') {
    throw new Error(result.message);
  }

  return result.data.link;  // Redirect URL
}

Verify Transaction (CRITICAL)

async function verifyTransaction(
  transactionId: number,
  expectedAmount: number,
  expectedCurrency: string
): Promise<VerifyTransactionData> {
  const response = await fetch(
    `${FLW_BASE_URL}/transactions/${transactionId}/verify`,
    { headers }
  );

  const result: FlutterwaveResponse<VerifyTransactionData> = await response.json();

  if (result.status !== 'success') {
    throw new Error(result.message);
  }

  // CRITICAL: Verify payment status
  if (result.data.status !== 'successful') {
    throw new Error(`Payment not successful: ${result.data.status}`);
  }

  // CRITICAL: Verify amount matches expected
  if (result.data.amount !== expectedAmount) {
    throw new Error(`Amount mismatch: expected ${expectedAmount}, got ${result.data.amount}`);
  }

  // CRITICAL: Verify currency matches
  if (result.data.currency !== expectedCurrency) {
    throw new Error(`Currency mismatch: expected ${expectedCurrency}, got ${result.data.currency}`);
  }

  return result.data;
}

Webhook Essentials

Webhooks notify your server of payment events. Signature verification is mandatory for security.

Webhook Verification (Two Methods)

Method 1: Simple verif-hash (Recommended)

function handleWebhook(req: Request): Response {
  const signature = req.headers.get('verif-hash');
  const secretHash = process.env.FLW_SECRET_HASH;

  if (!signature || signature !== secretHash) {
    return new Response('Invalid signature', { status: 401 });
  }

  const event: WebhookEvent = await req.json();
  await processWebhookEvent(event);
  return new Response('OK', { status: 200 });
}

Method 2: HMAC-SHA256 (More Secure)

import crypto from 'crypto';

function verifyFlutterwaveSignature(
  payload: string,
  signature: string,
  secretHash: string
): boolean {
  const hash = crypto
    .createHmac('sha256', secretHash)
    .update(payload)
    .digest('base64');

  // Use timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(hash),
      Buffer.from(signature)
    );
  } catch {
    return false;
  }
}

Key Webhook Events

Idempotency

async function processWebhookEvent(event: WebhookEvent): Promise<void> {
  const txRef = event.data.tx_ref;

  // Check if already processed
  const order = await db.orders.findUnique({ where: { txRef } });

  if (!order) {
    console.log(`Order not found for tx_ref: ${txRef}`);
    return;
  }

  if (order.status === 'paid') {
    console.log(`Order ${txRef} already paid, skipping`);
    return;
  }

  // Process based on event type
  if (event.event === 'charge.completed' && event.data.status === 'successful') {
    await fulfillOrder(order, event.data);
  }
}

See references/webhooks.md for complete event handling patterns.

Framework Guides

Next.js (App Router)

Recommended file structure:

app/api/flutterwave/
├── initialize/route.ts    # POST - Initialize payment
├── verify/route.ts        # GET - Verify payment
└── webhook/route.ts       # POST - Handle webhooks
components/
└── FlutterwaveButton.tsx  # Client component
lib/
└── flutterwave.ts         # Utility functions

See references/nextjs-implementation.md for complete implementation.

Express.js

Recommended structure:

routes/
└── flutterwave.routes.ts
controllers/
└── flutterwave.controller.ts
middleware/
└── flutterwave.middleware.ts  # Signature verification
services/
└── flutterwave.service.ts     # API calls

See references/express-implementation.md for complete implementation.

Deployment Checklist

Before Going Live

• Environment Variables

  • FLW_SECRET_KEY set (FLWSECK-xxxx for production)
  • FLW_PUBLIC_KEY set (FLWPUBK-xxxx for production)
  • FLW_SECRET_HASH set (from Dashboard)
  • Keys not committed to version control

• Webhook Configuration

  • Webhook URL configured in Flutterwave Dashboard
  • HTTPS endpoint (required for production)
  • Signature verification implemented
  • Return 200 OK within 30 seconds

• Payment Verification

  • Amount verification implemented
  • Currency verification implemented
  • Status check implemented (only process successful)
  • Handle success-pending-validation status
  • Idempotency for webhook handling

• Testing

  • Test with Flutterwave test cards
  • Test mobile money flows
  • Test webhook with ngrok (local)
  • Test failed payment scenarios

Test Cards

Test Mobile Money

• Phone: 0551234987 (Ghana)
• OTP: 123456

Quick Troubleshooting

Common Errors

Debug Checklist

1. API calls failing?

   • Check Authorization header format: Bearer FLWSECK-xxx
   • Verify base URL: https://api.flutterwave.com/v3
   • Check test vs live keys match environment

2. Webhook not received?

   • Verify URL is publicly accessible (HTTPS)
   • Check Flutterwave Dashboard for delivery logs
   • Ensure you return 200 OK quickly

3. Status issues?

   • Handle success-pending-validation status
   • Poll for status or wait for webhook

See references/troubleshooting.md for comprehensive debugging guide.

Official Documentation

• Flutterwave API Reference
• Standard Payments
• Webhooks Guide
• Mobile Money
• Bank Transfers
• Test Cards