Learning Objectives

Display wallet balance and history
Implement wallet funding flow
Transaction history with filtering
Withdrawal functionality

1. Wallet Database Schema

Before implementing the wallet functionality, we need to set up the database schema. The wallet system consists of two main tables: one for storing wallet information (balance, currency, owner) and another for recording all transactions that affect the wallet balance.

The wallet_transactions table uses a balance_before and balance_after pattern, which provides an audit trail and makes it easy to verify that transactions were applied correctly. The JSONB metadata field allows storing additional transaction-specific data without schema changes.

-- Wallet table
CREATE TABLE wallets (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  balance DECIMAL(12, 2) DEFAULT 0.00,
  currency VARCHAR(3) DEFAULT 'NGN',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_id)
);

-- Wallet transactions table
CREATE TABLE wallet_transactions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  wallet_id UUID REFERENCES wallets(id) ON DELETE CASCADE,
  type VARCHAR(20) NOT NULL, -- 'credit', 'debit'
  category VARCHAR(50) NOT NULL, -- 'funding', 'purchase', 'withdrawal', 'refund'
  amount DECIMAL(12, 2) NOT NULL,
  balance_before DECIMAL(12, 2) NOT NULL,
  balance_after DECIMAL(12, 2) NOT NULL,
  description TEXT,
  reference VARCHAR(100) UNIQUE,
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes
CREATE INDEX idx_wallet_transactions_wallet_id ON wallet_transactions(wallet_id);
CREATE INDEX idx_wallet_transactions_created_at ON wallet_transactions(created_at DESC);

2. Wallet Page

The wallet page serves as the main hub for all wallet-related activities. It's a server component that uses React Suspense to show loading states while async components fetch their data independently.

This layout pattern separates the wallet overview (balance and action buttons) from the transaction history, allowing each section to load and display as soon as its data is available.

// app/(dashboard)/wallet/page.tsx
import { Suspense } from 'react'
import { getWallet, getWalletTransactions } from '@/lib/data'
import WalletOverview from '@/components/wallet/WalletOverview'
import WalletTransactions from '@/components/wallet/WalletTransactions'
import { CardSkeleton, TableSkeleton } from '@/components/skeletons'

export default function WalletPage() {
  return (
    <div className="space-y-6">
      <h1 className="text-2xl font-bold">My Wallet</h1>

      <Suspense fallback={<CardSkeleton />}>
        <WalletOverview />
      </Suspense>

      <div>
        <h2 className="text-lg font-semibold mb-4">Transaction History</h2>
        <Suspense fallback={<TableSkeleton rows={10} />}>
          <WalletTransactions />
        </Suspense>
      </div>
    </div>
  )
}

3. Wallet Overview Component

The WalletOverview component displays the user's current balance along with summary statistics. It uses Promise.all to fetch the wallet and stats data in parallel, improving performance by making concurrent requests instead of sequential ones.

The component renders a gradient card with the main balance and action buttons, alongside smaller stat cards showing total funded, spent, and withdrawn amounts. This gives users a complete picture of their wallet activity at a glance.

// components/wallet/WalletOverview.tsx
import { getWallet, getWalletStats } from '@/lib/data'
import { formatCurrency } from '@/lib/utils'
import Link from 'next/link'

export default async function WalletOverview() {
  const [wallet, stats] = await Promise.all([
    getWallet(),
    getWalletStats(),
  ])

  return (
    <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
      {/* Main Balance Card */}
      <div className="lg:col-span-2 bg-gradient-to-r from-primary to-primary-dark rounded-2xl p-8 text-white">
        <p className="text-white/80">Available Balance</p>
        <p className="text-5xl font-bold mt-2">
          {formatCurrency(wallet.balance)}
        </p>

        <div className="flex gap-4 mt-8">
          <Link
            href="/wallet/fund"
            className="flex-1 py-4 bg-white text-primary font-semibold rounded-xl text-center hover:bg-white/90 transition"
          >
            Add Money
          </Link>
          <Link
            href="/wallet/withdraw"
            className="flex-1 py-4 bg-white/20 text-white font-semibold rounded-xl text-center hover:bg-white/30 transition"
          >
            Withdraw
          </Link>
        </div>
      </div>

      {/* Stats Cards */}
      <div className="space-y-4">
        <div className="bg-white rounded-xl p-6 shadow-card">
          <p className="text-sm text-gray-600">Total Funded</p>
          <p className="text-2xl font-bold text-gray-900">
            {formatCurrency(stats.totalFunded)}
          </p>
        </div>
        <div className="bg-white rounded-xl p-6 shadow-card">
          <p className="text-sm text-gray-600">Total Spent</p>
          <p className="text-2xl font-bold text-gray-900">
            {formatCurrency(stats.totalSpent)}
          </p>
        </div>
        <div className="bg-white rounded-xl p-6 shadow-card">
          <p className="text-sm text-gray-600">Total Withdrawn</p>
          <p className="text-2xl font-bold text-gray-900">
            {formatCurrency(stats.totalWithdrawn)}
          </p>
        </div>
      </div>
    </div>
  )
}

4. Wallet Transactions Component

The WalletTransactions component fetches and displays the user's transaction history in a table format. It maps transaction categories to icons for visual differentiation and uses color-coding to distinguish between credits (green) and debits (red).

The component handles the empty state by showing a friendly message when no transactions exist. Each transaction row displays the category with an icon, date, amount with positive/negative indicator, and the resulting balance after the transaction.

// components/wallet/WalletTransactions.tsx
import { getWalletTransactions } from '@/lib/data'
import { formatCurrency, formatDate } from '@/lib/utils'

const categoryIcons: Record<string, string> = {
  funding: '💰',
  purchase: '🛒',
  withdrawal: '🏦',
  refund: '↩️',
}

export default async function WalletTransactions() {
  const transactions = await getWalletTransactions()

  if (transactions.length === 0) {
    return (
      <div className="bg-white rounded-xl p-12 text-center shadow-card">
        <p className="text-gray-500">No wallet transactions yet</p>
      </div>
    )
  }

  return (
    <div className="bg-white rounded-xl shadow-card overflow-hidden">
      <div className="overflow-x-auto">
        <table className="w-full">
          <thead className="bg-gray-50">
            <tr>
              <th className="px-6 py-4 text-left text-sm font-medium text-gray-600">
                Transaction
              </th>
              <th className="px-6 py-4 text-left text-sm font-medium text-gray-600">
                Date
              </th>
              <th className="px-6 py-4 text-right text-sm font-medium text-gray-600">
                Amount
              </th>
              <th className="px-6 py-4 text-right text-sm font-medium text-gray-600">
                Balance
              </th>
            </tr>
          </thead>
          <tbody className="divide-y divide-gray-100">
            {transactions.map((tx) => (
              <tr key={tx.id} className="hover:bg-gray-50">
                <td className="px-6 py-4">
                  <div className="flex items-center gap-3">
                    <span className="text-2xl">
                      {categoryIcons[tx.category] || '💳'}
                    </span>
                    <div>
                      <p className="font-medium text-gray-900 capitalize">
                        {tx.category}
                      </p>
                      <p className="text-sm text-gray-500">
                        {tx.description || tx.reference}
                      </p>
                    </div>
                  </div>
                </td>
                <td className="px-6 py-4 text-sm text-gray-600">
                  {formatDate(tx.created_at)}
                </td>
                <td className="px-6 py-4 text-right">
                  <span
                    className={`font-semibold ${
                      tx.type === 'credit' ? 'text-green-600' : 'text-red-600'
                    }`}
                  >
                    {tx.type === 'credit' ? '+' : '-'}
                    {formatCurrency(tx.amount)}
                  </span>
                </td>
                <td className="px-6 py-4 text-right font-medium text-gray-900">
                  {formatCurrency(tx.balance_after)}
                </td>
              </tr>
            ))}
          </tbody>
        </table>
      </div>
    </div>
  )
}

5. Fund Wallet Page

The fund wallet page provides a simple layout that centers the funding form on the page. It's a server component that renders the FundWalletForm client component within a styled card container.

// app/(dashboard)/wallet/fund/page.tsx
import FundWalletForm from '@/components/wallet/FundWalletForm'

export default function FundWalletPage() {
  return (
    <div className="max-w-md mx-auto">
      <h1 className="text-2xl font-bold mb-6">Add Money to Wallet</h1>
      <div className="bg-white rounded-xl shadow-card p-6">
        <FundWalletForm />
      </div>
    </div>
  )
}

The FundWalletForm component provides a user-friendly interface for adding money to the wallet. It features quick-select buttons for common amounts (making it easy for users to tap and go) as well as a custom amount input field for flexibility.

The form uses React 19's useActionState hook to handle form submission and display feedback. A summary section shows the amount breakdown before the user confirms, and the component integrates with the initiateFunding server action to process the payment request.

// components/wallet/FundWalletForm.tsx
'use client'

import { useState } from 'react'
import { useActionState } from 'react'
import { initiateFunding } from '@/actions/wallet'
import { Button, Input } from '@/components/ui'
import { formatCurrency } from '@/lib/utils'

const quickAmounts = [1000, 2000, 5000, 10000, 20000, 50000]

export default function FundWalletForm() {
  const [amount, setAmount] = useState('')
  const [state, formAction, isPending] = useActionState(initiateFunding, {
    success: false,
    message: '',
  })

  return (
    <form action={formAction} className="space-y-6">
      {state.message && (
        <div
          className={`p-4 rounded-lg ${
            state.success
              ? 'bg-green-50 text-green-700'
              : 'bg-red-50 text-red-700'
          }`}
        >
          {state.message}
        </div>
      )}

      <div>
        <label className="block text-sm font-medium text-gray-700 mb-2">
          Select Amount
        </label>
        <div className="grid grid-cols-3 gap-3 mb-4">
          {quickAmounts.map((quickAmount) => (
            <button
              key={quickAmount}
              type="button"
              onClick={() => setAmount(quickAmount.toString())}
              className={`py-3 rounded-lg border-2 font-medium transition ${
                amount === quickAmount.toString()
                  ? 'border-primary bg-primary/5 text-primary'
                  : 'border-gray-200 hover:border-gray-300'
              }`}
            >
              {formatCurrency(quickAmount)}
            </button>
          ))}
        </div>

        <Input
          label="Or enter amount"
          name="amount"
          type="number"
          value={amount}
          onChange={(e) => setAmount(e.target.value)}
          placeholder="Enter amount"
          min="100"
          required
        />
      </div>

      <div className="bg-gray-50 rounded-lg p-4">
        <div className="flex justify-between text-sm">
          <span className="text-gray-600">Amount</span>
          <span className="font-medium">
            {amount ? formatCurrency(Number(amount)) : '₦0'}
          </span>
        </div>
        <div className="flex justify-between text-sm mt-2">
          <span className="text-gray-600">Fee</span>
          <span className="font-medium text-green-600">Free</span>
        </div>
        <div className="border-t mt-3 pt-3 flex justify-between">
          <span className="font-medium">Total</span>
          <span className="font-bold text-lg">
            {amount ? formatCurrency(Number(amount)) : '₦0'}
          </span>
        </div>
      </div>

      <Button type="submit" className="w-full" loading={isPending}>
        Continue to Payment
      </Button>
    </form>
  )
}

6. Wallet Actions

The wallet actions file contains server actions for managing wallet operations. The initiateFunding action validates the amount, generates a unique payment reference, and would typically integrate with a payment gateway like Paystack or Flutterwave to process the payment.

The creditWallet and debitWallet functions handle the actual balance updates, following a consistent pattern: fetch the current wallet state, calculate the new balance, update the wallet, and create a transaction record. Both functions use revalidatePath to ensure the UI reflects the updated data.

// actions/wallet.ts
'use server'

import { revalidatePath } from 'next/cache'
import { redirect } from 'next/navigation'
import { z } from 'zod'
import { getSession } from '@/lib/auth'
import { createClient } from '@/lib/supabase/server'

const FundingSchema = z.object({
  amount: z.number().min(100, 'Minimum amount is ₦100').max(1000000),
})

export async function initiateFunding(
  prevState: { success: boolean; message: string },
  formData: FormData
) {
  const session = await getSession()
  if (!session) {
    return { success: false, message: 'Please login to continue' }
  }

  const amount = Number(formData.get('amount'))
  const result = FundingSchema.safeParse({ amount })

  if (!result.success) {
    return { success: false, message: result.error.errors[0].message }
  }

  // Initialize payment with Paystack/Flutterwave
  const reference = `fund_${Date.now()}_${session.user.id.slice(0, 8)}`

  // In production, you'd call the payment gateway here
  // const paymentUrl = await initializePayment({
  //   amount: result.data.amount,
  //   email: session.user.email,
  //   reference,
  //   callback_url: `${process.env.NEXT_PUBLIC_APP_URL}/wallet/verify`,
  // })

  // For now, redirect to a mock verification
  redirect(`/wallet/verify?reference=${reference}&amount=${amount}`)
}

export async function creditWallet(
  userId: string,
  amount: number,
  reference: string,
  description: string
) {
  const supabase = await createClient()

  // Get current wallet
  const { data: wallet } = await supabase
    .from('wallets')
    .select('id, balance')
    .eq('user_id', userId)
    .single()

  if (!wallet) throw new Error('Wallet not found')

  const newBalance = wallet.balance + amount

  // Update wallet balance
  await supabase
    .from('wallets')
    .update({ balance: newBalance, updated_at: new Date().toISOString() })
    .eq('id', wallet.id)

  // Create transaction record
  await supabase.from('wallet_transactions').insert({
    wallet_id: wallet.id,
    type: 'credit',
    category: 'funding',
    amount,
    balance_before: wallet.balance,
    balance_after: newBalance,
    reference,
    description,
  })

  revalidatePath('/wallet')
  revalidatePath('/dashboard')
}

export async function debitWallet(
  userId: string,
  amount: number,
  reference: string,
  category: string,
  description: string
) {
  const supabase = await createClient()

  // Get current wallet
  const { data: wallet } = await supabase
    .from('wallets')
    .select('id, balance')
    .eq('user_id', userId)
    .single()

  if (!wallet) throw new Error('Wallet not found')
  if (wallet.balance < amount) throw new Error('Insufficient balance')

  const newBalance = wallet.balance - amount

  // Update wallet balance
  await supabase
    .from('wallets')
    .update({ balance: newBalance, updated_at: new Date().toISOString() })
    .eq('id', wallet.id)

  // Create transaction record
  await supabase.from('wallet_transactions').insert({
    wallet_id: wallet.id,
    type: 'debit',
    category,
    amount,
    balance_before: wallet.balance,
    balance_after: newBalance,
    reference,
    description,
  })

  revalidatePath('/wallet')
  revalidatePath('/dashboard')
}

7. Data Fetching Functions

These data fetching functions encapsulate all wallet-related database queries. Each function first validates the user session to ensure only authenticated users can access wallet data, then queries Supabase to retrieve the requested information.

The getWallet function fetches the user's wallet record, getWalletTransactions retrieves recent transactions with a configurable limit, and getWalletStats aggregates transaction data to calculate summary statistics. These functions are designed to be used in server components and server actions throughout the application.

// lib/data/wallet.ts
import { createClient } from '@/lib/supabase/server'
import { getSession } from '@/lib/auth'

export async function getWallet() {
  const session = await getSession()
  if (!session) throw new Error('Unauthorized')

  const supabase = await createClient()

  const { data, error } = await supabase
    .from('wallets')
    .select('*')
    .eq('user_id', session.user.id)
    .single()

  if (error) throw error
  return data
}

export async function getWalletTransactions(limit = 20) {
  const session = await getSession()
  if (!session) throw new Error('Unauthorized')

  const supabase = await createClient()

  const { data: wallet } = await supabase
    .from('wallets')
    .select('id')
    .eq('user_id', session.user.id)
    .single()

  if (!wallet) return []

  const { data, error } = await supabase
    .from('wallet_transactions')
    .select('*')
    .eq('wallet_id', wallet.id)
    .order('created_at', { ascending: false })
    .limit(limit)

  if (error) throw error
  return data || []
}

export async function getWalletStats() {
  const session = await getSession()
  if (!session) throw new Error('Unauthorized')

  const supabase = await createClient()

  const { data: wallet } = await supabase
    .from('wallets')
    .select('id')
    .eq('user_id', session.user.id)
    .single()

  if (!wallet) {
    return { totalFunded: 0, totalSpent: 0, totalWithdrawn: 0 }
  }

  const { data } = await supabase
    .from('wallet_transactions')
    .select('category, amount')
    .eq('wallet_id', wallet.id)

  const stats = {
    totalFunded: 0,
    totalSpent: 0,
    totalWithdrawn: 0,
  }

  data?.forEach((tx) => {
    if (tx.category === 'funding') stats.totalFunded += tx.amount
    if (tx.category === 'purchase') stats.totalSpent += tx.amount
    if (tx.category === 'withdrawal') stats.totalWithdrawn += tx.amount
  })

  return stats
}

Assignment

Task: Complete Wallet System

Build the complete wallet functionality:

Wallet overview page with balance and stats
Fund wallet flow with payment gateway integration
Withdrawal flow to bank account
Transaction history with filtering and pagination
Wallet transaction details modal

Files to Create

app/(dashboard)/wallet/
├── page.tsx
├── fund/
│   └── page.tsx
├── withdraw/
│   └── page.tsx
└── verify/
    └── page.tsx

components/wallet/
├── WalletOverview.tsx
├── WalletTransactions.tsx
├── FundWalletForm.tsx
└── WithdrawForm.tsx

lib/data/
└── wallet.ts

actions/
└── wallet.ts

Next Lesson: Bill Payment API Integration