flutterwave-integration

# 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

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

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

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

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

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

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   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

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;
}

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
}

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;
}

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 });
}

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;
  }
}

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);
  }
}

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

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