diff --git a/apps/api/package.json b/apps/api/package.json
index 42c672c..6c7b65d 100644
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -6,7 +6,7 @@
   "private": true,
   "license": "UNLICENSED",
   "scripts": {
-    "build": "prisma generate && nest build && cp generated/prisma/package.json dist/generated/prisma/package.json",
+    "build": "prisma generate && nest build && node -e \"const fs=require('fs'); const source=['generated/prisma/package.json','node_modules/.prisma/client/package.json','node_modules/@prisma/client/package.json'].find((file)=>fs.existsSync(file)); if(source){ fs.mkdirSync('dist/generated/prisma',{recursive:true}); fs.copyFileSync(source,'dist/generated/prisma/package.json'); }\"",
     "prisma:generate": "prisma generate",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "start": "nest start",
diff --git a/apps/api/prisma/migrations/20260418090000_add_notifications/migration.sql b/apps/api/prisma/migrations/20260418090000_add_notifications/migration.sql
new file mode 100644
index 0000000..27c6789
--- /dev/null
+++ b/apps/api/prisma/migrations/20260418090000_add_notifications/migration.sql
@@ -0,0 +1,19 @@
+-- CreateTable
+CREATE TABLE "Notification" (
+    "id" TEXT NOT NULL,
+    "merchantId" TEXT NOT NULL,
+    "type" TEXT NOT NULL,
+    "title" TEXT NOT NULL,
+    "body" TEXT NOT NULL,
+    "read" BOOLEAN NOT NULL DEFAULT false,
+    "metadata" JSONB,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "Notification_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "Notification_merchantId_createdAt_idx" ON "Notification"("merchantId", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "Notification" ADD CONSTRAINT "Notification_merchantId_fkey" FOREIGN KEY ("merchantId") REFERENCES "Merchant"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/apps/api/prisma/schema.prisma b/apps/api/prisma/schema.prisma
index 68d71cf..d5d39bb 100644
--- a/apps/api/prisma/schema.prisma
+++ b/apps/api/prisma/schema.prisma
@@ -46,6 +46,7 @@ model Merchant {
   teamMembers       TeamMember[]
   webhookEvents     WebhookEvent[]
   apiKeys           ApiKey[]
+  notifications     Notification[]
   settlementKey     MerchantSettlementKey?
 }
 
@@ -355,3 +356,17 @@ enum WebhookStatus {
   FAILED
   EXHAUSTED
 }
+
+model Notification {
+  id         String   @id @default(cuid())
+  merchantId String
+  type       String
+  title      String
+  body       String
+  read       Boolean  @default(false)
+  metadata   Json?
+  createdAt  DateTime @default(now())
+  merchant    Merchant @relation(fields: [merchantId], references: [id], onDelete: Cascade)
+
+  @@index([merchantId, createdAt])
+}
diff --git a/apps/api/src/modules/auth/auth.service.ts b/apps/api/src/modules/auth/auth.service.ts
index b218300..f5459ce 100644
--- a/apps/api/src/modules/auth/auth.service.ts
+++ b/apps/api/src/modules/auth/auth.service.ts
@@ -205,6 +205,10 @@ export class AuthService {
       },
     });
 
+    void this.notifications
+      .notifyApiKeyCreated(merchantId, apiKey.id, apiKey.name)
+      .catch(() => undefined);
+
     return {
       apiKey: plainTextKey,
       id: apiKey.id,
diff --git a/apps/api/src/modules/events/events/events.service.ts b/apps/api/src/modules/events/events/events.service.ts
index bb92424..0f5970d 100644
--- a/apps/api/src/modules/events/events/events.service.ts
+++ b/apps/api/src/modules/events/events/events.service.ts
@@ -9,6 +9,15 @@ interface WebhookEventData {
   createdAt: Date | string;
 }
 
+interface NotificationCreatedPayload {
+  id: string;
+  type: string;
+  title: string;
+  body: string;
+  metadata?: unknown;
+  createdAt: Date | string;
+}
+
 /**
  * Events Service
  * Handles real-time event emission to connected WebSocket clients
@@ -242,4 +251,33 @@ export class EventsService {
       );
     }
   }
+
+  emitNotificationCreated(
+    merchantId: string,
+    notification: NotificationCreatedPayload,
+  ): void {
+    try {
+      const normalizedPayload = {
+        id: notification.id,
+        type: notification.type,
+        title: notification.title,
+        body: notification.body,
+        metadata: notification.metadata,
+        createdAt: new Date(notification.createdAt).toISOString(),
+      };
+
+      this.gateway.server
+        .to(`merchant:${merchantId}`)
+        .emit('notification.created', normalizedPayload);
+
+      this.gateway.server.to(`merchant:${merchantId}`).emit('message', {
+        event: 'notification.created',
+        data: normalizedPayload,
+      });
+    } catch (error) {
+      this.logger.error(
+        `Failed to emit notification.created: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+    }
+  }
 }
diff --git a/apps/api/src/modules/invoices/invoices.service.ts b/apps/api/src/modules/invoices/invoices.service.ts
index 01b29e9..cd75bc2 100644
--- a/apps/api/src/modules/invoices/invoices.service.ts
+++ b/apps/api/src/modules/invoices/invoices.service.ts
@@ -510,6 +510,10 @@ export class InvoicesService {
     });
 
     if (newStatus === InvoiceStatus.PAID) {
+      void this.notifications
+        .notifyInvoicePaid(merchantId, id, existing.invoiceNumber)
+        .catch(() => undefined);
+
       await this.webhooks.dispatch(merchantId, 'invoice.paid', {
         invoiceId: id,
         customerEmail: existing.customerEmail,
diff --git a/apps/api/src/modules/merchant/merchant.module.ts b/apps/api/src/modules/merchant/merchant.module.ts
index af33273..b1d285d 100644
--- a/apps/api/src/modules/merchant/merchant.module.ts
+++ b/apps/api/src/modules/merchant/merchant.module.ts
@@ -3,11 +3,12 @@ import { AuthModule } from '../auth/auth.module';
 import { PrismaModule } from '../prisma/prisma.module';
 import { MerchantController } from './merchant.controller';
 import { MerchantService } from './merchant.service';
+import { NotificationsModule } from '../notifications/notifications.module';
 import { MerchantSettlementService } from './merchant-settlement.service';
 import { RolesGuard } from './guards/roles.guard';
 
 @Module({
-  imports: [AuthModule, PrismaModule],
+  imports: [AuthModule, PrismaModule, NotificationsModule],
   controllers: [MerchantController],
   providers: [MerchantService, MerchantSettlementService, RolesGuard],
   // Export MerchantSettlementService so AuthService can call .provision()
diff --git a/apps/api/src/modules/merchant/merchant.service.ts b/apps/api/src/modules/merchant/merchant.service.ts
index 26f5725..7205c6f 100644
--- a/apps/api/src/modules/merchant/merchant.service.ts
+++ b/apps/api/src/modules/merchant/merchant.service.ts
@@ -10,11 +10,15 @@ import { SettlementDto } from './dto/settlement.dto';
 import { BrandingDto } from './dto/branding.dto';
 import { InviteMemberDto } from './dto/invite-member.dto';
 import { KybSubmissionDto } from './dto/kyb-submission.dto';
+import { NotificationsService } from '../notifications/notifications.service';
 import { detectAddressChain, type Chain } from '@useroutr/types';
 
 @Injectable()
 export class MerchantService {
-  constructor(private readonly prisma: PrismaService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly notifications: NotificationsService,
+  ) {}
 
   // ── Profile ──────────────────────────────────────────────────
 
@@ -138,7 +142,9 @@ export class MerchantService {
       },
     });
 
-    // TODO: send invite email via NotificationsModule once implemented
+    void this.notifications
+      .notifyTeamMemberJoined(merchantId, member.email, member.role)
+      .catch(() => undefined);
 
     return member;
   }
diff --git a/apps/api/src/modules/notifications/notifications.controller.ts b/apps/api/src/modules/notifications/notifications.controller.ts
new file mode 100644
index 0000000..37d69d6
--- /dev/null
+++ b/apps/api/src/modules/notifications/notifications.controller.ts
@@ -0,0 +1,47 @@
+import {
+  Controller,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  Patch,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import { JwtAuthGuard } from '../../common/guards/jwt-auth.guard';
+import { CurrentMerchant } from '../merchant/decorators/current-merchant.decorator';
+import { NotificationsService } from './notifications.service';
+
+@Controller('v1/notifications')
+@UseGuards(JwtAuthGuard)
+export class NotificationsController {
+  constructor(private readonly notificationsService: NotificationsService) {}
+
+  @Get()
+  async listNotifications(
+    @CurrentMerchant('id') merchantId: string,
+    @Query('limit') limit?: string,
+    @Query('cursor') cursor?: string,
+  ) {
+    return this.notificationsService.listNotifications(merchantId, {
+      limit: limit ? Number(limit) : undefined,
+      cursor,
+    });
+  }
+
+  @Patch(':id/read')
+  @HttpCode(HttpStatus.OK)
+  async markAsRead(
+    @CurrentMerchant('id') merchantId: string,
+    @Param('id') notificationId: string,
+  ) {
+    return this.notificationsService.markAsRead(merchantId, notificationId);
+  }
+
+  @Post('mark-all-read')
+  @HttpCode(HttpStatus.OK)
+  async markAllAsRead(@CurrentMerchant('id') merchantId: string) {
+    return this.notificationsService.markAllAsRead(merchantId);
+  }
+}
diff --git a/apps/api/src/modules/notifications/notifications.module.ts b/apps/api/src/modules/notifications/notifications.module.ts
index eda5d50..d31052f 100644
--- a/apps/api/src/modules/notifications/notifications.module.ts
+++ b/apps/api/src/modules/notifications/notifications.module.ts
@@ -1,16 +1,22 @@
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { BullModule } from '@nestjs/bullmq';
+import { PrismaModule } from '../prisma/prisma.module';
+import { EventsModule } from '../events/events.module';
+import { NotificationsController } from './notifications.controller';
 import { NotificationsService } from './notifications.service';
 import { NotificationsProcessor } from './notifications.processor';
 
 @Module({
   imports: [
     ConfigModule,
+    PrismaModule,
+    EventsModule,
     BullModule.registerQueue({
       name: 'notifications',
     }),
   ],
+  controllers: [NotificationsController],
   providers: [NotificationsService, NotificationsProcessor],
   exports: [NotificationsService],
 })
diff --git a/apps/api/src/modules/notifications/notifications.service.ts b/apps/api/src/modules/notifications/notifications.service.ts
index ceebe19..7284815 100644
--- a/apps/api/src/modules/notifications/notifications.service.ts
+++ b/apps/api/src/modules/notifications/notifications.service.ts
@@ -1,10 +1,49 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, NotFoundException } from '@nestjs/common';
 import { InjectQueue } from '@nestjs/bullmq';
 import { ConfigService } from '@nestjs/config';
+import { Notification, Prisma } from '@prisma/client';
 import { Queue } from 'bullmq';
-import { EmailJobData, Invoice, Payment, Payout } from './types';
+import { EventsService } from '../events/events/events.service';
+import { PrismaService } from '../prisma/prisma.service';
+import {
+  EmailJobData,
+  Invoice as EmailInvoice,
+  Payment as EmailPayment,
+  Payout as EmailPayout,
+} from './types';
 import * as templates from './templates';
 
+interface NotificationListOptions {
+  limit?: number;
+  cursor?: string;
+}
+
+interface CreateNotificationInput {
+  merchantId: string;
+  type: string;
+  title: string;
+  body: string;
+  metadata?: Prisma.InputJsonValue | null;
+}
+
+function formatCurrency(amount: number | string, currency = 'USD'): string {
+  const numericAmount = typeof amount === 'number' ? amount : Number(amount);
+
+  if (!Number.isFinite(numericAmount)) {
+    return String(amount);
+  }
+
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency,
+      maximumFractionDigits: 2,
+    }).format(numericAmount);
+  } catch {
+    return `${numericAmount.toFixed(2)} ${currency}`;
+  }
+}
+
 @Injectable()
 export class NotificationsService {
   private readonly appUrl: string;
@@ -13,6 +52,8 @@ export class NotificationsService {
     @InjectQueue('notifications')
     private readonly notificationsQueue: Queue<EmailJobData>,
     private readonly configService: ConfigService,
+    private readonly prisma: PrismaService,
+    private readonly eventsService: EventsService,
   ) {
     this.appUrl = this.configService.get<string>(
       'FRONTEND_URL',
@@ -34,6 +75,249 @@ export class NotificationsService {
     });
   }
 
+  async createNotification(
+    input: CreateNotificationInput,
+  ): Promise<Notification> {
+    const notification = await this.prisma.notification.create({
+      data: {
+        merchantId: input.merchantId,
+        type: input.type,
+        title: input.title,
+        body: input.body,
+        ...(input.metadata !== undefined
+          ? { metadata: input.metadata ?? Prisma.JsonNull }
+          : {}),
+      },
+    });
+
+    this.eventsService.emitNotificationCreated(input.merchantId, {
+      id: notification.id,
+      type: notification.type,
+      title: notification.title,
+      body: notification.body,
+      metadata: notification.metadata ?? undefined,
+      createdAt: notification.createdAt,
+    });
+
+    return notification;
+  }
+
+  async listNotifications(
+    merchantId: string,
+    options: NotificationListOptions = {},
+  ) {
+    const take = Math.min(Math.max(options.limit ?? 50, 1), 50);
+
+    let createdAtCursor: Date | undefined;
+    if (options.cursor) {
+      const cursorItem = await this.prisma.notification.findFirst({
+        where: {
+          id: options.cursor,
+          merchantId,
+        },
+        select: { createdAt: true },
+      });
+
+      createdAtCursor = cursorItem?.createdAt;
+    }
+
+    const where: Prisma.NotificationWhereInput = {
+      merchantId,
+      ...(createdAtCursor ? { createdAt: { lt: createdAtCursor } } : {}),
+    };
+
+    const [items, unreadCount, total] = await Promise.all([
+      this.prisma.notification.findMany({
+        where,
+        take,
+        orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
+      }),
+      this.prisma.notification.count({
+        where: {
+          merchantId,
+          read: false,
+        },
+      }),
+      this.prisma.notification.count({ where: { merchantId } }),
+    ]);
+
+    return {
+      data: items,
+      meta: {
+        total,
+        limit: take,
+        unreadCount,
+        nextCursor: items.length === take ? items[items.length - 1]?.id : null,
+      },
+    };
+  }
+
+  async markAsRead(merchantId: string, notificationId: string) {
+    const existing = await this.prisma.notification.findFirst({
+      where: { id: notificationId, merchantId },
+    });
+
+    if (!existing) {
+      throw new NotFoundException('Notification not found');
+    }
+
+    if (existing.read) {
+      return existing;
+    }
+
+    return this.prisma.notification.update({
+      where: { id: notificationId },
+      data: { read: true },
+    });
+  }
+
+  async markAllAsRead(merchantId: string) {
+    const result = await this.prisma.notification.updateMany({
+      where: {
+        merchantId,
+        read: false,
+      },
+      data: { read: true },
+    });
+
+    return {
+      updatedCount: result.count,
+    };
+  }
+
+  async notifyPaymentReceived(
+    merchantId: string,
+    paymentId: string,
+    amount: number | string,
+    currency = 'USD',
+    customerEmail?: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'payment.received',
+      title: 'Payment received',
+      body: `${formatCurrency(amount, currency)}${customerEmail ? ` from ${customerEmail}` : ''}`,
+      metadata: {
+        paymentId,
+        amount: String(amount),
+        currency,
+        ...(customerEmail ? { customerEmail } : {}),
+      },
+    });
+  }
+
+  async notifyPayoutCompleted(
+    merchantId: string,
+    payoutId: string,
+    recipientName: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'payout.completed',
+      title: 'Payout completed',
+      body: `Payout to ${recipientName} completed`,
+      metadata: {
+        payoutId,
+        recipientName,
+      },
+    });
+  }
+
+  async notifyPayoutFailed(
+    merchantId: string,
+    payoutId: string,
+    recipientName: string,
+    failureReason?: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'payout.failed',
+      title: 'Payout failed',
+      body: failureReason
+        ? `Payout to ${recipientName} failed: ${failureReason}`
+        : `Payout to ${recipientName} failed`,
+      metadata: {
+        payoutId,
+        recipientName,
+        ...(failureReason ? { failureReason } : {}),
+      },
+    });
+  }
+
+  async notifyInvoicePaid(
+    merchantId: string,
+    invoiceId: string,
+    invoiceNumber?: string | null,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'invoice.paid',
+      title: 'Invoice paid',
+      body: `Invoice ${invoiceNumber ? `#${invoiceNumber}` : ''} marked as paid`.trim(),
+      metadata: {
+        invoiceId,
+        ...(invoiceNumber ? { invoiceNumber } : {}),
+      },
+    });
+  }
+
+  async notifyRefundInitiated(merchantId: string, paymentId: string) {
+    return this.createNotification({
+      merchantId,
+      type: 'refund.initiated',
+      title: 'Refund initiated',
+      body: 'A refund has been started for one of your payments.',
+      metadata: { paymentId },
+    });
+  }
+
+  async notifyTeamMemberJoined(
+    merchantId: string,
+    email: string,
+    role: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'team.member_joined',
+      title: 'Team member joined',
+      body: `${email} was added to your team as ${role.toLowerCase()}.`,
+      metadata: { email, role },
+    });
+  }
+
+  async notifyApiKeyCreated(
+    merchantId: string,
+    keyId: string,
+    keyName: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'api_key.created',
+      title: 'API key created',
+      body: `API key '${keyName}' was created successfully.`,
+      metadata: { apiKeyId: keyId, keyName },
+    });
+  }
+
+  async notifyWebhookFailed(
+    merchantId: string,
+    webhookUrl: string,
+    eventType?: string,
+    eventId?: string,
+  ) {
+    return this.createNotification({
+      merchantId,
+      type: 'webhook.failed',
+      title: 'Webhook failed',
+      body: `Webhook delivery to ${webhookUrl} failed`,
+      metadata: {
+        webhookUrl,
+        ...(eventType ? { eventType } : {}),
+        ...(eventId ? { eventId } : {}),
+      },
+    });
+  }
+
   // Auth emails
   async sendVerificationEmail(email: string, token: string): Promise<void> {
     await this.dispatch({
@@ -75,7 +359,7 @@ export class NotificationsService {
   // Payments
   async sendPaymentReceipt(
     customerEmail: string,
-    payment: Payment,
+    payment: EmailPayment,
   ): Promise<void> {
     await this.dispatch({
       to: customerEmail,
@@ -86,7 +370,7 @@ export class NotificationsService {
 
   async sendPaymentNotification(
     merchantEmail: string,
-    payment: Payment,
+    payment: EmailPayment,
   ): Promise<void> {
     await this.dispatch({
       to: merchantEmail,
@@ -98,7 +382,7 @@ export class NotificationsService {
   // Invoices
   async sendInvoice(
     customerEmail: string,
-    invoice: Invoice,
+    invoice: EmailInvoice,
     pdfBuffer: Buffer,
   ): Promise<void> {
     await this.dispatch({
@@ -116,7 +400,7 @@ export class NotificationsService {
 
   async sendInvoiceReminder(
     customerEmail: string,
-    invoice: Invoice,
+    invoice: EmailInvoice,
   ): Promise<void> {
     const now = new Date();
     const diff = Math.ceil(
@@ -139,7 +423,7 @@ export class NotificationsService {
   // Payouts
   async sendPayoutConfirmation(
     merchantEmail: string,
-    payout: Payout,
+    payout: EmailPayout,
   ): Promise<void> {
     await this.dispatch({
       to: merchantEmail,
diff --git a/apps/api/src/modules/payments/payments.module.ts b/apps/api/src/modules/payments/payments.module.ts
index cca9527..96d9e3d 100644
--- a/apps/api/src/modules/payments/payments.module.ts
+++ b/apps/api/src/modules/payments/payments.module.ts
@@ -13,6 +13,7 @@ import { QuotesModule } from '../quotes/quotes.module';
 import { WebhooksModule } from '../webhooks/webhooks.module';
 import { StripeWebhooksController } from '../webhooks/webhooks.controller';
 import { AuthModule } from '../auth/auth.module';
+import { NotificationsModule } from '../notifications/notifications.module';
 import { LinksModule } from '../links/links.module';
 import { CctpModule } from '../cctp/cctp.module';
 
@@ -36,6 +37,7 @@ import { CctpModule } from '../cctp/cctp.module';
     // (not CctpModule) so the processor can inject PaymentsService without
     // a module-level circular dependency.
     BullModule.registerQueue({ name: CCTP_OBSERVE_QUEUE }),
+    NotificationsModule,
   ],
   providers: [PaymentsService, CctpProcessor],
   controllers: [
diff --git a/apps/api/src/modules/payments/payments.service.ts b/apps/api/src/modules/payments/payments.service.ts
index 94376b6..de36842 100644
--- a/apps/api/src/modules/payments/payments.service.ts
+++ b/apps/api/src/modules/payments/payments.service.ts
@@ -40,6 +40,7 @@ import { ethers } from 'ethers';
 import { CreatePaymentDto } from './dto/create-payment.dto';
 import { PaymentFiltersDto } from './dto/payment-filters.dto';
 import { PaymentResponseDto } from './dto/payment-response.dto';
+import { NotificationsService } from '../notifications/notifications.service';
 import * as crypto from 'crypto';
 
 interface CheckoutLineItem {
@@ -151,6 +152,7 @@ export class PaymentsService implements OnModuleInit {
     private readonly cctpService: CctpService,
     @InjectQueue(CCTP_OBSERVE_QUEUE) private readonly cctpQueue: Queue,
     private readonly configService: ConfigService,
+    private readonly notificationsService: NotificationsService,
   ) {
     const secretKey = this.configService.get<string>('STRIPE_SECRET_KEY');
     this.stripe = secretKey ? new Stripe(secretKey) : null;
@@ -208,6 +210,37 @@ export class PaymentsService implements OnModuleInit {
       updatedPayment.id,
     );
 
+    const metadata =
+      updatedPayment.metadata && typeof updatedPayment.metadata === 'object'
+        ? (updatedPayment.metadata as Record<string, unknown>)
+        : {};
+    const customerEmail =
+      typeof metadata.customerEmail === 'string'
+        ? metadata.customerEmail
+        : typeof metadata.email === 'string'
+          ? metadata.email
+          : undefined;
+
+    if (status === PaymentStatus.COMPLETED) {
+      const receivedAmount = updatedPayment.destAmount?.toString() ?? '0';
+
+      void this.notificationsService
+        .notifyPaymentReceived(
+          updatedPayment.merchantId,
+          updatedPayment.id,
+          receivedAmount,
+          updatedPayment.destAsset || 'USD',
+          customerEmail,
+        )
+        .catch(() => undefined);
+    }
+
+    if (status === PaymentStatus.REFUNDING) {
+      void this.notificationsService
+        .notifyRefundInitiated(updatedPayment.merchantId, updatedPayment.id)
+        .catch(() => undefined);
+    }
+
     return updatedPayment;
   }
 
@@ -391,9 +424,13 @@ export class PaymentsService implements OnModuleInit {
     const payment = await this.prisma.payment.create({
       data: {
         merchantId: internal.merchant.id,
+        quoteId: null,
         status: PaymentStatus.PENDING,
         // Source fields stay null until the customer picks a method.
         // Quote stays null too — created when the method is chosen.
+        sourceChain: null,
+        sourceAsset: null,
+        sourceAmount: null,
         destChain: internal.merchant.settlementChain,
         destAsset: internal.merchant.settlementAsset,
         destAmount,
diff --git a/apps/api/src/modules/payouts/payouts.module.ts b/apps/api/src/modules/payouts/payouts.module.ts
index 581fcc7..2e36b3c 100644
--- a/apps/api/src/modules/payouts/payouts.module.ts
+++ b/apps/api/src/modules/payouts/payouts.module.ts
@@ -5,9 +5,11 @@ import { PrismaModule } from '../prisma/prisma.module';
 import { WebhooksModule } from '../webhooks/webhooks.module';
 import { StellarModule } from '../stellar/stellar.module';
 import { AuthModule } from '../auth/auth.module';
+import { EventsModule } from '../events/events.module';
+import { NotificationsModule } from '../notifications/notifications.module';
 
 @Module({
-  imports: [PrismaModule, WebhooksModule, StellarModule, AuthModule],
+  imports: [PrismaModule, WebhooksModule, StellarModule, AuthModule, EventsModule, NotificationsModule],
   providers: [PayoutsService],
   controllers: [PayoutsController],
   exports: [PayoutsService],
diff --git a/apps/api/src/modules/payouts/payouts.service.ts b/apps/api/src/modules/payouts/payouts.service.ts
index 618ed05..bf013b8 100644
--- a/apps/api/src/modules/payouts/payouts.service.ts
+++ b/apps/api/src/modules/payouts/payouts.service.ts
@@ -9,6 +9,8 @@ import { DestType, Payout, PayoutStatus, Prisma } from '@prisma/client';
 import { PrismaService } from '../prisma/prisma.service';
 import { WebhooksService } from '../webhooks/webhooks.service';
 import { StellarService } from '../stellar/stellar.service';
+import { EventsService } from '../events/events/events.service';
+import { NotificationsService } from '../notifications/notifications.service';
 import { CreatePayoutDto, BulkPayoutDto } from './dto/create-payout.dto';
 import { PayoutFiltersDto } from './dto/payout-filters.dto';
 import { randomUUID } from 'crypto';
@@ -42,6 +44,8 @@ export class PayoutsService {
     private readonly prisma: PrismaService,
     private readonly webhooks: WebhooksService,
     private readonly stellar: StellarService,
+    private readonly eventsService: EventsService,
+    private readonly notifications: NotificationsService,
   ) {}
 
   // ── Create single payout ──────────────────────────────────────────────────
@@ -254,6 +258,25 @@ export class PayoutsService {
         where: { id: payout.id },
         data: { status: PayoutStatus.FAILED, failureReason },
       });
+      this.eventsService.emitPayoutStatus(
+        payout.merchantId,
+        payout.id,
+        PayoutStatus.FAILED,
+        {
+          amount: failed.amount.toString(),
+          currency: failed.currency,
+          failureReason,
+          updatedAt: new Date(),
+        },
+      );
+      void this.notifications
+        .notifyPayoutFailed(
+          payout.merchantId,
+          payout.id,
+          payout.recipientName,
+          failureReason,
+        )
+        .catch(() => undefined);
       this.webhooks
         .dispatch(payout.merchantId, 'payout.failed', {
           ...this.webhookPayload(failed),
@@ -307,6 +330,25 @@ export class PayoutsService {
       },
     });
 
+    this.eventsService.emitPayoutStatus(
+      payout.merchantId,
+      payout.id,
+      PayoutStatus.COMPLETED,
+      {
+        amount: completed.amount.toString(),
+        currency: completed.currency,
+        stellarTxHash: txHash,
+        updatedAt: new Date(),
+      },
+    );
+    void this.notifications
+      .notifyPayoutCompleted(
+        payout.merchantId,
+        payout.id,
+        payout.recipientName,
+      )
+      .catch(() => undefined);
+
     this.webhooks
       .dispatch(payout.merchantId, 'payout.completed', {
         ...this.webhookPayload(completed),
diff --git a/apps/api/src/modules/webhooks/webhooks.module.ts b/apps/api/src/modules/webhooks/webhooks.module.ts
index a1e10ab..5a1532f 100644
--- a/apps/api/src/modules/webhooks/webhooks.module.ts
+++ b/apps/api/src/modules/webhooks/webhooks.module.ts
@@ -4,11 +4,13 @@ import { WebhooksService } from './webhooks.service';
 import { WebhooksProcessor } from './webhooks.processor';
 import { WebhooksController } from './webhooks.controller';
 import { PrismaModule } from '../prisma/prisma.module';
+import { NotificationsModule } from '../notifications/notifications.module';
 import { WEBHOOK_QUEUE_NAME } from './webhooks.constants';
 
 @Module({
   imports: [
     PrismaModule,
+    NotificationsModule,
     BullModule.registerQueue({ name: WEBHOOK_QUEUE_NAME }),
   ],
   providers: [WebhooksService, WebhooksProcessor],
diff --git a/apps/api/src/modules/webhooks/webhooks.processor.ts b/apps/api/src/modules/webhooks/webhooks.processor.ts
index 0e574dc..be124be 100644
--- a/apps/api/src/modules/webhooks/webhooks.processor.ts
+++ b/apps/api/src/modules/webhooks/webhooks.processor.ts
@@ -3,6 +3,7 @@ import { Processor, WorkerHost, InjectQueue } from '@nestjs/bullmq';
 import { Job, Queue } from 'bullmq';
 import axios, { AxiosError } from 'axios';
 import { PrismaService } from '../prisma/prisma.service';
+import { NotificationsService } from '../notifications/notifications.service';
 import { WebhookStatus } from '@prisma/client';
 import {
   WEBHOOK_QUEUE_NAME,
@@ -22,6 +23,7 @@ export class WebhooksProcessor extends WorkerHost {
   constructor(
     @InjectQueue(WEBHOOK_QUEUE_NAME) private readonly webhookQueue: Queue,
     private readonly prisma: PrismaService,
+    private readonly notifications: NotificationsService,
   ) {
     super();
   }
@@ -117,6 +119,12 @@ export class WebhooksProcessor extends WorkerHost {
           },
         });
 
+        if (attempt === 1) {
+          void this.notifications
+            .notifyWebhookFailed(merchantId, webhookUrl, eventType, eventId)
+            .catch(() => undefined);
+        }
+
         this.logger.log(
           `Webhook ${eventId} will retry at ${nextRetryAt.toISOString()} (delay: ${delayMs}ms)`,
         );
diff --git a/apps/api/tsconfig.json b/apps/api/tsconfig.json
index 7561134..7ab7cf6 100644
--- a/apps/api/tsconfig.json
+++ b/apps/api/tsconfig.json
@@ -1,7 +1,6 @@
 {
   "compilerOptions": {
     "module": "CommonJS",
-    "moduleResolution": "node",
     "esModuleInterop": true,
     "isolatedModules": true,
     "declaration": true,
@@ -12,7 +11,6 @@
     "target": "ES2020",
     "sourceMap": true,
     "outDir": "./dist",
-    "baseUrl": "./",
     "incremental": true,
     "skipLibCheck": true,
     "strictNullChecks": true,
diff --git a/apps/dashboard/src/app/(dashboard)/layout.tsx b/apps/dashboard/src/app/(dashboard)/layout.tsx
index 6e42f32..2c5c12b 100644
--- a/apps/dashboard/src/app/(dashboard)/layout.tsx
+++ b/apps/dashboard/src/app/(dashboard)/layout.tsx
@@ -4,6 +4,7 @@ import { AppSidebar } from "@/components/app-sidebar";
 import { SiteHeader } from "@/components/site-header";
 import { SidebarInset, SidebarProvider, SidebarRail } from "@useroutr/ui";
 import { useAuth } from "@/providers/AuthProvider";
+import { useRefundEvents } from "@/hooks/useRefundEvents";
 
 export default function DashboardLayout({
   children,
@@ -12,6 +13,9 @@ export default function DashboardLayout({
 }) {
   const { merchant, isLoading } = useAuth();
 
+  // Subscribe to real-time refund events across all dashboard pages
+  useRefundEvents();
+
   if (isLoading) {
     return (
       <div className="flex min-h-screen items-center justify-center bg-background px-6">
diff --git a/apps/dashboard/src/app/(dashboard)/links/page.tsx b/apps/dashboard/src/app/(dashboard)/links/page.tsx
index ee86758..e779f83 100644
--- a/apps/dashboard/src/app/(dashboard)/links/page.tsx
+++ b/apps/dashboard/src/app/(dashboard)/links/page.tsx
@@ -94,15 +94,13 @@ export default function PaymentLinksPage() {
   const { subscribe } = useDashboardSocket();
 
   useEffect(() => {
-    // Subscribe to payment link payment events
-    const unsubscribe = subscribe("payment-link.payment", (...args: unknown[]) => {
-      const payload = args[0] as { linkId: string; amount: number };
-      toast(`Payment received: $${payload.amount}`, "success");
+    // Refresh the link list when a real-time link payment event arrives.
+    const unsubscribe = subscribe("payment-link.payment", () => {
       refetch();
     });
 
     return () => unsubscribe();
-  }, [subscribe, toast, refetch]);
+  }, [subscribe, refetch]);
 
   const handleCreate = (data: CreatePaymentLinkInput) => {
     createMutation.mutate(data, {
diff --git a/apps/dashboard/src/app/(dashboard)/refunds/page.tsx b/apps/dashboard/src/app/(dashboard)/refunds/page.tsx
new file mode 100644
index 0000000..5dfadb1
--- /dev/null
+++ b/apps/dashboard/src/app/(dashboard)/refunds/page.tsx
@@ -0,0 +1,18 @@
+import { RefundHistoryTable } from "@/components/payments/RefundHistoryTable";
+
+export default function RefundsPage() {
+  return (
+    <div className="space-y-6">
+      <div>
+        <h2 className="font-display text-xl font-semibold text-foreground">
+          Refunds
+        </h2>
+        <p className="mt-1 text-sm text-muted-foreground">
+          View and manage all refund transactions
+        </p>
+      </div>
+
+      <RefundHistoryTable />
+    </div>
+  );
+}
diff --git a/apps/dashboard/src/app/(dashboard)/settings/page.tsx b/apps/dashboard/src/app/(dashboard)/settings/page.tsx
index 44c0427..d3385de 100644
--- a/apps/dashboard/src/app/(dashboard)/settings/page.tsx
+++ b/apps/dashboard/src/app/(dashboard)/settings/page.tsx
@@ -7,6 +7,7 @@ import {
   useUpdateMerchantProfile,
   useProvisionSettlement,
 } from "@/hooks/useSettings";
+import { useToastNotificationPreference } from "@/hooks/useToastNotificationPreference";
 import { motion } from "framer-motion";
 import {
   Building2,
@@ -33,6 +34,10 @@ export default function SettingsPage() {
   const { data: merchant, isLoading: isLoadingProfile } =
     useMerchantProfile();
   const updateProfile = useUpdateMerchantProfile();
+  const {
+    enabled: realtimeNotificationsEnabled,
+    setEnabled: setRealtimeNotificationsEnabled,
+  } = useToastNotificationPreference();
   const provisionSettlement = useProvisionSettlement();
 
   const [name, setName] = useState("");
@@ -62,6 +67,16 @@ export default function SettingsPage() {
     );
   };
 
+  const handleRealtimeNotificationsToggle = (checked: boolean) => {
+    setRealtimeNotificationsEnabled(checked);
+    toast(
+      checked
+        ? "Real-time notifications enabled."
+        : "Real-time notifications disabled.",
+      checked ? "success" : "info",
+    );
+  };
+
   if (isLoadingProfile) {
     return (
       <div className="space-y-6">
@@ -254,6 +269,39 @@ export default function SettingsPage() {
         </div>
 
         <div className="mt-5 space-y-2">
+          <label className="flex items-center justify-between gap-4 rounded-xl border border-border/60 bg-secondary/30 p-4 cursor-pointer transition-all duration-200 hover:bg-secondary/60">
+            <div className="flex items-center gap-3">
+              <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-background">
+                <Radio size={15} className="text-primary" />
+              </div>
+              <div>
+                <div className="flex items-center gap-2">
+                  <p className="text-sm font-medium text-foreground">
+                    Enable real-time notifications
+                  </p>
+                  <span
+                    className={`rounded-full px-2 py-0.5 text-[10px] font-semibold uppercase tracking-wide ${
+                      realtimeNotificationsEnabled
+                        ? "bg-emerald-100 text-emerald-700"
+                        : "bg-muted text-muted-foreground"
+                    }`}
+                  >
+                    {realtimeNotificationsEnabled ? "On" : "Off"}
+                  </span>
+                </div>
+                <p className="text-xs text-muted-foreground">
+                  Show live payment, payout, invoice, and webhook updates in-app
+                </p>
+              </div>
+            </div>
+            <Switch
+              checked={realtimeNotificationsEnabled}
+              onCheckedChange={handleRealtimeNotificationsToggle}
+              aria-label="Enable real-time notifications"
+              className="data-[state=checked]:bg-emerald-500"
+            />
+          </label>
+
           {[
             {
               label: "Email notifications",
diff --git a/apps/dashboard/src/app/globals.css b/apps/dashboard/src/app/globals.css
index 7003643..178963d 100644
--- a/apps/dashboard/src/app/globals.css
+++ b/apps/dashboard/src/app/globals.css
@@ -7,10 +7,107 @@
 @import "tw-animate-css";
 @import "@useroutr/ui/globals.css";
 
+@source "../../../../packages/ui/src";
+
 @custom-variant dark (&:is(.dark *));
 
-:root {
-  --header-height: 3.5rem;
+@theme inline {
+  /* ── Colors ── */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-border: var(--border);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+
+  /* ── Chart palette ── */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /* ── Brand palette ── */
+  --color-ink: var(--ink);
+  --color-ink2: var(--ink2);
+  --color-ink3: var(--ink3);
+  --color-blue: var(--blue);
+  --color-blue2: var(--blue2);
+  --color-teal: var(--teal);
+  --color-amber: var(--amber);
+  --color-red: var(--red);
+  --color-green: var(--green);
+  --color-purple: var(--purple);
+
+  /* ── Font families ── */
+  --font-display: "Inter", "Trebuchet MS", sans-serif;
+  --font-body: "Open Sans", sans-serif;
+  --font-mono: "IBM Plex Mono", "JetBrains Mono", Menlo, monospace;
+
+  /* ── Radius ── */
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+  --radius-2xl: var(--radius-2xl);
+
+  /* ── Sidebar ── */
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+
+  /* ── Dark mode page tokens ── */
+  --color-bg-page: var(--bg-page);
+  --color-bg-card: var(--bg-card);
+  --color-bg-sidebar: var(--bg-sidebar);
+  --color-text-primary: var(--text-primary);
+  --color-text-secondary: var(--text-secondary);
+  --color-border-color: var(--border-color);
+  --color-input-bg: var(--input-bg);
+  --color-input-border: var(--input-border);
+  --color-code-bg: var(--code-bg);
+
+  /* ── Chart theming tokens ── */
+  --color-chart-tick: var(--chart-tick);
+  --color-chart-grid: var(--chart-grid);
+  --color-chart-tooltip-bg: var(--chart-tooltip-bg);
+  --color-chart-tooltip-text: var(--chart-tooltip-text);
+
+  /* ── Status tokens ── */
+  --color-status-success-bg: var(--status-success-bg);
+  --color-status-success-text: var(--status-success-text);
+  --color-status-warning-bg: var(--status-warning-bg);
+  --color-status-warning-text: var(--status-warning-text);
+  --color-status-error-bg: var(--status-error-bg);
+  --color-status-error-text: var(--status-error-text);
+  --color-status-info-bg: var(--status-info-bg);
+  --color-status-info-text: var(--status-info-text);
+  --color-status-purple-bg: var(--status-purple-bg);
+  --color-status-purple-text: var(--status-purple-text);
+  --color-status-amber-bg: var(--status-amber-bg);
+  --color-status-amber-text: var(--status-amber-text);
 }
 
 @layer base {
diff --git a/apps/dashboard/src/app/layout.tsx b/apps/dashboard/src/app/layout.tsx
index 595381e..e55d6f0 100644
--- a/apps/dashboard/src/app/layout.tsx
+++ b/apps/dashboard/src/app/layout.tsx
@@ -4,8 +4,11 @@ import { Hanken_Grotesk, Fraunces, JetBrains_Mono } from "next/font/google";
 import { ThemeProvider } from "@/providers/ThemeProvider";
 import { QueryProvider } from "@/providers/QueryProvider";
 import { AuthProvider } from "@/providers/AuthProvider";
+import { RealtimeToastNotifications } from "@/providers/RealtimeToastNotifications";
+import { NotificationsProvider } from "@/providers/NotificationsProvider";
 import "./globals.css";
 import { ToastProvider } from "@useroutr/ui";
+import { TooltipProvider } from "@/components/ui/tooltip";
 
 // Hanken Grotesk — display + body. Same family as the marketing site so the
 // brand voice is unbroken between useroutr.com and dashboard.useroutr.com.
@@ -56,7 +59,14 @@ export default function RootLayout({
           <QueryProvider>
             <Suspense>
               <AuthProvider>
-                <ToastProvider>{children}</ToastProvider>
+                <TooltipProvider>
+                  <ToastProvider>
+                    <NotificationsProvider>
+                      <RealtimeToastNotifications />
+                      {children}
+                    </NotificationsProvider>
+                  </ToastProvider>
+                </TooltipProvider>
               </AuthProvider>
             </Suspense>
           </QueryProvider>
diff --git a/apps/dashboard/src/components/analytics/AnalyticsDashboard.tsx b/apps/dashboard/src/components/analytics/AnalyticsDashboard.tsx
index 00b11f1..40726fd 100644
--- a/apps/dashboard/src/components/analytics/AnalyticsDashboard.tsx
+++ b/apps/dashboard/src/components/analytics/AnalyticsDashboard.tsx
@@ -111,9 +111,9 @@ const PERIOD_OPTIONS: Array<{ value: Period; label: string }> = [
 ];
 
 const PAYMENT_COLORS: Record<PaymentMethod, string> = {
-  card: "#3b82f6",
-  crypto: "#14b8a6",
-  bank: "#f59e0b",
+  card: "var(--blue)",
+  crypto: "var(--teal)",
+  bank: "var(--amber)",
 };
 
 const WEEKDAY_LABELS = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
@@ -782,7 +782,7 @@ function RevenueChart({
                 x2={width}
                 y1={y}
                 y2={y}
-                stroke="rgba(148,163,184,0.22)"
+                stroke="var(--chart-grid)"
                 strokeDasharray="4 6"
               />
             );
@@ -806,7 +806,7 @@ function RevenueChart({
                   width={barWidth}
                   height={barHeight}
                   rx={8}
-                  fill={active ? "#1d4ed8" : "#3b82f6"}
+                  fill={active ? "var(--blue)" : "var(--blue2)"}
                   opacity={active ? 1 : 0.82}
                 />
                 <text
@@ -814,7 +814,7 @@ function RevenueChart({
                   y={height - 18}
                   textAnchor="middle"
                   fontSize="11"
-                  fill="rgba(100,116,139,1)"
+                  fill="var(--chart-tick)"
                 >
                   {point.label}
                 </text>
@@ -826,13 +826,13 @@ function RevenueChart({
                       width={106}
                       height={30}
                       rx={10}
-                      fill="rgba(15,23,42,0.95)"
+                      fill="var(--chart-tooltip-bg)"
                     />
                     <text
                       x={Math.max(18, x - 18)}
                       y={Math.max(28, y - 18)}
                       fontSize="11"
-                      fill="#ffffff"
+                      fill="var(--chart-tooltip-text)"
                     >
                       {formatCompactMoney(point.amount)}
                     </text>
@@ -880,7 +880,7 @@ function PaymentMethodCard({
               cy="70"
               r={radius}
               fill="none"
-              stroke="rgba(148,163,184,0.18)"
+              stroke="var(--chart-grid)"
               strokeWidth="20"
             />
             {segments.map((segment) => {
@@ -983,8 +983,8 @@ function ConversionCard({
         >
           <defs>
             <linearGradient id="conversion-fill-dashboard" x1="0" x2="0" y1="0" y2="1">
-              <stop offset="0%" stopColor="rgba(20,184,166,0.35)" />
-              <stop offset="100%" stopColor="rgba(20,184,166,0.02)" />
+              <stop offset="0%" stopColor="var(--teal)" stopOpacity={0.35} />
+              <stop offset="100%" stopColor="var(--teal)" stopOpacity={0.02} />
             </linearGradient>
           </defs>
           <path
@@ -994,7 +994,7 @@ function ConversionCard({
           <path
             d={path}
             fill="none"
-            stroke="#14b8a6"
+            stroke="var(--teal)"
             strokeWidth="3"
             strokeLinecap="round"
             strokeLinejoin="round"
@@ -1058,7 +1058,7 @@ function FailureHeatmap({
   const maxCount = Math.max(...byHour.map((cell) => cell.count), 1);
   const getColor = (count: number) => {
     const alpha = count / maxCount;
-    return `rgba(239,68,68,${0.1 + alpha * 0.75})`;
+    return `color-mix(in srgb, var(--red) ${Math.round((0.1 + alpha * 0.75) * 100)}%, transparent)`;
   };
 
   return (
diff --git a/apps/dashboard/src/components/app-sidebar.tsx b/apps/dashboard/src/components/app-sidebar.tsx
index 9059916..30b91bc 100644
--- a/apps/dashboard/src/components/app-sidebar.tsx
+++ b/apps/dashboard/src/components/app-sidebar.tsx
@@ -10,6 +10,7 @@ import {
   Settings,
   LifeBuoy,
   Send,
+  RotateCcw,
 } from "lucide-react";
 
 import { NavMain } from "@/components/nav-main";
@@ -28,6 +29,7 @@ import {
 const navMain = [
   { title: "Overview", url: "/", icon: Home },
   { title: "Payments", url: "/payments", icon: CreditCard },
+  { title: "Refunds", url: "/refunds", icon: RotateCcw },
   { title: "Payment Links", url: "/links", icon: Link2 },
   { title: "Invoices", url: "/invoices", icon: FileText },
   { title: "Payouts", url: "/payouts", icon: ArrowLeftRight },
diff --git a/apps/dashboard/src/components/invoices/InvoiceDetailSheet.tsx b/apps/dashboard/src/components/invoices/InvoiceDetailSheet.tsx
index 3d7e594..060eac1 100644
--- a/apps/dashboard/src/components/invoices/InvoiceDetailSheet.tsx
+++ b/apps/dashboard/src/components/invoices/InvoiceDetailSheet.tsx
@@ -1,4 +1,4 @@
-"use client";
+"use client";
 
 import { useState } from "react";
 import {
@@ -34,15 +34,15 @@ import { SendInvoiceModal } from "./SendInvoiceModal";
 import { InvoicePdfPreview } from "./InvoicePdfPreview";
 import type { Invoice, InvoiceStatus } from "@/hooks/useInvoices";
 
-// ── Status badge ───────────────────────────────────────────────────────────────
+// ── Status badge ───────────────────────────────────────────────────────────────
 
 const STATUS_CONFIG: Record<InvoiceStatus, { label: string; className: string }> = {
   DRAFT: { label: "Draft", className: "bg-muted text-muted-foreground" },
-  SENT: { label: "Sent", className: "bg-blue-100 text-blue-700 dark:bg-blue-900/40 dark:text-blue-300" },
-  VIEWED: { label: "Viewed", className: "bg-purple-100 text-purple-700 dark:bg-purple-900/40 dark:text-purple-300" },
-  PARTIALLY_PAID: { label: "Partially Paid", className: "bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300" },
-  PAID: { label: "Paid", className: "bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300" },
-  OVERDUE: { label: "Overdue", className: "bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-300" },
+  SENT: { label: "Sent", className: "bg-status-info-bg text-status-info-text" },
+  VIEWED: { label: "Viewed", className: "bg-status-purple-bg text-status-purple-text" },
+  PARTIALLY_PAID: { label: "Partially Paid", className: "bg-status-amber-bg text-status-amber-text" },
+  PAID: { label: "Paid", className: "bg-status-success-bg text-status-success-text" },
+  OVERDUE: { label: "Overdue", className: "bg-status-error-bg text-status-error-text" },
   CANCELLED: { label: "Cancelled", className: "bg-muted text-muted-foreground" },
 };
 
@@ -55,7 +55,7 @@ function StatusBadge({ status }: { status: InvoiceStatus }) {
   );
 }
 
-// ── Activity timeline ─────────────────────────────────────────────────────────
+// ── Activity timeline ─────────────────────────────────────────────────────────
 
 interface TimelineEvent {
   key: string;
@@ -239,7 +239,7 @@ function ActivityTimeline({ invoice }: { invoice: Invoice }) {
   );
 }
 
-// ── Props ──────────────────────────────────────────────────────────────────────
+// ── Props ──────────────────────────────────────────────────────────────────────
 
 interface InvoiceDetailSheetProps {
   invoice: Invoice | null;
@@ -254,7 +254,7 @@ interface InvoiceDetailSheetProps {
   isSendPending?: boolean;
 }
 
-// ── Helpers ────────────────────────────────────────────────────────────────────
+// ── Helpers ────────────────────────────────────────────────────────────────────
 
 function fmtCurrency(amount: string | number, currency: string) {
   const num = typeof amount === "string" ? parseFloat(amount) : amount;
@@ -263,7 +263,7 @@ function fmtCurrency(amount: string | number, currency: string) {
 }
 
 function fmtDate(iso?: string | null) {
-  if (!iso) return "—";
+  if (!iso) return "—";
   return new Date(iso).toLocaleDateString("en-US", {
     year: "numeric",
     month: "long",
@@ -271,7 +271,7 @@ function fmtDate(iso?: string | null) {
   });
 }
 
-// ── Component ──────────────────────────────────────────────────────────────────
+// ── Component ──────────────────────────────────────────────────────────────────
 
 export function InvoiceDetailSheet({
   invoice,
@@ -305,7 +305,7 @@ export function InvoiceDetailSheet({
     <>
       <Sheet open={open} onOpenChange={onOpenChange}>
         <SheetContent className="w-full sm:max-w-[520px] flex flex-col gap-0 p-0 overflow-hidden">
-          {/* ── Header ── */}
+          {/* ── Header ── */}
           <SheetHeader className="px-6 py-4 border-b border-border shrink-0">
             <div className="flex items-start justify-between gap-3 pr-6">
               <div className="space-y-1.5 min-w-0">
@@ -334,7 +334,7 @@ export function InvoiceDetailSheet({
             </div>
           </SheetHeader>
 
-          {/* ── Scrollable body ── */}
+          {/* ── Scrollable body ── */}
           <div className="flex-1 overflow-y-auto">
             <div className="px-6 py-5 space-y-6">
 
@@ -402,7 +402,7 @@ export function InvoiceDetailSheet({
                     </p>
                     <p
                       className={`text-sm font-medium ${
-                        invoice.status === "OVERDUE" ? "text-red-600" : "text-foreground"
+                        invoice.status === "OVERDUE" ? "text-status-error-text" : "text-foreground"
                       }`}
                     >
                       {fmtDate(invoice.dueDate)}
@@ -412,7 +412,7 @@ export function InvoiceDetailSheet({
                 {invoice.paidAt && (
                   <div className="space-y-1">
                     <p className="text-xs text-muted-foreground">Paid On</p>
-                    <p className="text-sm font-medium text-green-600">{fmtDate(invoice.paidAt)}</p>
+                    <p className="text-sm font-medium text-status-success-text">{fmtDate(invoice.paidAt)}</p>
                   </div>
                 )}
               </section>
@@ -464,8 +464,8 @@ export function InvoiceDetailSheet({
                 {discount > 0 && (
                   <div className="flex justify-between text-muted-foreground">
                     <span>Discount</span>
-                    <span className="tabular-nums text-green-600">
-                      −{fmtCurrency(discount, invoice.currency)}
+                    <span className="tabular-nums text-status-success-text">
+                      −{fmtCurrency(discount, invoice.currency)}
                     </span>
                   </div>
                 )}
@@ -476,7 +476,7 @@ export function InvoiceDetailSheet({
                 </div>
                 {amountPaid > 0 && (
                   <>
-                    <div className="flex justify-between text-green-600 text-xs">
+                    <div className="flex justify-between text-status-success-text text-xs">
                       <span>Amount Paid</span>
                       <span className="tabular-nums">{fmtCurrency(amountPaid, invoice.currency)}</span>
                     </div>
@@ -494,10 +494,10 @@ export function InvoiceDetailSheet({
                   <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
                     Payment Details
                   </h3>
-                  <div className="rounded-lg border border-border bg-green-50/50 dark:bg-green-900/10 p-4 space-y-2 text-sm">
+                  <div className="rounded-lg border border-border bg-status-success-bg p-4 space-y-2 text-sm">
                     <div className="flex items-center gap-2">
-                      <CheckCircle2 className="h-4 w-4 text-green-600 shrink-0" />
-                      <span className="font-medium text-green-700 dark:text-green-400">
+                      <CheckCircle2 className="h-4 w-4 text-status-success-text shrink-0" />
+                      <span className="font-medium text-status-success-text">
                         {invoice.status === "PAID" ? "Fully paid" : "Partially paid"}
                       </span>
                     </div>
@@ -517,7 +517,7 @@ export function InvoiceDetailSheet({
                       {amountDue > 0 && (
                         <div className="space-y-0.5">
                           <p className="text-xs text-muted-foreground">Balance due</p>
-                          <p className="font-semibold text-amber-600">
+                          <p className="font-semibold text-status-amber-text">
                             {fmtCurrency(amountDue, invoice.currency)}
                           </p>
                         </div>
@@ -554,7 +554,7 @@ export function InvoiceDetailSheet({
             </div>
           </div>
 
-          {/* ── Footer actions ── */}
+          {/* ── Footer actions ── */}
           <div className="shrink-0 border-t border-border px-6 py-4 space-y-2">
             {/* Primary row: Edit + Send */}
             {isDraft && (
@@ -615,7 +615,7 @@ export function InvoiceDetailSheet({
         </SheetContent>
       </Sheet>
 
-      {/* ── Send modal (rendered outside sheet to avoid z-index nesting issues) ── */}
+      {/* ── Send modal (rendered outside sheet to avoid z-index nesting issues) ── */}
       <SendInvoiceModal
         invoice={invoice}
         open={sendModalOpen}
@@ -624,7 +624,7 @@ export function InvoiceDetailSheet({
         isSending={isSendPending}
       />
 
-      {/* ── PDF preview dialog ── */}
+      {/* ── PDF preview dialog ── */}
       <InvoicePdfPreview
         invoice={invoice}
         open={pdfPreviewOpen}
diff --git a/apps/dashboard/src/components/invoices/InvoiceDrawer.tsx b/apps/dashboard/src/components/invoices/InvoiceDrawer.tsx
index 494c5a7..b3d0aa1 100644
--- a/apps/dashboard/src/components/invoices/InvoiceDrawer.tsx
+++ b/apps/dashboard/src/components/invoices/InvoiceDrawer.tsx
@@ -1,4 +1,4 @@
-"use client";
+"use client";
 
 import { useState, useCallback } from "react";
 import { z } from "zod";
@@ -18,14 +18,14 @@ import {
 } from "@useroutr/ui";
 import type { CreateInvoiceInput, Invoice } from "@/hooks/useInvoices";
 
-// ── Validation schema ──────────────────────────────────────────────────────────
+// ── Validation schema ──────────────────────────────────────────────────────────
 
 const LineItemSchema = z.object({
   description: z.string().min(1, "Description is required"),
   qty: z.number({ invalid_type_error: "Must be a number" }).positive("Qty > 0"),
   unitPrice: z
     .number({ invalid_type_error: "Must be a number" })
-    .nonnegative("Price ≥ 0"),
+    .nonnegative("Price ≥ 0"),
 });
 
 const InvoiceSchema = z.object({
@@ -44,7 +44,7 @@ const InvoiceSchema = z.object({
 
 type FormErrors = Partial<Record<string, string>>;
 
-// ── Line item helpers ──────────────────────────────────────────────────────────
+// ── Line item helpers ──────────────────────────────────────────────────────────
 
 interface LineItemRow {
   id: string;
@@ -80,7 +80,7 @@ function computeTotals(
   return { subtotal, taxAmount, total };
 }
 
-// ── Props ──────────────────────────────────────────────────────────────────────
+// ── Props ──────────────────────────────────────────────────────────────────────
 
 interface InvoiceDrawerProps {
   open: boolean;
@@ -92,7 +92,7 @@ interface InvoiceDrawerProps {
   isLoading?: boolean;
 }
 
-// ── Component ──────────────────────────────────────────────────────────────────
+// ── Component ──────────────────────────────────────────────────────────────────
 
 export function InvoiceDrawer({
   open,
@@ -104,12 +104,12 @@ export function InvoiceDrawer({
 }: InvoiceDrawerProps) {
   const isEditing = !!invoice;
 
-  // ── Customer fields ──────────────────────────────────────────────────────────
+  // ── Customer fields ──────────────────────────────────────────────────────────
   const [customerEmail, setCustomerEmail] = useState(invoice?.customerEmail ?? "");
   const [customerName, setCustomerName] = useState(invoice?.customerName ?? "");
   const [invoiceNumber, setInvoiceNumber] = useState(invoice?.invoiceNumber ?? "");
 
-  // ── Line items ───────────────────────────────────────────────────────────────
+  // ── Line items ───────────────────────────────────────────────────────────────
   const [rows, setRows] = useState<LineItemRow[]>(() => {
     if (invoice?.lineItems?.length) {
       return invoice.lineItems.map((li) => ({
@@ -122,7 +122,7 @@ export function InvoiceDrawer({
     return [emptyRow()];
   });
 
-  // ── Pricing ──────────────────────────────────────────────────────────────────
+  // ── Pricing ──────────────────────────────────────────────────────────────────
   const [currency, setCurrency] = useState(invoice?.currency ?? "USD");
   const [taxRate, setTaxRate] = useState(
     invoice?.taxRate ? String(Number(invoice.taxRate) * 100) : "",
@@ -131,21 +131,21 @@ export function InvoiceDrawer({
     invoice?.discount ? String(Number(invoice.discount)) : "",
   );
 
-  // ── Meta ─────────────────────────────────────────────────────────────────────
+  // ── Meta ─────────────────────────────────────────────────────────────────────
   const [dueDate, setDueDate] = useState(
     invoice?.dueDate ? invoice.dueDate.split("T")[0] : "",
   );
   const [notes, setNotes] = useState(invoice?.notes ?? "");
 
-  // ── Errors ───────────────────────────────────────────────────────────────────
+  // ── Errors ───────────────────────────────────────────────────────────────────
   const [errors, setErrors] = useState<FormErrors>({});
 
-  // ── Computed totals ───────────────────────────────────────────────────────────
+  // ── Computed totals ───────────────────────────────────────────────────────────
   const taxRatePct = parseFloat(taxRate) || 0;
   const discountAmt = parseFloat(discount) || 0;
   const { subtotal, taxAmount, total } = computeTotals(rows, taxRatePct, discountAmt);
 
-  // ── Row handlers ──────────────────────────────────────────────────────────────
+  // ── Row handlers ──────────────────────────────────────────────────────────────
   const addRow = () => setRows((prev) => [...prev, emptyRow()]);
 
   const removeRow = useCallback((id: string) => {
@@ -166,7 +166,7 @@ export function InvoiceDrawer({
     [],
   );
 
-  // ── Validation ────────────────────────────────────────────────────────────────
+  // ── Validation ────────────────────────────────────────────────────────────────
   const validate = (): CreateInvoiceInput | null => {
     const lineItemsForValidation = rows.map(rowToItem);
 
@@ -259,7 +259,7 @@ export function InvoiceDrawer({
           </DialogDescription>
         </DialogHeader>
 
-        {/* ── Scrollable body ── */}
+        {/* ── Scrollable body ── */}
         <div className="flex-1 overflow-y-auto space-y-5 py-1 pr-1">
 
           {/* Client details */}
@@ -466,7 +466,7 @@ export function InvoiceDrawer({
               {discountAmt > 0 && (
                 <div className="flex justify-between text-muted-foreground">
                   <span>Discount</span>
-                  <span className="text-green-600">−{fmtCurrency(discountAmt)}</span>
+                  <span className="text-status-success-text">−{fmtCurrency(discountAmt)}</span>
                 </div>
               )}
               <Separator className="my-1" />
@@ -496,7 +496,7 @@ export function InvoiceDrawer({
               </Label>
               <textarea
                 id="inv-notes"
-                placeholder="Payment terms, thank you note, instructions…"
+                placeholder="Payment terms, thank you note, instructions…"
                 value={notes}
                 onChange={(e) => setNotes(e.target.value)}
                 rows={3}
@@ -506,7 +506,7 @@ export function InvoiceDrawer({
           </section>
         </div>
 
-        {/* ── Footer ── */}
+        {/* ── Footer ── */}
         <DialogFooter className="mt-4 gap-2 sm:gap-0">
           <Button
             type="button"
diff --git a/apps/dashboard/src/components/invoices/InvoicesTable.tsx b/apps/dashboard/src/components/invoices/InvoicesTable.tsx
index ae5b706..ad16032 100644
--- a/apps/dashboard/src/components/invoices/InvoicesTable.tsx
+++ b/apps/dashboard/src/components/invoices/InvoicesTable.tsx
@@ -1,4 +1,4 @@
-"use client";
+"use client";
 
 import { useState } from "react";
 import {
@@ -25,15 +25,15 @@ import {
 } from "@/components/ui/dropdown-menu";
 import type { Invoice, InvoiceStatus } from "@/hooks/useInvoices";
 
-// ── Status badge ───────────────────────────────────────────────────────────────
+// ── Status badge ───────────────────────────────────────────────────────────────
 
 const STATUS_CONFIG: Record<InvoiceStatus, { label: string; className: string }> = {
   DRAFT: { label: "Draft", className: "bg-muted text-muted-foreground" },
-  SENT: { label: "Sent", className: "bg-blue-100 text-blue-700 dark:bg-blue-900/40 dark:text-blue-300" },
-  VIEWED: { label: "Viewed", className: "bg-purple-100 text-purple-700 dark:bg-purple-900/40 dark:text-purple-300" },
-  PARTIALLY_PAID: { label: "Partial", className: "bg-amber-100 text-amber-700 dark:bg-amber-900/40 dark:text-amber-300" },
-  PAID: { label: "Paid", className: "bg-green-100 text-green-700 dark:bg-green-900/40 dark:text-green-300" },
-  OVERDUE: { label: "Overdue", className: "bg-red-100 text-red-700 dark:bg-red-900/40 dark:text-red-300" },
+  SENT: { label: "Sent", className: "bg-status-info-bg text-status-info-text" },
+  VIEWED: { label: "Viewed", className: "bg-status-purple-bg text-status-purple-text" },
+  PARTIALLY_PAID: { label: "Partial", className: "bg-status-amber-bg text-status-amber-text" },
+  PAID: { label: "Paid", className: "bg-status-success-bg text-status-success-text" },
+  OVERDUE: { label: "Overdue", className: "bg-status-error-bg text-status-error-text" },
   CANCELLED: { label: "Cancelled", className: "bg-muted text-muted-foreground line-through" },
 };
 
@@ -46,7 +46,7 @@ function StatusBadge({ status }: { status: InvoiceStatus }) {
   );
 }
 
-// ── Sort indicator ─────────────────────────────────────────────────────────────
+// ── Sort indicator ─────────────────────────────────────────────────────────────
 
 function SortIcon({ col, sortBy, sortOrder }: { col: string; sortBy?: string; sortOrder?: "asc" | "desc" }) {
   if (sortBy !== col) return <ChevronsUpDown className="h-3 w-3 opacity-40" />;
@@ -55,7 +55,7 @@ function SortIcon({ col, sortBy, sortOrder }: { col: string; sortBy?: string; so
     : <ChevronDown className="h-3 w-3" />;
 }
 
-// ── Skeleton row ───────────────────────────────────────────────────────────────
+// ── Skeleton row ───────────────────────────────────────────────────────────────
 
 function SkeletonRow() {
   return (
@@ -68,7 +68,7 @@ function SkeletonRow() {
   );
 }
 
-// ── Empty state ────────────────────────────────────────────────────────────────
+// ── Empty state ────────────────────────────────────────────────────────────────
 
 function EmptyState({ onCreate }: { onCreate: () => void }) {
   return (
@@ -89,7 +89,7 @@ function EmptyState({ onCreate }: { onCreate: () => void }) {
   );
 }
 
-// ── Props ──────────────────────────────────────────────────────────────────────
+// ── Props ──────────────────────────────────────────────────────────────────────
 
 interface InvoicesTableProps {
   invoices: Invoice[];
@@ -107,7 +107,7 @@ interface InvoicesTableProps {
   onCreate: () => void;
 }
 
-// ── Sortable header cell ──────────────────────────────────────────────────────
+// ── Sortable header cell ──────────────────────────────────────────────────────
 
 function SortableHeader({
   label,
@@ -135,7 +135,7 @@ function SortableHeader({
   );
 }
 
-// ── Main component ────────────────────────────────────────────────────────────
+// ── Main component ────────────────────────────────────────────────────────────
 
 export function InvoicesTable({
   invoices,
@@ -162,7 +162,7 @@ export function InvoicesTable({
   };
 
   const fmtDate = (iso?: string) => {
-    if (!iso) return "—";
+    if (!iso) return "—";
     return new Date(iso).toLocaleDateString("en-US", {
       year: "numeric",
       month: "short",
@@ -245,12 +245,12 @@ export function InvoicesTable({
                     {fmtCurrency(inv.total, inv.currency)}
                   </span>
                   {parseFloat(inv.amountPaid ?? "0") > 0 && inv.status !== "PAID" && (
-                    <span className="text-xs text-green-600">
+                    <span className="text-xs text-status-success-text">
                       +{fmtCurrency(inv.amountPaid, inv.currency)} paid
                     </span>
                   )}
                   {inv.status === "PARTIALLY_PAID" && (
-                    <span className="text-xs text-amber-600">
+                    <span className="text-xs text-status-amber-text">
                       {fmtCurrency(String(amountDue), inv.currency)} due
                     </span>
                   )}
@@ -262,7 +262,7 @@ export function InvoicesTable({
                 {/* Due date */}
                 <span
                   className={`text-sm tabular-nums ${
-                    inv.status === "OVERDUE" ? "text-red-600 font-medium" : "text-muted-foreground"
+                    inv.status === "OVERDUE" ? "text-status-error-text font-medium" : "text-muted-foreground"
                   }`}
                 >
                   {fmtDate(inv.dueDate)}
diff --git a/apps/dashboard/src/components/layout/Topbar.tsx b/apps/dashboard/src/components/layout/Topbar.tsx
index d844289..7d813b2 100644
--- a/apps/dashboard/src/components/layout/Topbar.tsx
+++ b/apps/dashboard/src/components/layout/Topbar.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Bell, Moon, Search, Sun, LogOut, Settings, User } from "lucide-react";
+import { Bell, Moon, Monitor, Search, Sun, LogOut, Settings, User } from "lucide-react";
 import { useTheme } from "@/providers/ThemeProvider";
 import { useAuth } from "@/providers/AuthProvider";
 import {
@@ -17,7 +17,7 @@ interface TopbarProps {
 }
 
 export function Topbar({ title }: TopbarProps) {
-  const { theme, toggleTheme } = useTheme();
+  const { preference, toggleTheme } = useTheme();
   const { merchant, logout } = useAuth();
 
   const initials = merchant?.name
@@ -47,11 +47,21 @@ export function Topbar({ title }: TopbarProps) {
         <button
           onClick={toggleTheme}
           className="rounded-md p-2 text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground"
+          aria-label={`Theme: ${preference}`}
+          title={
+            preference === "light"
+              ? "Light mode — click for dark"
+              : preference === "dark"
+                ? "Dark mode — click for system"
+                : "System mode — click for light"
+          }
         >
-          {theme === "dark" ? (
+          {preference === "dark" ? (
+            <Moon className="size-5" />
+          ) : preference === "light" ? (
             <Sun className="size-5" />
           ) : (
-            <Moon className="size-5" />
+            <Monitor className="size-5" />
           )}
         </button>
 
diff --git a/apps/dashboard/src/components/links/LinkCreatedModal.tsx b/apps/dashboard/src/components/links/LinkCreatedModal.tsx
index bef92d9..fbf060d 100644
--- a/apps/dashboard/src/components/links/LinkCreatedModal.tsx
+++ b/apps/dashboard/src/components/links/LinkCreatedModal.tsx
@@ -105,7 +105,7 @@ export function LinkCreatedModal({
             {/* QR Code Preview */}
             <div className="space-y-2">
               <Label>QR Code</Label>
-              <div className="flex items-center justify-center rounded-lg border border-[var(--border)] bg-white p-4">
+              <div className="flex items-center justify-center rounded-lg border border-[var(--border)] bg-card p-4">
                 <QRCodeSVG
                   value={linkUrl}
                   size={150}
diff --git a/apps/dashboard/src/components/links/QRCodeModal.tsx b/apps/dashboard/src/components/links/QRCodeModal.tsx
index d028b60..e7d8e98 100644
--- a/apps/dashboard/src/components/links/QRCodeModal.tsx
+++ b/apps/dashboard/src/components/links/QRCodeModal.tsx
@@ -79,7 +79,7 @@ export function QRCodeModal({ open, onOpenChange, url, linkName }: QRCodeModalPr
         </DialogHeader>
 
         <div className="flex flex-col items-center justify-center py-4">
-          <div className="rounded-lg border border-[var(--border)] bg-white p-4 shadow-sm">
+          <div className="rounded-lg border border-[var(--border)] bg-card p-4 shadow-sm">
             <QRCodeSVG
               value={url}
               size={200}
diff --git a/apps/dashboard/src/components/notifications/NotificationBell.tsx b/apps/dashboard/src/components/notifications/NotificationBell.tsx
new file mode 100644
index 0000000..971fa4f
--- /dev/null
+++ b/apps/dashboard/src/components/notifications/NotificationBell.tsx
@@ -0,0 +1,217 @@
+"use client";
+
+import { useMemo } from "react";
+import { formatDistanceToNowStrict } from "date-fns";
+import { useRouter } from "next/navigation";
+import {
+  Bell,
+  CheckCheck,
+  CreditCard,
+  ArrowLeftRight,
+  Receipt,
+  RotateCcw,
+  Users,
+  KeyRound,
+  Webhook,
+} from "lucide-react";
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  ScrollArea,
+  cn,
+} from "@useroutr/ui";
+import {
+  DashboardNotification,
+  useNotifications,
+} from "@/providers/NotificationsProvider";
+
+function getNotificationHref(notification: DashboardNotification): string {
+  const metadata = notification.metadata ?? {};
+
+  switch (notification.type) {
+    case "payment.received":
+      return typeof metadata.paymentId === "string"
+        ? `/payments/${metadata.paymentId}`
+        : "/payments";
+    case "invoice.paid":
+      return typeof metadata.invoiceId === "string"
+        ? `/invoices/${metadata.invoiceId}`
+        : "/invoices";
+    case "payout.completed":
+    case "payout.failed":
+      return "/payouts";
+    case "refund.initiated":
+      return "/refunds";
+    case "team.member_joined":
+      return "/settings/team";
+    case "api_key.created":
+      return "/settings/api-keys";
+    case "webhook.failed":
+      return "/settings/webhooks";
+    default:
+      return "/settings";
+  }
+}
+
+function NotificationTypeIcon({ type }: { type: string }) {
+  const className = "size-4";
+
+  switch (type) {
+    case "payment.received":
+      return <CreditCard className={cn(className, "text-emerald-500")} />;
+    case "invoice.paid":
+      return <Receipt className={cn(className, "text-blue")} />;
+    case "payout.completed":
+      return <ArrowLeftRight className={cn(className, "text-emerald-500")} />;
+    case "payout.failed":
+      return <ArrowLeftRight className={cn(className, "text-red")} />;
+    case "refund.initiated":
+      return <RotateCcw className={cn(className, "text-amber")} />;
+    case "team.member_joined":
+      return <Users className={cn(className, "text-purple")} />;
+    case "api_key.created":
+      return <KeyRound className={cn(className, "text-amber")} />;
+    case "webhook.failed":
+      return <Webhook className={cn(className, "text-red")} />;
+    default:
+      return <Bell className={cn(className, "text-primary")} />;
+  }
+}
+
+export function NotificationBell() {
+  const router = useRouter();
+  const {
+    notifications,
+    unreadCount,
+    isLoading,
+    highlightedIds,
+    markAsRead,
+    markAllAsRead,
+  } = useNotifications();
+
+  const unreadLabel = useMemo(() => {
+    if (unreadCount <= 0) {
+      return null;
+    }
+
+    return unreadCount > 9 ? "9+" : String(unreadCount);
+  }, [unreadCount]);
+
+  const handleNotificationClick = async (notification: DashboardNotification) => {
+    if (!notification.read) {
+      await markAsRead(notification.id);
+    }
+
+    router.push(getNotificationHref(notification));
+  };
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="relative h-8 w-8"
+          aria-label={`Notifications${unreadCount > 0 ? `, ${unreadCount} unread` : ""}`}
+        >
+          <Bell className="size-4" />
+          {unreadLabel ? (
+            <span className="absolute -right-1 -top-1 inline-flex min-w-5 items-center justify-center rounded-full bg-emerald-500 px-1.5 py-0.5 text-[10px] font-semibold text-white">
+              {unreadLabel}
+            </span>
+          ) : null}
+        </Button>
+      </DropdownMenuTrigger>
+
+      <DropdownMenuContent
+        align="end"
+        className="w-95 rounded-2xl border-border/70 bg-popover p-0 shadow-xl"
+      >
+        <div className="flex items-center justify-between border-b border-border/60 px-4 py-3">
+          <div>
+            <p className="text-sm font-semibold text-foreground">Notifications</p>
+            <p className="text-xs text-muted-foreground">
+              {unreadCount > 0
+                ? `${unreadCount} unread update${unreadCount === 1 ? "" : "s"}`
+                : "You’re all caught up"}
+            </p>
+          </div>
+
+          <button
+            type="button"
+            onClick={() => void markAllAsRead()}
+            disabled={unreadCount === 0}
+            className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs font-medium text-primary transition-colors hover:bg-primary/10 disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            <CheckCheck className="size-3.5" />
+            Mark all as read
+          </button>
+        </div>
+
+        <ScrollArea className="max-h-105">
+          <div className="p-2">
+            {!isLoading && notifications.length === 0 ? (
+              <div className="flex flex-col items-center justify-center px-6 py-10 text-center">
+                <div className="mb-3 rounded-full bg-secondary p-3 text-muted-foreground">
+                  <Bell className="size-5" />
+                </div>
+                <p className="text-sm font-medium text-foreground">No notifications yet</p>
+                <p className="mt-1 text-xs text-muted-foreground">
+                  New payment, payout, invoice, and webhook activity will appear here.
+                </p>
+              </div>
+            ) : (
+              notifications.map((notification) => (
+                <button
+                  key={notification.id}
+                  type="button"
+                  onClick={() => void handleNotificationClick(notification)}
+                  className={cn(
+                    "mb-1 flex w-full items-start gap-3 rounded-xl border px-3 py-3 text-left transition-all duration-200 hover:border-border hover:bg-secondary/50 focus:outline-none focus:ring-2 focus:ring-ring",
+                    notification.read
+                      ? "border-transparent bg-transparent"
+                      : "border-primary/10 bg-primary/5",
+                    highlightedIds.has(notification.id) &&
+                      "border-emerald-400/40 bg-emerald-500/10",
+                  )}
+                >
+                  <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-secondary">
+                    <NotificationTypeIcon type={notification.type} />
+                  </div>
+
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-start justify-between gap-2">
+                      <p
+                        className={cn(
+                          "truncate text-sm text-foreground",
+                          !notification.read && "font-semibold",
+                        )}
+                      >
+                        {notification.title}
+                      </p>
+                      {!notification.read ? (
+                        <span className="mt-1 h-2 w-2 shrink-0 rounded-full bg-emerald-500" />
+                      ) : null}
+                    </div>
+
+                    <p className="mt-0.5 line-clamp-2 text-xs text-muted-foreground">
+                      {notification.body}
+                    </p>
+
+                    <p className="mt-2 text-[11px] text-muted-foreground">
+                      {formatDistanceToNowStrict(new Date(notification.createdAt), {
+                        addSuffix: true,
+                      })}
+                    </p>
+                  </div>
+                </button>
+              ))
+            )}
+          </div>
+        </ScrollArea>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
diff --git a/apps/dashboard/src/components/overview/GreetingHeader.tsx b/apps/dashboard/src/components/overview/GreetingHeader.tsx
index cfa9caf..ff07688 100644
--- a/apps/dashboard/src/components/overview/GreetingHeader.tsx
+++ b/apps/dashboard/src/components/overview/GreetingHeader.tsx
@@ -1,4 +1,4 @@
-"use client";
+"use client";
 
 import { useMemo } from "react";
 import { motion } from "framer-motion";
diff --git a/apps/dashboard/src/components/payments/PaymentDetailDrawer.tsx b/apps/dashboard/src/components/payments/PaymentDetailDrawer.tsx
index 4137d5c..afb5dd9 100644
--- a/apps/dashboard/src/components/payments/PaymentDetailDrawer.tsx
+++ b/apps/dashboard/src/components/payments/PaymentDetailDrawer.tsx
@@ -1,10 +1,17 @@
 "use client";
 
-import { Drawer } from "@useroutr/ui";
+import { useState } from "react";
+import { Drawer, Button } from "@useroutr/ui";
+import { ArrowCounterClockwise } from "@phosphor-icons/react";
 import { type Payment } from "@/hooks/usePayments";
+import { usePaymentRefunds } from "@/hooks/useRefunds";
 import { StatusBadge } from "./StatusBadge";
+import { RefundStatusBadge, type RefundBadgeStatus } from "./RefundStatusBadge";
+import { RefundModal } from "./RefundModal";
+import { RefundTimeline } from "./RefundTimeline";
 import { formatCurrency, truncateAddress } from "@/lib/utils";
 import { PaymentTimeline } from "./PaymentTimeline";
+import { canRefund, getRefundEta, getPaymentMethodLabel } from "@/lib/refund";
 
 interface PaymentDetailDrawerProps {
   payment?: Payment;
@@ -17,102 +24,214 @@ export function PaymentDetailDrawer({
   open,
   onOpenChange,
 }: PaymentDetailDrawerProps) {
+  const [refundModalOpen, setRefundModalOpen] = useState(false);
+
+  // Fetch refunds for this payment when drawer is open
+  const { data: refunds } = usePaymentRefunds(payment?.id ?? "");
+
   if (!payment) return null;
 
   const amount = Number(payment.amount);
+  const showRefundButton = canRefund(payment.status, payment.completedAt, payment.refundedAt);
+
+  // Determine refund badge status
+  const refundBadgeStatus: RefundBadgeStatus | null =
+    payment.status === "REFUNDING"
+      ? "REFUNDING"
+      : payment.status === "REFUNDED"
+        ? "REFUNDED"
+        : refunds && refunds.length > 0 && payment.status === "COMPLETED"
+          ? "PARTIAL_REFUND"
+          : null;
 
   return (
-    <Drawer
-      open={open}
-      onOpenChange={onOpenChange}
-      title={`Payment ${payment.id.slice(0, 8)}...`}
-      description="Transaction details and timeline"
-    >
-      <div className="space-y-6">
-        {/* Summary */}
-        <div className="space-y-4 border-b border-border pb-6">
-          <div className="flex items-center justify-between">
-            <span className="text-sm text-muted-foreground">Amount</span>
-            <span className="font-semibold text-foreground">
-              {formatCurrency(amount, payment.currency)}
-            </span>
-          </div>
-          <div className="flex items-center justify-between">
-            <span className="text-sm text-muted-foreground">Status</span>
-            <StatusBadge status={payment.status} />
-          </div>
-          <div className="flex items-center justify-between">
-            <span className="text-sm text-muted-foreground">Created</span>
-            <span className="text-sm text-foreground">
-              {new Date(payment.createdAt).toLocaleDateString()} at{" "}
-              {new Date(payment.createdAt).toLocaleTimeString()}
-            </span>
-          </div>
-          {payment.completedAt && (
+    <>
+      <Drawer
+        open={open}
+        onOpenChange={onOpenChange}
+        title={`Payment ${payment.id.slice(0, 8)}...`}
+        description="Transaction details and timeline"
+      >
+        <div className="space-y-6">
+          {/* Summary */}
+          <div className="space-y-4 border-b border-border pb-6">
+            <div className="flex items-center justify-between">
+              <span className="text-sm text-muted-foreground">Amount</span>
+              <span className="font-semibold text-foreground">
+                {formatCurrency(amount, payment.currency)}
+              </span>
+            </div>
+            <div className="flex items-center justify-between">
+              <span className="text-sm text-muted-foreground">Status</span>
+              <div className="flex items-center gap-2">
+                <StatusBadge status={payment.status} />
+                {refundBadgeStatus && (
+                  <RefundStatusBadge status={refundBadgeStatus} />
+                )}
+              </div>
+            </div>
             <div className="flex items-center justify-between">
-              <span className="text-sm text-muted-foreground">Completed</span>
+              <span className="text-sm text-muted-foreground">Created</span>
               <span className="text-sm text-foreground">
-                {new Date(payment.completedAt).toLocaleDateString()} at{" "}
-                {new Date(payment.completedAt).toLocaleTimeString()}
+                {new Date(payment.createdAt).toLocaleDateString()} at{" "}
+                {new Date(payment.createdAt).toLocaleTimeString()}
               </span>
             </div>
+            {payment.completedAt && (
+              <div className="flex items-center justify-between">
+                <span className="text-sm text-muted-foreground">Completed</span>
+                <span className="text-sm text-foreground">
+                  {new Date(payment.completedAt).toLocaleDateString()} at{" "}
+                  {new Date(payment.completedAt).toLocaleTimeString()}
+                </span>
+              </div>
+            )}
+            {payment.refundedAt && (
+              <div className="flex items-center justify-between">
+                <span className="text-sm text-muted-foreground">Refunded</span>
+                <span className="text-sm text-foreground">
+                  {new Date(payment.refundedAt).toLocaleDateString()} at{" "}
+                  {new Date(payment.refundedAt).toLocaleTimeString()}
+                </span>
+              </div>
+            )}
+          </div>
+
+          {/* Refund action */}
+          {showRefundButton && (
+            <div className="border-b border-border pb-6">
+              <Button
+                variant="destructive"
+                size="sm"
+                className="w-full"
+                onClick={() => setRefundModalOpen(true)}
+              >
+                <ArrowCounterClockwise size={16} weight="bold" />
+                Issue Refund
+              </Button>
+            </div>
           )}
-        </div>
 
-        {/* Route */}
-        <div className="space-y-3">
-          <h3 className="text-sm font-semibold text-foreground">Route</h3>
+          {/* Refund detail section (if refunds exist) */}
+          {refunds && refunds.length > 0 && (
+            <div className="space-y-3 border-b border-border pb-6">
+              <h3 className="text-sm font-semibold text-foreground">
+                Refund Details
+              </h3>
+              {refunds.map((refund) => (
+                <div
+                  key={refund.id}
+                  className="rounded-lg border border-border bg-(--secondary)/20 p-3 space-y-2"
+                >
+                  <div className="flex justify-between text-sm">
+                    <span className="text-muted-foreground">Amount</span>
+                    <span className="font-semibold text-foreground">
+                      {formatCurrency(refund.amount, payment.currency)}
+                    </span>
+                  </div>
+                  <div className="flex justify-between text-sm">
+                    <span className="text-muted-foreground">Status</span>
+                    <span className="text-foreground capitalize">
+                      {refund.status.toLowerCase()}
+                    </span>
+                  </div>
+                  <div className="flex justify-between text-sm">
+                    <span className="text-muted-foreground">Est. Delivery</span>
+                    <span className="text-foreground">
+                      {getRefundEta(payment.sourceChain)} ({getPaymentMethodLabel(payment.sourceChain)})
+                    </span>
+                  </div>
+                  {refund.notes && (
+                    <div className="flex justify-between text-sm">
+                      <span className="text-muted-foreground">Notes</span>
+                      <span className="max-w-45 text-right text-foreground">
+                        {refund.notes}
+                      </span>
+                    </div>
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Route */}
           <div className="space-y-3">
-            <div className="rounded-lg border border-border bg-(--secondary)/20 p-3">
-              <p className="text-xs font-medium text-muted-foreground">
-                Source
-              </p>
-              <p className="mt-1 text-sm font-semibold text-foreground">
-                {payment.sourceAsset} on {payment.sourceChain}
-              </p>
-              {payment.sourceAddress && (
-                <p className="mt-1 text-xs text-muted-foreground">
-                  {truncateAddress(payment.sourceAddress)}
+            <h3 className="text-sm font-semibold text-foreground">Route</h3>
+            <div className="space-y-3">
+              <div className="rounded-lg border border-border bg-(--secondary)/20 p-3">
+                <p className="text-xs font-medium text-muted-foreground">
+                  Source
                 </p>
-              )}
-              <p className="mt-1 text-sm text-foreground">
-                {Number(payment.sourceAmount).toFixed(6)}
-              </p>
-            </div>
+                <p className="mt-1 text-sm font-semibold text-foreground">
+                  {payment.sourceAsset} on {payment.sourceChain}
+                </p>
+                {payment.sourceAddress && (
+                  <p className="mt-1 text-xs text-muted-foreground">
+                    {truncateAddress(payment.sourceAddress)}
+                  </p>
+                )}
+                <p className="mt-1 text-sm text-foreground">
+                  {Number(payment.sourceAmount).toFixed(6)}
+                </p>
+              </div>
 
-            <div className="flex justify-center">
-              <div className="rounded-full bg-(--primary)/20 p-2">
-                <div className="text-xs font-semibold text-primary">
-                  ↓
+              <div className="flex justify-center">
+                <div className="rounded-full bg-(--primary)/20 p-2">
+                  <div className="text-xs font-semibold text-primary">
+                    ↓
+                  </div>
                 </div>
               </div>
-            </div>
 
-            <div className="rounded-lg border border-border bg-(--accent)/20 p-3">
-              <p className="text-xs font-medium text-muted-foreground">
-                Destination
-              </p>
-              <p className="mt-1 text-sm font-semibold text-foreground">
-                {payment.destAsset} on {payment.destChain}
-              </p>
-              <p className="mt-1 text-xs text-muted-foreground">
-                {truncateAddress(payment.destAddress)}
-              </p>
-              <p className="mt-1 text-sm text-foreground">
-                {Number(payment.destAmount).toFixed(6)}
-              </p>
+              <div className="rounded-lg border border-border bg-(--accent)/20 p-3">
+                <p className="text-xs font-medium text-muted-foreground">
+                  Destination
+                </p>
+                <p className="mt-1 text-sm font-semibold text-foreground">
+                  {payment.destAsset} on {payment.destChain}
+                </p>
+                <p className="mt-1 text-xs text-muted-foreground">
+                  {truncateAddress(payment.destAddress)}
+                </p>
+                <p className="mt-1 text-sm text-foreground">
+                  {Number(payment.destAmount).toFixed(6)}
+                </p>
+              </div>
             </div>
           </div>
-        </div>
 
-        {/* Timeline */}
-        <div>
-          <h3 className="mb-4 text-sm font-semibold text-foreground">
-            Timeline
-          </h3>
-          <PaymentTimeline payment={payment} />
+          {/* Timeline */}
+          <div>
+            <h3 className="mb-4 text-sm font-semibold text-foreground">
+              Timeline
+            </h3>
+            <PaymentTimeline payment={payment} />
+
+            {/* Refund timeline events */}
+            {refunds && refunds.length > 0 && (
+              <div className="mt-4 border-t border-border pt-4">
+                <h4 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                  Refund Activity
+                </h4>
+                <RefundTimeline
+                  refunds={refunds}
+                  currency={payment.currency}
+                  sourceChain={payment.sourceChain}
+                />
+              </div>
+            )}
+          </div>
         </div>
-      </div>
-    </Drawer>
+      </Drawer>
+
+      {/* Refund Modal */}
+      {showRefundButton && (
+        <RefundModal
+          payment={payment}
+          open={refundModalOpen}
+          onOpenChange={setRefundModalOpen}
+        />
+      )}
+    </>
   );
 }
\ No newline at end of file
diff --git a/apps/dashboard/src/components/payments/PaymentTimeline.tsx b/apps/dashboard/src/components/payments/PaymentTimeline.tsx
index 9339bf1..5ba8971 100644
--- a/apps/dashboard/src/components/payments/PaymentTimeline.tsx
+++ b/apps/dashboard/src/components/payments/PaymentTimeline.tsx
@@ -88,8 +88,7 @@ export function PaymentTimeline({ payment }: PaymentTimelineProps) {
         // Special case for failed/expired/refunded statuses
         if (
           payment.status === "FAILED" ||
-          payment.status === "EXPIRED" ||
-          payment.status === "REFUNDED"
+          payment.status === "EXPIRED"
         ) {
           return (
             <div key={step.status} className="flex gap-3">
@@ -103,15 +102,38 @@ export function PaymentTimeline({ payment }: PaymentTimelineProps) {
                   {step.label}
                 </p>
                 <p className="text-xs text-muted-foreground">
-                  {payment.status === "REFUNDED"
-                    ? "Payment refunded"
-                    : "Payment failed or expired"}
+                  Payment failed or expired
                 </p>
               </div>
             </div>
           );
         }
 
+        // Show completed flow for REFUNDED/REFUNDING (these went through COMPLETED first)
+        if (
+          payment.status === "REFUNDED" ||
+          payment.status === "REFUNDING"
+        ) {
+          return (
+            <div key={step.status} className="flex gap-3">
+              <div className="flex flex-col items-center">
+                <div className="rounded-full p-2 bg-(--primary)/20 text-primary">
+                  <CheckCircle size={16} weight="bold" />
+                </div>
+                {index < TIMELINE_STEPS.length - 1 && (
+                  <div className="my-1 h-8 w-0.5 bg-primary" />
+                )}
+              </div>
+              <div className="pt-1">
+                <p className="text-sm font-medium text-foreground">
+                  {step.label}
+                </p>
+                <p className="text-xs text-muted-foreground">Completed</p>
+              </div>
+            </div>
+          );
+        }
+
         return (
           <div key={step.status} className="flex gap-3">
             <div className="flex flex-col items-center">
diff --git a/apps/dashboard/src/components/payments/RefundHistoryTable.tsx b/apps/dashboard/src/components/payments/RefundHistoryTable.tsx
new file mode 100644
index 0000000..33cdcfc
--- /dev/null
+++ b/apps/dashboard/src/components/payments/RefundHistoryTable.tsx
@@ -0,0 +1,172 @@
+"use client";
+
+import { useState, useMemo } from "react";
+import { useRefunds } from "@/hooks/useRefunds";
+import { DataTable, Pagination, Badge, type Column } from "@useroutr/ui";
+import { formatCurrency } from "@/lib/utils";
+import { REFUND_REASONS, type Refund, type RefundStatus } from "@/lib/refund";
+
+type RefundWithIndex = Refund & Record<string, unknown>;
+
+const STATUS_FILTER_OPTIONS = [
+  { value: "", label: "All" },
+  { value: "PENDING", label: "Pending" },
+  { value: "PROCESSING", label: "Processing" },
+  { value: "COMPLETED", label: "Completed" },
+  { value: "FAILED", label: "Failed" },
+];
+
+const BADGE_VARIANT: Record<RefundStatus, "pending" | "processing" | "completed" | "failed"> = {
+  PENDING: "pending",
+  PROCESSING: "processing",
+  COMPLETED: "completed",
+  FAILED: "failed",
+};
+
+const BADGE_LABEL: Record<RefundStatus, string> = {
+  PENDING: "Pending",
+  PROCESSING: "Processing",
+  COMPLETED: "Completed",
+  FAILED: "Failed",
+};
+
+export function RefundHistoryTable() {
+  const [page, setPage] = useState(1);
+  const [limit, setLimit] = useState(10);
+  const [statusFilter, setStatusFilter] = useState<string>("");
+  const [sortColumn, setSortColumn] = useState("createdAt");
+  const [sortDirection, setSortDirection] = useState<"asc" | "desc">("desc");
+
+  const { data, isLoading } = useRefunds({
+    page,
+    limit,
+    status: statusFilter || undefined,
+    sortBy: sortColumn,
+    sortOrder: sortDirection,
+  });
+
+  const refunds = data?.data ?? [];
+  const totalRefunds = data?.total ?? 0;
+  const totalPages = Math.ceil(totalRefunds / limit);
+
+  const handleSort = (column: string, direction: "asc" | "desc") => {
+    setSortColumn(column);
+    setSortDirection(direction);
+  };
+
+  const columns: Column<RefundWithIndex>[] = useMemo(
+    () => [
+      {
+        key: "paymentId",
+        header: "Payment ID",
+        sortable: false,
+        render: (refund) => (
+          <span className="font-mono text-xs">{refund.paymentId.slice(0, 8)}…</span>
+        ),
+      },
+      {
+        key: "amount",
+        header: "Refund Amount",
+        sortable: true,
+        render: (refund) => (
+          <span className="font-semibold">
+            {formatCurrency(refund.amount, "USD")}
+          </span>
+        ),
+      },
+      {
+        key: "reason",
+        header: "Reason",
+        sortable: false,
+        render: (refund) =>
+          REFUND_REASONS.find((r) => r.value === refund.reason)?.label ?? refund.reason,
+      },
+      {
+        key: "status",
+        header: "Status",
+        sortable: true,
+        render: (refund) => (
+          <Badge variant={BADGE_VARIANT[refund.status]}>
+            {BADGE_LABEL[refund.status]}
+          </Badge>
+        ),
+      },
+      {
+        key: "createdAt",
+        header: "Initiated",
+        sortable: true,
+        render: (refund) =>
+          new Date(refund.createdAt).toLocaleDateString("en-US", {
+            month: "short",
+            day: "numeric",
+            year: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+          }),
+      },
+      {
+        key: "completedAt",
+        header: "Completed",
+        sortable: true,
+        render: (refund) =>
+          refund.completedAt
+            ? new Date(refund.completedAt).toLocaleDateString("en-US", {
+                month: "short",
+                day: "numeric",
+                year: "numeric",
+                hour: "2-digit",
+                minute: "2-digit",
+              })
+            : "—",
+      },
+    ],
+    [],
+  );
+
+  return (
+    <div className="space-y-4">
+      {/* Filter bar */}
+      <div className="flex items-center gap-2">
+        {STATUS_FILTER_OPTIONS.map((opt) => (
+          <button
+            key={opt.value}
+            onClick={() => {
+              setStatusFilter(opt.value);
+              setPage(1);
+            }}
+            className={`rounded-sm px-3 py-1.5 text-xs font-medium transition-colors ${
+              statusFilter === opt.value
+                ? "bg-primary text-primary-foreground"
+                : "bg-secondary text-muted-foreground hover:text-foreground"
+            }`}
+          >
+            {opt.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Table */}
+      <DataTable<RefundWithIndex>
+        columns={columns}
+        data={refunds as RefundWithIndex[]}
+        isLoading={isLoading}
+        loadingRows={limit}
+        emptyMessage="No refunds found"
+        sortColumn={sortColumn}
+        sortDirection={sortDirection}
+        onSort={handleSort}
+      />
+
+      {/* Pagination */}
+      <Pagination
+        page={page}
+        totalPages={totalPages}
+        totalItems={totalRefunds}
+        pageSize={limit}
+        onPageChange={setPage}
+        onPageSizeChange={setLimit}
+        pageSizeOptions={[10, 25, 50]}
+      />
+    </div>
+  );
+}
diff --git a/apps/dashboard/src/components/payments/RefundModal.tsx b/apps/dashboard/src/components/payments/RefundModal.tsx
new file mode 100644
index 0000000..5423476
--- /dev/null
+++ b/apps/dashboard/src/components/payments/RefundModal.tsx
@@ -0,0 +1,329 @@
+"use client";
+
+import { useState, useCallback, useMemo } from "react";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+  Button,
+  Input,
+  Select,
+  Textarea,
+  useToast,
+} from "@useroutr/ui";
+import { Info, Warning, ArrowLeft } from "@phosphor-icons/react";
+import { type Payment } from "@/hooks/usePayments";
+import { useCreateRefund } from "@/hooks/useRefunds";
+import {
+  REFUND_REASONS,
+  getRefundEta,
+  getPaymentMethodLabel,
+  refundWindowDaysRemaining,
+} from "@/lib/refund";
+import { formatCurrency } from "@/lib/utils";
+
+type RefundType = "full" | "partial";
+type Step = "form" | "confirm";
+
+interface RefundModalProps {
+  payment: Payment;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+const REASON_OPTIONS = REFUND_REASONS.map((r) => ({
+  value: r.value,
+  label: r.label,
+}));
+
+const NOTES_MAX_LENGTH = 500;
+
+export function RefundModal({ payment, open, onOpenChange }: RefundModalProps) {
+  const { toast } = useToast();
+  const createRefund = useCreateRefund();
+
+  const fullAmount = Number(payment.amount);
+  const currency = payment.currency;
+
+  // ── Form state ───────────────────────────────────────────────────────────────
+  const [step, setStep] = useState<Step>("form");
+  const [refundType, setRefundType] = useState<RefundType>("full");
+  const [amountStr, setAmountStr] = useState(String(fullAmount));
+  const [reason, setReason] = useState("");
+  const [notes, setNotes] = useState("");
+
+  // ── Derived ──────────────────────────────────────────────────────────────────
+  const amount = Number(amountStr);
+  const daysRemaining = refundWindowDaysRemaining(payment.completedAt);
+  const methodLabel = getPaymentMethodLabel(payment.sourceChain);
+  const eta = getRefundEta(payment.sourceChain);
+
+  // ── Validation ───────────────────────────────────────────────────────────────
+  const amountError = useMemo(() => {
+    if (refundType === "full") return undefined;
+    if (!amountStr || isNaN(amount)) return "Enter a valid amount";
+    if (amount <= 0) return "Amount must be greater than zero";
+    if (amount > fullAmount)
+      return `Cannot exceed ${formatCurrency(fullAmount, currency)}`;
+    return undefined;
+  }, [refundType, amountStr, amount, fullAmount, currency]);
+
+  const canSubmit = reason !== "" && !amountError && amount > 0;
+
+  // ── Handlers ─────────────────────────────────────────────────────────────────
+  const reset = useCallback(() => {
+    setStep("form");
+    setRefundType("full");
+    setAmountStr(String(fullAmount));
+    setReason("");
+    setNotes("");
+  }, [fullAmount]);
+
+  const handleOpenChange = useCallback(
+    (next: boolean) => {
+      if (!next) reset();
+      onOpenChange(next);
+    },
+    [onOpenChange, reset],
+  );
+
+  const handleTypeToggle = (type: RefundType) => {
+    setRefundType(type);
+    if (type === "full") setAmountStr(String(fullAmount));
+  };
+
+  const handleConfirm = async () => {
+    try {
+      await createRefund.mutateAsync({
+        paymentId: payment.id,
+        amount: refundType === "full" ? fullAmount : amount,
+        reason,
+        notes: notes.trim() || undefined,
+      });
+      toast("Refund initiated successfully", "success");
+      handleOpenChange(false);
+    } catch (err) {
+      toast(
+        err instanceof Error ? err.message : "Failed to create refund",
+        "error",
+      );
+    }
+  };
+
+  // ── Render ───────────────────────────────────────────────────────────────────
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="max-w-md">
+        {step === "form" ? (
+          <>
+            <DialogHeader>
+              <DialogTitle>Refund Payment</DialogTitle>
+              <DialogDescription>
+                Issue a refund for payment{" "}
+                <span className="font-mono">{payment.id.slice(0, 8)}…</span>
+              </DialogDescription>
+            </DialogHeader>
+
+            <div className="space-y-5 py-2">
+              {/* Refund type toggle */}
+              <div className="space-y-1.5">
+                <label className="block text-sm font-medium text-foreground">
+                  Refund Type
+                </label>
+                <div className="flex rounded-md border border-border p-0.5">
+                  {(["full", "partial"] as const).map((type) => (
+                    <button
+                      key={type}
+                      type="button"
+                      onClick={() => handleTypeToggle(type)}
+                      className={`flex-1 rounded-sm px-4 py-2 text-sm font-medium transition-colors ${
+                        refundType === type
+                          ? "bg-primary text-primary-foreground"
+                          : "text-muted-foreground hover:text-foreground"
+                      }`}
+                    >
+                      {type === "full" ? "Full Refund" : "Partial Refund"}
+                    </button>
+                  ))}
+                </div>
+              </div>
+
+              {/* Amount */}
+              <Input
+                id="refund-amount"
+                label="Refund Amount"
+                type="number"
+                step="0.01"
+                min={0}
+                max={fullAmount}
+                value={amountStr}
+                onChange={(e) => setAmountStr(e.target.value)}
+                readOnly={refundType === "full"}
+                error={amountError}
+                helperText={
+                  refundType === "full"
+                    ? "Full amount will be refunded"
+                    : `Max ${formatCurrency(fullAmount, currency)}`
+                }
+              />
+
+              {/* Reason */}
+              <Select
+                label="Reason"
+                placeholder="Select a reason…"
+                options={REASON_OPTIONS}
+                value={reason}
+                onValueChange={setReason}
+                error={reason === "" ? undefined : undefined}
+              />
+
+              {/* Notes */}
+              <div className="space-y-1.5">
+                <Textarea
+                  id="refund-notes"
+                  label="Notes (optional)"
+                  placeholder="Additional context for this refund…"
+                  value={notes}
+                  onChange={(e) => {
+                    if (e.target.value.length <= NOTES_MAX_LENGTH)
+                      setNotes(e.target.value);
+                  }}
+                  rows={3}
+                />
+                <p className="text-right text-xs text-muted-foreground">
+                  {notes.length}/{NOTES_MAX_LENGTH}
+                </p>
+              </div>
+
+              {/* Refund rules */}
+              <div className="rounded-md border border-border bg-(--blue)/5 p-3">
+                <div className="mb-2 flex items-center gap-1.5 text-sm font-medium text-blue">
+                  <Info size={16} weight="bold" /> Refund Rules
+                </div>
+                <ul className="space-y-1 text-xs text-muted-foreground">
+                  <li>• Refunds allowed up to 180 days ({daysRemaining} days remaining)</li>
+                  <li>• Partial refunds are supported</li>
+                  <li>• Crypto network fees may be deducted</li>
+                  <li>
+                    • Estimated delivery:{" "}
+                    <span className="font-medium text-foreground">{eta}</span>{" "}
+                    ({methodLabel})
+                  </li>
+                </ul>
+              </div>
+            </div>
+
+            <DialogFooter>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => handleOpenChange(false)}
+              >
+                Cancel
+              </Button>
+              <Button
+                variant="primary"
+                size="sm"
+                disabled={!canSubmit}
+                onClick={() => setStep("confirm")}
+              >
+                Review Refund
+              </Button>
+            </DialogFooter>
+          </>
+        ) : (
+          <>
+            <DialogHeader>
+              <DialogTitle>Confirm Refund</DialogTitle>
+              <DialogDescription>
+                Please review the refund details before submitting.
+              </DialogDescription>
+            </DialogHeader>
+
+            <div className="space-y-4 py-2">
+              {/* Summary table */}
+              <div className="space-y-3 rounded-md border border-border p-4">
+                <div className="flex justify-between text-sm">
+                  <span className="text-muted-foreground">Payment</span>
+                  <span className="font-mono text-foreground">
+                    {payment.id.slice(0, 8)}…
+                  </span>
+                </div>
+                <div className="flex justify-between text-sm">
+                  <span className="text-muted-foreground">Refund Amount</span>
+                  <span className="font-semibold text-foreground">
+                    {formatCurrency(
+                      refundType === "full" ? fullAmount : amount,
+                      currency,
+                    )}
+                  </span>
+                </div>
+                <div className="flex justify-between text-sm">
+                  <span className="text-muted-foreground">Type</span>
+                  <span className="text-foreground">
+                    {refundType === "full" ? "Full Refund" : "Partial Refund"}
+                  </span>
+                </div>
+                <div className="flex justify-between text-sm">
+                  <span className="text-muted-foreground">Reason</span>
+                  <span className="text-foreground">
+                    {REFUND_REASONS.find((r) => r.value === reason)?.label}
+                  </span>
+                </div>
+                {notes.trim() && (
+                  <div className="flex justify-between text-sm">
+                    <span className="text-muted-foreground">Notes</span>
+                    <span className="max-w-50 text-right text-foreground">
+                      {notes.trim()}
+                    </span>
+                  </div>
+                )}
+                <div className="flex justify-between text-sm">
+                  <span className="text-muted-foreground">Est. Delivery</span>
+                  <span className="text-foreground">
+                    {eta} ({methodLabel})
+                  </span>
+                </div>
+              </div>
+
+              {/* Warning notice */}
+              <div className="rounded-md border border-(--amber)/30 bg-(--amber)/5 p-3">
+                <div className="mb-1.5 flex items-center gap-1.5 text-sm font-medium text-amber">
+                  <Warning size={16} weight="bold" /> Important
+                </div>
+                <p className="text-xs leading-relaxed text-muted-foreground">
+                  This refund will be processed immediately. The customer may receive
+                  funds within {eta} depending on payment method. Crypto network fees
+                  may be deducted and this action may not be reversible.
+                </p>
+              </div>
+            </div>
+
+            <DialogFooter>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setStep("form")}
+                disabled={createRefund.isPending}
+              >
+                <ArrowLeft size={14} />
+                Back
+              </Button>
+              <Button
+                variant="destructive"
+                size="sm"
+                loading={createRefund.isPending}
+                onClick={handleConfirm}
+              >
+                Confirm Refund
+              </Button>
+            </DialogFooter>
+          </>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/apps/dashboard/src/components/payments/RefundStatusBadge.tsx b/apps/dashboard/src/components/payments/RefundStatusBadge.tsx
new file mode 100644
index 0000000..d4244b7
--- /dev/null
+++ b/apps/dashboard/src/components/payments/RefundStatusBadge.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+import { Badge } from "@useroutr/ui";
+
+export type RefundBadgeStatus = "REFUNDING" | "REFUNDED" | "PARTIAL_REFUND";
+
+const VARIANT_MAP: Record<RefundBadgeStatus, "pending" | "completed" | "processing"> = {
+  REFUNDING: "pending",
+  REFUNDED: "completed",
+  PARTIAL_REFUND: "processing",
+};
+
+const LABEL_MAP: Record<RefundBadgeStatus, string> = {
+  REFUNDING: "Refund Pending",
+  REFUNDED: "Refunded",
+  PARTIAL_REFUND: "Partial Refund",
+};
+
+interface RefundStatusBadgeProps {
+  status: RefundBadgeStatus;
+}
+
+export function RefundStatusBadge({ status }: RefundStatusBadgeProps) {
+  return <Badge variant={VARIANT_MAP[status]}>{LABEL_MAP[status]}</Badge>;
+}
diff --git a/apps/dashboard/src/components/payments/RefundTimeline.tsx b/apps/dashboard/src/components/payments/RefundTimeline.tsx
new file mode 100644
index 0000000..feee825
--- /dev/null
+++ b/apps/dashboard/src/components/payments/RefundTimeline.tsx
@@ -0,0 +1,157 @@
+"use client";
+
+import type { Refund } from "@/lib/refund";
+import { REFUND_REASONS, getRefundEta } from "@/lib/refund";
+import { formatCurrency } from "@/lib/utils";
+import {
+  ArrowCounterClockwise,
+  ArrowsClockwise,
+  CheckCircle,
+  XCircle,
+  Clock,
+} from "@phosphor-icons/react";
+
+interface RefundTimelineProps {
+  refunds: Refund[];
+  currency: string;
+  sourceChain: string;
+}
+
+const STATUS_ICON: Record<string, React.ReactNode> = {
+  PENDING: <Clock size={16} weight="bold" />,
+  PROCESSING: <ArrowsClockwise size={16} weight="bold" />,
+  COMPLETED: <CheckCircle size={16} weight="bold" />,
+  FAILED: <XCircle size={16} weight="bold" />,
+};
+
+const STATUS_COLOR: Record<string, string> = {
+  PENDING: "bg-[var(--amber)]/15 text-[var(--amber)]",
+  PROCESSING: "bg-[var(--blue)]/15 text-[var(--blue)]",
+  COMPLETED: "bg-[var(--green)]/15 text-[var(--green)]",
+  FAILED: "bg-[var(--red)]/15 text-[var(--red)]",
+};
+
+const STATUS_LINE_COLOR: Record<string, string> = {
+  PENDING: "bg-[var(--amber)]",
+  PROCESSING: "bg-[var(--blue)]",
+  COMPLETED: "bg-[var(--green)]",
+  FAILED: "bg-[var(--red)]",
+};
+
+function formatTimestamp(dateStr: string) {
+  const d = new Date(dateStr);
+  return `${d.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+  })} at ${d.toLocaleTimeString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+  })}`;
+}
+
+export function RefundTimeline({ refunds, currency, sourceChain }: RefundTimelineProps) {
+  if (!refunds.length) return null;
+
+  const eta = getRefundEta(sourceChain);
+
+  // Build timeline events from refunds
+  const events = refunds.flatMap((refund) => {
+    const items: Array<{
+      key: string;
+      icon: React.ReactNode;
+      color: string;
+      lineColor: string;
+      label: string;
+      detail: string;
+      timestamp: string;
+    }> = [];
+
+    // Initiated
+    items.push({
+      key: `${refund.id}-initiated`,
+      icon: <ArrowCounterClockwise size={16} weight="bold" />,
+      color: "bg-[var(--amber)]/15 text-[var(--amber)]",
+      lineColor: STATUS_LINE_COLOR[refund.status] ?? "bg-[var(--muted)]/30",
+      label: "Refund initiated",
+      detail: `${formatCurrency(refund.amount, currency)} — ${
+        REFUND_REASONS.find((r) => r.value === refund.reason)?.label ?? refund.reason
+      }${refund.notes ? ` · ${refund.notes}` : ""}`,
+      timestamp: formatTimestamp(refund.createdAt),
+    });
+
+    // Processing (implied if status >= PROCESSING)
+    if (
+      refund.status === "PROCESSING" ||
+      refund.status === "COMPLETED"
+    ) {
+      items.push({
+        key: `${refund.id}-processing`,
+        icon: <ArrowsClockwise size={16} weight="bold" />,
+        color: "bg-[var(--blue)]/15 text-[var(--blue)]",
+        lineColor:
+          refund.status === "COMPLETED"
+            ? "bg-[var(--green)]"
+            : "bg-[var(--muted)]/30",
+        label: "Refund processing",
+        detail: `Est. delivery: ${eta}`,
+        timestamp: formatTimestamp(refund.createdAt),
+      });
+    }
+
+    // Completed
+    if (refund.status === "COMPLETED" && refund.completedAt) {
+      items.push({
+        key: `${refund.id}-completed`,
+        icon: <CheckCircle size={16} weight="bold" />,
+        color: "bg-[var(--green)]/15 text-[var(--green)]",
+        lineColor: "bg-transparent",
+        label: "Refund completed",
+        detail: `${formatCurrency(refund.amount, currency)} refunded`,
+        timestamp: formatTimestamp(refund.completedAt),
+      });
+    }
+
+    // Failed
+    if (refund.status === "FAILED") {
+      items.push({
+        key: `${refund.id}-failed`,
+        icon: <XCircle size={16} weight="bold" />,
+        color: "bg-[var(--red)]/15 text-[var(--red)]",
+        lineColor: "bg-transparent",
+        label: "Refund failed",
+        detail: "The refund could not be processed",
+        timestamp: formatTimestamp(refund.createdAt),
+      });
+    }
+
+    return items;
+  });
+
+  return (
+    <div className="space-y-0">
+      {events.map((event, index) => (
+        <div key={event.key} className="flex gap-3">
+          <div className="flex flex-col items-center">
+            <div className={`rounded-full p-2 ${event.color}`}>
+              {event.icon}
+            </div>
+            {index < events.length - 1 && (
+              <div className={`my-1 h-8 w-0.5 ${event.lineColor}`} />
+            )}
+          </div>
+          <div className="pt-1 pb-4">
+            <p className="text-sm font-medium text-foreground">
+              {event.label}
+            </p>
+            <p className="text-xs text-muted-foreground">
+              {event.detail}
+            </p>
+            <p className="mt-0.5 text-xs text-muted-foreground">
+              {event.timestamp}
+            </p>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/dashboard/src/components/payments/StatusBadge.tsx b/apps/dashboard/src/components/payments/StatusBadge.tsx
index 479c22f..b63b594 100644
--- a/apps/dashboard/src/components/payments/StatusBadge.tsx
+++ b/apps/dashboard/src/components/payments/StatusBadge.tsx
@@ -14,8 +14,8 @@ const STATUS_TONES: Record<PaymentStatus, Tone> = {
   STELLAR_LOCKED: "processing",
   PROCESSING: "processing",
   COMPLETED: "completed",
-  REFUNDING: "processing",
-  REFUNDED: "cancelled",
+  REFUNDING: "pending",
+  REFUNDED: "completed",
   EXPIRED: "failed",
   FAILED: "failed",
 };
@@ -27,7 +27,7 @@ const STATUS_LABELS: Record<PaymentStatus, string> = {
   STELLAR_LOCKED: "Stellar locked",
   PROCESSING: "Processing",
   COMPLETED: "Completed",
-  REFUNDING: "Refunding",
+  REFUNDING: "Refund Pending",
   REFUNDED: "Refunded",
   EXPIRED: "Expired",
   FAILED: "Failed",
diff --git a/apps/dashboard/src/components/site-header.tsx b/apps/dashboard/src/components/site-header.tsx
index 7dc50d7..36bfe9f 100644
--- a/apps/dashboard/src/components/site-header.tsx
+++ b/apps/dashboard/src/components/site-header.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { usePathname } from "next/navigation";
-import { Bell, SidebarIcon } from "lucide-react";
+import { Moon, Monitor, SidebarIcon, Sun } from "lucide-react";
 
 import { Button } from "@/components/ui/button";
 import { Separator } from "@/components/ui/separator";
@@ -14,8 +14,16 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from "@/components/ui/breadcrumb";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip";
+import { useTheme } from "@/providers/ThemeProvider";
+import { NotificationBell } from "@/components/notifications/NotificationBell";
 import { ThemeToggle } from "@/components/brand/ThemeToggle";
 
+
 const routeLabels: Record<string, string> = {
   "/": "Overview",
   "/payments": "Payments",
@@ -32,6 +40,7 @@ const routeLabels: Record<string, string> = {
 
 export function SiteHeader() {
   const { toggleSidebar } = useSidebar();
+  const { preference, toggleTheme } = useTheme();
   const pathname = usePathname();
 
   const segments = pathname.split("/").filter(Boolean);
@@ -75,11 +84,34 @@ export function SiteHeader() {
           </BreadcrumbList>
         </Breadcrumb>
 
-        <div className="ml-auto flex items-center gap-2">
-          <Button variant="ghost" size="icon" className="size-8">
-            <Bell className="size-4" strokeWidth={1.5} />
-          </Button>
-          <ThemeToggle size="sm" />
+        <div className="ml-auto flex items-center gap-1">
+          <NotificationBell />
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-8 w-8"
+                onClick={toggleTheme}
+                aria-label={`Theme: ${preference}`}
+              >
+                {preference === "dark" ? (
+                  <Moon className="size-4" />
+                ) : preference === "light" ? (
+                  <Sun className="size-4" />
+                ) : (
+                  <Monitor className="size-4" />
+                )}
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              {preference === "light"
+                ? "Light mode — click for dark"
+                : preference === "dark"
+                  ? "Dark mode — click for system"
+                  : "System mode — click for light"}
+            </TooltipContent>
+          </Tooltip>
         </div>
       </div>
     </header>
diff --git a/apps/dashboard/src/hooks/useDashboardSocket.ts b/apps/dashboard/src/hooks/useDashboardSocket.ts
index 05f9149..2d86cd7 100644
--- a/apps/dashboard/src/hooks/useDashboardSocket.ts
+++ b/apps/dashboard/src/hooks/useDashboardSocket.ts
@@ -1,36 +1,94 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { io, type Socket } from "socket.io-client";
+import { useAuth } from "@/hooks/useAuth";
 
 const SOCKET_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3000";
 
+let sharedSocket: Socket | null = null;
+let sharedToken: string | null = null;
+
+function createDashboardSocket(token: string) {
+  return io(SOCKET_URL, {
+    transports: ["websocket", "polling"],
+    autoConnect: true,
+    reconnection: true,
+    reconnectionDelay: 1000,
+    reconnectionAttempts: 10,
+    query: {
+      type: "merchant",
+      token: `Bearer ${token}`,
+    },
+  });
+}
+
 export function useDashboardSocket() {
-  const socketRef = useRef<Socket | null>(null);
-  const [connected, setConnected] = useState(false);
+  const { token, merchant } = useAuth();
+  const merchantIdRef = useRef<string | null>(merchant?.id ?? null);
+  const [connected, setConnected] = useState(Boolean(sharedSocket?.connected));
+
+  merchantIdRef.current = merchant?.id ?? null;
 
   useEffect(() => {
-    const socket = io(SOCKET_URL, {
-      transports: ["websocket"],
-      autoConnect: true,
-    });
+    if (!token || !merchant?.id) {
+      setConnected(false);
 
-    socket.on("connect", () => setConnected(true));
-    socket.on("disconnect", () => setConnected(false));
+      if (sharedSocket) {
+        sharedSocket.disconnect();
+        sharedSocket = null;
+        sharedToken = null;
+      }
 
-    socketRef.current = socket;
+      return;
+    }
 
-    return () => {
-      socket.disconnect();
+    if (!sharedSocket || sharedToken !== token) {
+      sharedSocket?.disconnect();
+      sharedSocket = createDashboardSocket(token);
+      sharedToken = token;
+    }
+
+    const socket = sharedSocket;
+
+    const handleConnect = () => {
+      setConnected(true);
+      socket.emit("subscribe:merchant", merchantIdRef.current);
     };
-  }, []);
 
-  const subscribe = (event: string, callback: (...args: unknown[]) => void) => {
-    socketRef.current?.on(event, callback);
+    const handleDisconnect = () => {
+      setConnected(false);
+    };
+
+    socket.on("connect", handleConnect);
+    socket.on("disconnect", handleDisconnect);
+    socket.on("connect_error", handleDisconnect);
+
+    if (socket.connected) {
+      handleConnect();
+    }
+
     return () => {
-      socketRef.current?.off(event, callback);
+      socket.off("connect", handleConnect);
+      socket.off("disconnect", handleDisconnect);
+      socket.off("connect_error", handleDisconnect);
     };
-  };
+  }, [merchant?.id, token]);
+
+  const subscribe = useCallback(
+    (event: string, callback: (...args: unknown[]) => void) => {
+      if (!sharedSocket) {
+        return () => undefined;
+      }
+
+      sharedSocket.on(event, callback);
+
+      return () => {
+        sharedSocket?.off(event, callback);
+      };
+    },
+    [],
+  );
 
-  return { connected, subscribe, socket: socketRef.current };
+  return { connected, subscribe, socket: sharedSocket };
 }
diff --git a/apps/dashboard/src/hooks/useRefundEvents.ts b/apps/dashboard/src/hooks/useRefundEvents.ts
new file mode 100644
index 0000000..88cfa95
--- /dev/null
+++ b/apps/dashboard/src/hooks/useRefundEvents.ts
@@ -0,0 +1,55 @@
+"use client";
+
+import { useEffect } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useDashboardSocket } from "./useDashboardSocket";
+import { useToast } from "@useroutr/ui";
+
+interface RefundEventPayload {
+  refundId: string;
+  paymentId: string;
+  status: string;
+  amount: number;
+}
+
+/**
+ * Subscribe to refund.created and refund.completed WebSocket events.
+ * Automatically invalidates relevant queries and shows toast notifications.
+ */
+export function useRefundEvents() {
+  const { subscribe, connected } = useDashboardSocket();
+  const queryClient = useQueryClient();
+  const { toast } = useToast();
+
+  useEffect(() => {
+    if (!connected) return;
+
+    const unsubCreated = subscribe("refund:created", (raw: unknown) => {
+      const payload = raw as RefundEventPayload;
+
+      // Invalidate caches
+      queryClient.invalidateQueries({ queryKey: ["payments"] });
+      queryClient.invalidateQueries({ queryKey: ["payment", payload.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["payment-refunds", payload.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["refunds"] });
+
+      toast("Refund initiated", "info");
+    });
+
+    const unsubCompleted = subscribe("refund:completed", (raw: unknown) => {
+      const payload = raw as RefundEventPayload;
+
+      queryClient.invalidateQueries({ queryKey: ["payments"] });
+      queryClient.invalidateQueries({ queryKey: ["payment", payload.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["payment-refunds", payload.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["refunds"] });
+
+      toast("Refund completed successfully", "success");
+    });
+
+    return () => {
+      unsubCreated();
+      unsubCompleted();
+    };
+  }, [connected, subscribe, queryClient, toast]);
+}
diff --git a/apps/dashboard/src/hooks/useRefunds.ts b/apps/dashboard/src/hooks/useRefunds.ts
new file mode 100644
index 0000000..f2ff6a8
--- /dev/null
+++ b/apps/dashboard/src/hooks/useRefunds.ts
@@ -0,0 +1,34 @@
+"use client";
+
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { api } from "@/lib/api";
+import type { Refund, RefundPayload, RefundsResponse, RefundsParams } from "@/lib/refund";
+
+export function useRefunds(params: RefundsParams = {}) {
+  return useQuery<RefundsResponse>({
+    queryKey: ["refunds", params],
+    queryFn: () => api.get("/refunds", { params }),
+  });
+}
+
+export function usePaymentRefunds(paymentId: string) {
+  return useQuery<Refund[]>({
+    queryKey: ["payment-refunds", paymentId],
+    queryFn: () => api.get(`/payments/${paymentId}/refunds`),
+    enabled: !!paymentId,
+  });
+}
+
+export function useCreateRefund() {
+  const queryClient = useQueryClient();
+
+  return useMutation<Refund, Error, RefundPayload>({
+    mutationFn: (payload) => api.post<Refund>("/refunds", payload),
+    onSuccess: (data) => {
+      queryClient.invalidateQueries({ queryKey: ["payments"] });
+      queryClient.invalidateQueries({ queryKey: ["payment", data.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["payment-refunds", data.paymentId] });
+      queryClient.invalidateQueries({ queryKey: ["refunds"] });
+    },
+  });
+}
diff --git a/apps/dashboard/src/hooks/useToastNotificationPreference.ts b/apps/dashboard/src/hooks/useToastNotificationPreference.ts
new file mode 100644
index 0000000..8c755b6
--- /dev/null
+++ b/apps/dashboard/src/hooks/useToastNotificationPreference.ts
@@ -0,0 +1,42 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+
+export const TOAST_NOTIFICATIONS_ENABLED_KEY = "toast_notifications_enabled";
+
+function readStoredPreference(): boolean {
+  if (typeof window === "undefined") {
+    return true;
+  }
+
+  const stored = window.localStorage.getItem(TOAST_NOTIFICATIONS_ENABLED_KEY);
+  return stored === null ? true : stored === "true";
+}
+
+export function getToastNotificationsEnabled(): boolean {
+  return readStoredPreference();
+}
+
+export function useToastNotificationPreference() {
+  const [enabled, setEnabledState] = useState(true);
+
+  useEffect(() => {
+    setEnabledState(readStoredPreference());
+  }, []);
+
+  const setEnabled = useCallback((value: boolean) => {
+    setEnabledState(value);
+
+    if (typeof window !== "undefined") {
+      window.localStorage.setItem(
+        TOAST_NOTIFICATIONS_ENABLED_KEY,
+        String(value),
+      );
+    }
+  }, []);
+
+  return {
+    enabled,
+    setEnabled,
+  };
+}
diff --git a/apps/dashboard/src/lib/refund.ts b/apps/dashboard/src/lib/refund.ts
new file mode 100644
index 0000000..d966e99
--- /dev/null
+++ b/apps/dashboard/src/lib/refund.ts
@@ -0,0 +1,128 @@
+// ── Refund helpers ─────────────────────────────────────────────────────────────
+
+export const REFUND_WINDOW_DAYS = 180;
+
+export const REFUND_REASONS = [
+  { value: "customer_request", label: "Customer Request" },
+  { value: "duplicate", label: "Duplicate Payment" },
+  { value: "fraudulent", label: "Fraudulent" },
+  { value: "other", label: "Other" },
+] as const;
+
+export type RefundReason = (typeof REFUND_REASONS)[number]["value"];
+
+export type RefundStatus = "PENDING" | "PROCESSING" | "COMPLETED" | "FAILED";
+
+export interface Refund {
+  id: string;
+  paymentId: string;
+  amount: number;
+  reason: RefundReason;
+  notes?: string;
+  status: RefundStatus;
+  createdAt: string;
+  completedAt?: string | null;
+}
+
+export interface RefundPayload {
+  paymentId: string;
+  amount: number;
+  reason: string;
+  notes?: string;
+}
+
+export interface RefundsResponse {
+  data: Refund[];
+  total: number;
+  page: number;
+  limit: number;
+}
+
+export interface RefundsParams extends Record<string, unknown> {
+  page?: number;
+  limit?: number;
+  status?: RefundStatus | string;
+  sortBy?: string;
+  sortOrder?: "asc" | "desc";
+}
+
+/**
+ * Check whether a completed payment is still within the refund window.
+ */
+export function isWithinRefundWindow(completedAt: string | null | undefined): boolean {
+  if (!completedAt) return false;
+  const completed = new Date(completedAt);
+  const now = new Date();
+  const diffMs = now.getTime() - completed.getTime();
+  const diffDays = diffMs / (1000 * 60 * 60 * 24);
+  return diffDays <= REFUND_WINDOW_DAYS;
+}
+
+/**
+ * Returns days remaining in the refund window, or 0 if expired.
+ */
+export function refundWindowDaysRemaining(completedAt: string | null | undefined): number {
+  if (!completedAt) return 0;
+  const completed = new Date(completedAt);
+  const now = new Date();
+  const diffDays = (now.getTime() - completed.getTime()) / (1000 * 60 * 60 * 24);
+  return Math.max(0, Math.ceil(REFUND_WINDOW_DAYS - diffDays));
+}
+
+/**
+ * Return an estimated delivery time string based on the payment method / chain.
+ */
+export function getRefundEta(paymentMethod: string): string {
+  const method = paymentMethod.toLowerCase();
+
+  if (method.includes("card") || method.includes("visa") || method.includes("mastercard")) {
+    return "5–10 business days";
+  }
+
+  if (method.includes("bank") || method.includes("ach") || method.includes("wire")) {
+    return "1–3 business days";
+  }
+
+  // Default to crypto for chain names (ethereum, stellar, starknet, etc.)
+  return "A few minutes";
+}
+
+/**
+ * Determine the payment method category from chain/asset info for ETA display.
+ */
+export function getPaymentMethodLabel(sourceChain: string): string {
+  const chain = sourceChain.toLowerCase();
+  if (chain.includes("card")) return "Card";
+  if (chain.includes("bank") || chain.includes("ach")) return "Bank";
+  return "Crypto";
+}
+
+/**
+ * Whether a payment can be refunded (eligible status + within window + not fully refunded).
+ */
+export function canRefund(
+  status: string,
+  completedAt: string | null | undefined,
+  refundedAt: string | null | undefined,
+): boolean {
+  if (status !== "COMPLETED") return false;
+  if (refundedAt) return false; // already fully refunded
+  return isWithinRefundWindow(completedAt);
+}
+
+/**
+ * Get the refund-related display status for a payment.
+ * Returns null if no refund state applies.
+ */
+export function getRefundDisplayStatus(
+  status: string,
+): { label: string; variant: "pending" | "completed" | "processing" } | null {
+  switch (status) {
+    case "REFUNDING":
+      return { label: "Refund Pending", variant: "pending" };
+    case "REFUNDED":
+      return { label: "Refunded", variant: "completed" };
+    default:
+      return null;
+  }
+}
diff --git a/apps/dashboard/src/providers/NotificationsProvider.tsx b/apps/dashboard/src/providers/NotificationsProvider.tsx
new file mode 100644
index 0000000..9e19f99
--- /dev/null
+++ b/apps/dashboard/src/providers/NotificationsProvider.tsx
@@ -0,0 +1,253 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { api } from "@/lib/api";
+import { useDashboardSocket } from "@/hooks/useDashboardSocket";
+
+export interface DashboardNotification {
+  id: string;
+  type: string;
+  title: string;
+  body: string;
+  read: boolean;
+  metadata?: Record<string, unknown> | null;
+  createdAt: string;
+}
+
+interface NotificationsResponse {
+  data: DashboardNotification[];
+  meta?: {
+    unreadCount?: number;
+    total?: number;
+    nextCursor?: string;
+    limit?: number;
+  };
+}
+
+interface NotificationsContextValue {
+  notifications: DashboardNotification[];
+  unreadCount: number;
+  isLoading: boolean;
+  highlightedIds: Set<string>;
+  markAsRead: (id: string) => Promise<void>;
+  markAllAsRead: () => Promise<void>;
+  addNotification: (notification: DashboardNotification) => void;
+}
+
+const NotificationsContext = createContext<NotificationsContextValue | undefined>(
+  undefined,
+);
+
+const MAX_NOTIFICATIONS = 50;
+
+function normalizeSocketNotification(
+  raw: unknown,
+): DashboardNotification | null {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+
+  const candidate = raw as Record<string, unknown>;
+  const id = typeof candidate.id === "string" ? candidate.id : undefined;
+  const type = typeof candidate.type === "string" ? candidate.type : undefined;
+  const title =
+    typeof candidate.title === "string" ? candidate.title : undefined;
+  const body = typeof candidate.body === "string" ? candidate.body : undefined;
+  const createdAt =
+    typeof candidate.createdAt === "string"
+      ? candidate.createdAt
+      : new Date().toISOString();
+
+  if (!id || !type || !title || !body) {
+    return null;
+  }
+
+  return {
+    id,
+    type,
+    title,
+    body,
+    read: false,
+    metadata:
+      candidate.metadata && typeof candidate.metadata === "object"
+        ? (candidate.metadata as Record<string, unknown>)
+        : null,
+    createdAt,
+  };
+}
+
+export function NotificationsProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { connected, subscribe } = useDashboardSocket();
+  const [notifications, setNotifications] = useState<DashboardNotification[]>([]);
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [isLoading, setIsLoading] = useState(true);
+  const [highlightedIds, setHighlightedIds] = useState<Set<string>>(new Set());
+  const highlightTimeoutsRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+    new Map(),
+  );
+
+  const highlightNotification = useCallback((id: string) => {
+    setHighlightedIds((prev) => new Set([...prev, id]));
+
+    const existingTimeout = highlightTimeoutsRef.current.get(id);
+    if (existingTimeout) {
+      clearTimeout(existingTimeout);
+    }
+
+    const timeout = setTimeout(() => {
+      setHighlightedIds((prev) => {
+        const next = new Set(prev);
+        next.delete(id);
+        return next;
+      });
+      highlightTimeoutsRef.current.delete(id);
+    }, 2200);
+
+    highlightTimeoutsRef.current.set(id, timeout);
+  }, []);
+
+  const addNotification = useCallback(
+    (notification: DashboardNotification) => {
+      setNotifications((prev) => {
+        const alreadyExists = prev.some((item) => item.id === notification.id);
+
+        if (!alreadyExists) {
+          setUnreadCount((count) => count + 1);
+          highlightNotification(notification.id);
+        }
+
+        const next = [notification, ...prev.filter((item) => item.id !== notification.id)];
+        return next.slice(0, MAX_NOTIFICATIONS);
+      });
+    },
+    [highlightNotification],
+  );
+
+  const fetchNotifications = useCallback(async () => {
+    try {
+      const response = await api.get<NotificationsResponse>("/v1/notifications", {
+        params: { limit: 50 },
+      });
+
+      setNotifications(response.data ?? []);
+      setUnreadCount(
+        response.meta?.unreadCount ??
+          (response.data ?? []).filter((item) => !item.read).length,
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void fetchNotifications();
+
+    return () => {
+      highlightTimeoutsRef.current.forEach((timeout) => clearTimeout(timeout));
+      highlightTimeoutsRef.current.clear();
+    };
+  }, [fetchNotifications]);
+
+  useEffect(() => {
+    if (!connected) {
+      return;
+    }
+
+    const unsubscribeDirect = subscribe("notification.created", (raw) => {
+      const notification = normalizeSocketNotification(raw);
+      if (notification) {
+        addNotification(notification);
+      }
+    });
+
+    const unsubscribeEnvelope = subscribe("message", (raw) => {
+      const message = raw as { event?: string; data?: unknown };
+
+      if (message?.event !== "notification.created") {
+        return;
+      }
+
+      const notification = normalizeSocketNotification(message.data);
+      if (notification) {
+        addNotification(notification);
+      }
+    });
+
+    return () => {
+      unsubscribeDirect();
+      unsubscribeEnvelope();
+    };
+  }, [addNotification, connected, subscribe]);
+
+  const markAsRead = useCallback(async (id: string) => {
+    setNotifications((prev) =>
+      prev.map((item) => (item.id === id ? { ...item, read: true } : item)),
+    );
+    setUnreadCount((prev) => Math.max(0, prev - 1));
+
+    try {
+      await api.patch(`/v1/notifications/${id}/read`);
+    } catch {
+      setNotifications((prev) =>
+        prev.map((item) => (item.id === id ? { ...item, read: false } : item)),
+      );
+      setUnreadCount((prev) => prev + 1);
+    }
+  }, []);
+
+  const markAllAsRead = useCallback(async () => {
+    const previousNotifications = notifications;
+    const previousUnreadCount = unreadCount;
+
+    setNotifications((prev) => prev.map((item) => ({ ...item, read: true })));
+    setUnreadCount(0);
+
+    try {
+      await api.post("/v1/notifications/mark-all-read");
+    } catch {
+      setNotifications(previousNotifications);
+      setUnreadCount(previousUnreadCount);
+    }
+  }, [notifications, unreadCount]);
+
+  const value = useMemo<NotificationsContextValue>(
+    () => ({
+      notifications,
+      unreadCount,
+      isLoading,
+      highlightedIds,
+      markAsRead,
+      markAllAsRead,
+      addNotification,
+    }),
+    [addNotification, highlightedIds, isLoading, markAllAsRead, markAsRead, notifications, unreadCount],
+  );
+
+  return (
+    <NotificationsContext.Provider value={value}>
+      {children}
+    </NotificationsContext.Provider>
+  );
+}
+
+export function useNotifications() {
+  const context = useContext(NotificationsContext);
+
+  if (!context) {
+    throw new Error("useNotifications must be used within NotificationsProvider");
+  }
+
+  return context;
+}
diff --git a/apps/dashboard/src/providers/RealtimeToastNotifications.tsx b/apps/dashboard/src/providers/RealtimeToastNotifications.tsx
new file mode 100644
index 0000000..f7c45dd
--- /dev/null
+++ b/apps/dashboard/src/providers/RealtimeToastNotifications.tsx
@@ -0,0 +1,415 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useQueryClient } from "@tanstack/react-query";
+import { useToast, type ToastVariant } from "@useroutr/ui";
+import { useDashboardSocket } from "@/hooks/useDashboardSocket";
+import { useToastNotificationPreference } from "@/hooks/useToastNotificationPreference";
+
+type RealtimeEventName =
+  | "payment.received"
+  | "payment.failed"
+  | "payment_link.paid"
+  | "invoice.paid"
+  | "payout.completed"
+  | "payout.failed"
+  | "webhook.failed"
+  | "bulk_payout.completed";
+
+interface ToastPayload {
+  type: ToastVariant;
+  title?: string;
+  message: string;
+  actionLabel?: string;
+  actionHref?: string;
+}
+
+interface SocketEnvelope {
+  event?: string;
+  data?: Record<string, unknown>;
+}
+
+function getString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+
+  return undefined;
+}
+
+function formatAmount(amount?: unknown, currency?: unknown): string {
+  const numericAmount =
+    typeof amount === "number"
+      ? amount
+      : typeof amount === "string"
+        ? Number(amount)
+        : Number.NaN;
+
+  const currencyCode =
+    typeof currency === "string" && currency.trim().length >= 3
+      ? currency.trim().slice(0, 3).toUpperCase()
+      : "USD";
+
+  if (!Number.isFinite(numericAmount)) {
+    return typeof amount === "string" && amount.trim()
+      ? amount.trim()
+      : "an amount";
+  }
+
+  try {
+    return new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency: currencyCode,
+      maximumFractionDigits: 2,
+    }).format(numericAmount);
+  } catch {
+    return `${numericAmount.toLocaleString()} ${currencyCode}`;
+  }
+}
+
+function getDomainLabel(value?: string): string {
+  if (!value) {
+    return "your webhook endpoint";
+  }
+
+  try {
+    return new URL(value).hostname;
+  } catch {
+    return value;
+  }
+}
+
+function resolveEvent(
+  eventName: string,
+  payload: Record<string, unknown>,
+): { name: RealtimeEventName; payload: Record<string, unknown> } | null {
+  if (
+    [
+      "payment.received",
+      "payment.failed",
+      "payment_link.paid",
+      "invoice.paid",
+      "payout.completed",
+      "payout.failed",
+      "webhook.failed",
+      "bulk_payout.completed",
+    ].includes(eventName)
+  ) {
+    return {
+      name: eventName as RealtimeEventName,
+      payload,
+    };
+  }
+
+  if (eventName === "payment-link.payment") {
+    return {
+      name: "payment_link.paid",
+      payload,
+    };
+  }
+
+  if (eventName === "payment:status") {
+    const status = String(payload.status ?? "").toLowerCase();
+
+    if (["completed", "paid", "success", "succeeded"].includes(status)) {
+      return { name: "payment.received", payload };
+    }
+
+    if (["failed", "error", "declined"].includes(status)) {
+      return { name: "payment.failed", payload };
+    }
+  }
+
+  if (eventName === "payout:status") {
+    const status = String(payload.status ?? "").toLowerCase();
+
+    if (["completed", "paid", "success", "succeeded"].includes(status)) {
+      return { name: "payout.completed", payload };
+    }
+
+    if (status.includes("bulk") && status.includes("complete")) {
+      return { name: "bulk_payout.completed", payload };
+    }
+
+    if (["failed", "error", "rejected"].includes(status)) {
+      return { name: "payout.failed", payload };
+    }
+  }
+
+  if (eventName === "webhook:delivery") {
+    const status = String(payload.status ?? "").toLowerCase();
+
+    if (["failed", "error"].includes(status)) {
+      return { name: "webhook.failed", payload };
+    }
+  }
+
+  if (eventName === "notification") {
+    const type = String(payload.type ?? "").toLowerCase();
+
+    if (type === "link_paid") {
+      return { name: "payment_link.paid", payload };
+    }
+
+    if (type === "invoice_paid") {
+      return { name: "invoice.paid", payload };
+    }
+
+    if (type === "bulk_payout_completed") {
+      return { name: "bulk_payout.completed", payload };
+    }
+  }
+
+  return null;
+}
+
+function buildToastPayload(
+  eventName: RealtimeEventName,
+  payload: Record<string, unknown>,
+): ToastPayload {
+  switch (eventName) {
+    case "payment.received": {
+      const payer = getString(
+        payload.customerEmail,
+        payload.email,
+        payload.customerName,
+        payload.name,
+      );
+      const amount = formatAmount(
+        payload.amount ?? payload.destAmount ?? payload.sourceAmount,
+        payload.currency ?? payload.destAsset ?? payload.sourceAsset,
+      );
+      const paymentId = getString(payload.paymentId, payload.id);
+
+      return {
+        type: "success",
+        title: "Payment received",
+        message: `Payment received — ${amount}${payer ? ` from ${payer}` : ""}`,
+        actionLabel: paymentId ? "View Payment →" : undefined,
+        actionHref: paymentId ? `/payments/${paymentId}` : undefined,
+      };
+    }
+
+    case "payment.failed": {
+      const paymentId = getString(payload.paymentId, payload.id);
+
+      return {
+        type: "error",
+        title: "Payment failed",
+        message: "A payment attempt failed and may need review.",
+        actionLabel: paymentId ? "Review Payment →" : undefined,
+        actionHref: paymentId ? `/payments/${paymentId}` : "/payments",
+      };
+    }
+
+    case "payment_link.paid": {
+      const linkName = getString(
+        payload.title,
+        payload.name,
+        payload.linkTitle,
+      );
+
+      return {
+        type: "success",
+        title: "Payment link paid",
+        message: `Payment link '${linkName ?? "Untitled link"}' was just paid`,
+        actionLabel: "View Links →",
+        actionHref: "/links",
+      };
+    }
+
+    case "invoice.paid": {
+      const invoiceLabel = getString(
+        payload.invoiceNumber,
+        payload.invoiceId,
+        payload.resourceId,
+      );
+
+      return {
+        type: "success",
+        title: "Invoice paid",
+        message: `Invoice ${invoiceLabel ? `#${invoiceLabel}` : ""} marked as paid`.trim(),
+        actionLabel: "View Invoices →",
+        actionHref: "/invoices",
+      };
+    }
+
+    case "payout.completed": {
+      const recipient = getString(
+        payload.recipientName,
+        payload.name,
+        payload.beneficiary,
+      );
+
+      return {
+        type: "success",
+        title: "Payout completed",
+        message: `Payout${recipient ? ` to ${recipient}` : ""} completed`,
+        actionLabel: "View Payouts →",
+        actionHref: "/payouts",
+      };
+    }
+
+    case "payout.failed": {
+      return {
+        type: "error",
+        title: "Payout failed",
+        message: "A payout could not be completed.",
+        actionLabel: "View Payouts →",
+        actionHref: "/payouts",
+      };
+    }
+
+    case "webhook.failed": {
+      const endpoint = getDomainLabel(
+        getString(payload.endpointUrl, payload.webhookUrl, payload.url),
+      );
+
+      return {
+        type: "error",
+        title: "Webhook failed",
+        message: `Webhook delivery to ${endpoint} failed`,
+        actionLabel: "Retry Webhook →",
+        actionHref: "/settings/webhooks",
+      };
+    }
+
+    case "bulk_payout.completed": {
+      const successCount = payload.successCount ?? payload.successful ?? 0;
+      const totalCount = payload.totalCount ?? payload.total ?? successCount;
+
+      return {
+        type: "info",
+        title: "Bulk payout complete",
+        message: `Bulk payout batch completed: ${successCount}/${totalCount} successful`,
+        actionLabel: "View Payouts →",
+        actionHref: "/payouts",
+      };
+    }
+  }
+}
+
+function invalidateForEvent(
+  queryClient: ReturnType<typeof useQueryClient>,
+  eventName: RealtimeEventName,
+  payload: Record<string, unknown>,
+) {
+  switch (eventName) {
+    case "payment.received":
+    case "payment.failed": {
+      void queryClient.invalidateQueries({ queryKey: ["payments"] });
+
+      const paymentId = getString(payload.paymentId, payload.id);
+      if (paymentId) {
+        void queryClient.invalidateQueries({ queryKey: ["payment", paymentId] });
+      }
+      break;
+    }
+
+    case "payment_link.paid":
+      void queryClient.invalidateQueries({ queryKey: ["payment-links"] });
+      break;
+
+    case "invoice.paid":
+      void queryClient.invalidateQueries({ queryKey: ["invoices"] });
+      break;
+
+    case "payout.completed":
+    case "payout.failed":
+    case "bulk_payout.completed":
+      void queryClient.invalidateQueries({ queryKey: ["analytics-overview"] });
+      break;
+
+    case "webhook.failed":
+      void queryClient.invalidateQueries({ queryKey: ["webhook-logs"] });
+      break;
+  }
+}
+
+export function RealtimeToastNotifications() {
+  const router = useRouter();
+  const queryClient = useQueryClient();
+  const toast = useToast();
+  const { connected, subscribe } = useDashboardSocket();
+  const { enabled } = useToastNotificationPreference();
+
+  useEffect(() => {
+    if (!connected) {
+      return;
+    }
+
+    const showRealtimeToast = (
+      rawEventName: string,
+      rawPayload: Record<string, unknown>,
+    ) => {
+      const resolved = resolveEvent(rawEventName, rawPayload);
+      if (!resolved) {
+        return;
+      }
+
+      invalidateForEvent(queryClient, resolved.name, resolved.payload);
+
+      if (!enabled) {
+        return;
+      }
+
+      const mapped = buildToastPayload(resolved.name, resolved.payload);
+      const onAction = mapped.actionHref
+        ? () => router.push(mapped.actionHref!)
+        : undefined;
+
+      toast[mapped.type]({
+        title: mapped.title,
+        message: mapped.message,
+        actionLabel: mapped.actionLabel,
+        actionHref: mapped.actionHref,
+        onAction,
+      });
+    };
+
+    const unsubscribers = [
+      subscribe("message", (raw) => {
+        const envelope = raw as SocketEnvelope;
+
+        if (!envelope?.event || !envelope.data) {
+          return;
+        }
+
+        showRealtimeToast(envelope.event, envelope.data);
+      }),
+      subscribe("payment.received", (raw) =>
+        showRealtimeToast("payment.received", raw as Record<string, unknown>),
+      ),
+      subscribe("payment_link.paid", (raw) =>
+        showRealtimeToast("payment_link.paid", raw as Record<string, unknown>),
+      ),
+      subscribe("invoice.paid", (raw) =>
+        showRealtimeToast("invoice.paid", raw as Record<string, unknown>),
+      ),
+      subscribe("payout.completed", (raw) =>
+        showRealtimeToast("payout.completed", raw as Record<string, unknown>),
+      ),
+      subscribe("webhook.failed", (raw) =>
+        showRealtimeToast("webhook.failed", raw as Record<string, unknown>),
+      ),
+      subscribe("bulk_payout.completed", (raw) =>
+        showRealtimeToast(
+          "bulk_payout.completed",
+          raw as Record<string, unknown>,
+        ),
+      ),
+      subscribe("payment-link.payment", (raw) =>
+        showRealtimeToast("payment-link.payment", raw as Record<string, unknown>),
+      ),
+    ];
+
+    return () => {
+      unsubscribers.forEach((unsubscribe) => unsubscribe());
+    };
+  }, [connected, enabled, queryClient, router, subscribe, toast]);
+
+  return null;
+}
diff --git a/apps/dashboard/src/providers/ThemeProvider.tsx b/apps/dashboard/src/providers/ThemeProvider.tsx
index c9a8990..82d3ceb 100644
--- a/apps/dashboard/src/providers/ThemeProvider.tsx
+++ b/apps/dashboard/src/providers/ThemeProvider.tsx
@@ -1,38 +1,84 @@
 "use client";
 
-import { createContext, useContext, useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useState, useCallback } from "react";
 
-type Theme = "light" | "dark";
+type ThemePreference = "light" | "dark" | "system";
+type ResolvedTheme = "light" | "dark";
 
 interface ThemeContextValue {
-  theme: Theme;
+  /** The user's preference: light, dark, or system */
+  preference: ThemePreference;
+  /** The resolved theme applied to the DOM: light or dark */
+  theme: ResolvedTheme;
+  /** Cycle through light → dark → system */
   toggleTheme: () => void;
-  setTheme: (theme: Theme) => void;
+  /** Set an explicit preference */
+  setPreference: (preference: ThemePreference) => void;
 }
 
 const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
 
+const STORAGE_KEY = "useroutr-theme";
+
+function resolveTheme(preference: ThemePreference): ResolvedTheme {
+  if (preference === "system") {
+    if (typeof window === "undefined") return "light";
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  return preference;
+}
+
+function applyThemeToDOM(theme: ResolvedTheme) {
+  const root = document.documentElement;
+  root.classList.remove("light", "dark");
+  root.classList.add(theme);
+}
+
 export function ThemeProvider({ children }: { children: React.ReactNode }) {
-  const [theme, setTheme] = useState<Theme>("light");
+  const [preference, setPreferenceState] = useState<ThemePreference>("system");
+  const [theme, setTheme] = useState<ResolvedTheme>("light");
 
+  // Initialize from localStorage or system preference
   useEffect(() => {
-    const stored = localStorage.getItem("useroutr-theme") as Theme | null;
-    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
-    const initial = stored ?? (prefersDark ? "dark" : "light");
-    setTheme(initial);
+    const stored = localStorage.getItem(STORAGE_KEY) as ThemePreference | null;
+    const initial: ThemePreference = stored ?? "system";
+    setPreferenceState(initial);
+    const resolved = resolveTheme(initial);
+    setTheme(resolved);
+    applyThemeToDOM(resolved);
   }, []);
 
+  // Listen for system preference changes when in "system" mode
   useEffect(() => {
-    const root = document.documentElement;
-    root.classList.remove("light", "dark");
-    root.classList.add(theme);
-    localStorage.setItem("useroutr-theme", theme);
-  }, [theme]);
+    if (preference !== "system") return;
+
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const handler = (e: MediaQueryListEvent) => {
+      const resolved: ResolvedTheme = e.matches ? "dark" : "light";
+      setTheme(resolved);
+      applyThemeToDOM(resolved);
+    };
+
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [preference]);
+
+  const setPreference = useCallback((pref: ThemePreference) => {
+    setPreferenceState(pref);
+    localStorage.setItem(STORAGE_KEY, pref);
+    const resolved = resolveTheme(pref);
+    setTheme(resolved);
+    applyThemeToDOM(resolved);
+  }, []);
 
-  const toggleTheme = () => setTheme((t) => (t === "light" ? "dark" : "light"));
+  const toggleTheme = useCallback(() => {
+    setPreference(
+      preference === "light" ? "dark" : preference === "dark" ? "system" : "light"
+    );
+  }, [preference, setPreference]);
 
   return (
-    <ThemeContext.Provider value={{ theme, toggleTheme, setTheme }}>
+    <ThemeContext.Provider value={{ preference, theme, toggleTheme, setPreference }}>
       {children}
     </ThemeContext.Provider>
   );
diff --git a/package.json b/package.json
index 16314b3..65907f4 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,6 @@
     "@nestjs/jwt": "^11.0.2",
     "@nestjs/passport": "^11.0.0",
     "@openzeppelin/contracts": "^5.6.1",
-    "lightningcss-darwin-arm64": "^1.32.0",
     "passport": "^0.7.0",
     "passport-jwt": "^4.0.1"
   },
diff --git a/packages/ui/src/components/switch.tsx b/packages/ui/src/components/switch.tsx
index e41a86d..b4b32d5 100644
--- a/packages/ui/src/components/switch.tsx
+++ b/packages/ui/src/components/switch.tsx
@@ -1,32 +1,57 @@
 "use client";
 
-import { forwardRef } from "react";
+import { forwardRef, useMemo, useState } from "react";
 import * as SwitchPrimitive from "@radix-ui/react-switch";
 import { cn } from "../utils";
 
 const Switch = forwardRef<
   React.ComponentRef<typeof SwitchPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof SwitchPrimitive.Root>
->(({ className, ...props }, ref) => (
-  <SwitchPrimitive.Root
-    ref={ref}
-    className={cn(
-      "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors",
-      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--background)]",
-      "disabled:cursor-not-allowed disabled:opacity-50",
-      "data-[state=checked]:bg-[var(--primary)] data-[state=unchecked]:bg-[var(--input)]",
-      className
-    )}
-    {...props}
-  >
-    <SwitchPrimitive.Thumb
+>(({ className, checked, defaultChecked, onCheckedChange, ...props }, ref) => {
+  const [localChecked, setLocalChecked] = useState(Boolean(defaultChecked));
+
+  const isChecked = useMemo(
+    () => (typeof checked === "boolean" ? checked : localChecked),
+    [checked, localChecked],
+  );
+
+  return (
+    <SwitchPrimitive.Root
+      ref={ref}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={(nextChecked) => {
+        if (typeof checked !== "boolean") {
+          setLocalChecked(nextChecked);
+        }
+        onCheckedChange?.(nextChecked);
+      }}
       className={cn(
-        "pointer-events-none block h-4 w-4 rounded-full bg-white shadow-lg ring-0 transition-transform",
-        "data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0"
+        "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border border-transparent p-0.5 shadow-sm transition-colors duration-200",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--background)]",
+        "disabled:cursor-not-allowed disabled:opacity-50",
+        isChecked
+          ? "bg-emerald-500 shadow-[0_0_0_3px_rgba(16,185,129,0.18)]"
+          : "bg-[var(--input)]",
+        className,
       )}
-    />
-  </SwitchPrimitive.Root>
-));
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        style={{
+          width: 20,
+          height: 20,
+          borderRadius: 9999,
+          backgroundColor: "#ffffff",
+          boxShadow: "0 1px 3px rgba(0,0,0,0.25)",
+          transform: `translateX(${isChecked ? 20 : 0}px)`,
+          transition: "transform 200ms ease-in-out",
+        }}
+        className="pointer-events-none block shrink-0"
+      />
+    </SwitchPrimitive.Root>
+  );
+});
 Switch.displayName = "Switch";
 
 export { Switch };
diff --git a/packages/ui/src/components/toast.tsx b/packages/ui/src/components/toast.tsx
index 0cd906c..bd53f8d 100644
--- a/packages/ui/src/components/toast.tsx
+++ b/packages/ui/src/components/toast.tsx
@@ -1,6 +1,14 @@
 "use client";
 
-import { createContext, useCallback, useContext, useState } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   X,
   CheckCircle,
@@ -10,86 +18,340 @@ import {
 } from "@phosphor-icons/react";
 import { cn } from "../utils";
 
-type ToastVariant = "success" | "error" | "warning" | "info";
+export type ToastVariant = "success" | "error" | "warning" | "info";
 
-interface ToastItem {
+export interface ToastProps {
   id: string;
+  type: ToastVariant;
+  title?: string;
+  message: string;
+  actionLabel?: string;
+  actionHref?: string;
+  duration?: number;
+  onClose: () => void;
+  onAction?: () => void;
+}
+
+interface ToastInput {
+  type?: ToastVariant;
+  title?: string;
   message: string;
-  variant: ToastVariant;
+  actionLabel?: string;
+  actionHref?: string;
+  duration?: number;
+  onAction?: () => void;
+}
+
+interface ToastItem extends ToastInput {
+  id: string;
+  type: ToastVariant;
+  duration: number;
 }
 
 interface ToastContextValue {
-  toast: (message: string, variant?: ToastVariant) => void;
+  toast: (messageOrOptions: string | ToastInput, variant?: ToastVariant) => string;
+  success: (messageOrOptions: string | Omit<ToastInput, "type">) => string;
+  error: (messageOrOptions: string | Omit<ToastInput, "type">) => string;
+  warning: (messageOrOptions: string | Omit<ToastInput, "type">) => string;
+  info: (messageOrOptions: string | Omit<ToastInput, "type">) => string;
+  dismiss: (id: string) => void;
+  clearAll: () => void;
 }
 
 const ToastContext = createContext<ToastContextValue | undefined>(undefined);
 
 const MAX_VISIBLE = 3;
+const DEFAULT_DURATION = 4000;
+const EXIT_DURATION = 200;
 
 const VARIANT_CONFIG: Record<
   ToastVariant,
-  { bg: string; icon: typeof CheckCircle }
+  {
+    bg: string;
+    icon: typeof CheckCircle;
+    iconColor: string;
+    actionClass: string;
+  }
 > = {
-  success: { bg: "border-[var(--green)]/30 bg-[var(--green)]/10", icon: CheckCircle },
-  error: { bg: "border-[var(--red)]/30 bg-[var(--red)]/10", icon: XCircle },
-  warning: { bg: "border-[var(--amber)]/30 bg-[var(--amber)]/10", icon: Warning },
-  info: { bg: "border-[var(--blue)]/30 bg-[var(--blue)]/10", icon: Info },
+  success: {
+    bg: "border-[var(--green)]/30 bg-[var(--green)]/10",
+    icon: CheckCircle,
+    iconColor: "text-[var(--green)]",
+    actionClass: "text-[var(--green)] hover:text-[var(--green)]/80",
+  },
+  error: {
+    bg: "border-[var(--red)]/30 bg-[var(--red)]/10",
+    icon: XCircle,
+    iconColor: "text-[var(--red)]",
+    actionClass: "text-[var(--red)] hover:text-[var(--red)]/80",
+  },
+  warning: {
+    bg: "border-[var(--amber)]/30 bg-[var(--amber)]/10",
+    icon: Warning,
+    iconColor: "text-[var(--amber)]",
+    actionClass: "text-[var(--amber)] hover:text-[var(--amber)]/80",
+  },
+  info: {
+    bg: "border-[var(--blue)]/30 bg-[var(--blue)]/10",
+    icon: Info,
+    iconColor: "text-[var(--blue)]",
+    actionClass: "text-[var(--blue)] hover:text-[var(--blue)]/80",
+  },
 };
 
-const VARIANT_ICON_COLOR: Record<ToastVariant, string> = {
-  success: "text-[var(--green)]",
-  error: "text-[var(--red)]",
-  warning: "text-[var(--amber)]",
-  info: "text-[var(--blue)]",
-};
+function createToastId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+    return crypto.randomUUID();
+  }
+
+  return `toast-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+function normalizeToastInput(
+  messageOrOptions: string | ToastInput,
+  variant: ToastVariant,
+): ToastItem {
+  if (typeof messageOrOptions === "string") {
+    return {
+      id: createToastId(),
+      type: variant,
+      message: messageOrOptions,
+      duration: DEFAULT_DURATION,
+    };
+  }
+
+  return {
+    id: createToastId(),
+    type: messageOrOptions.type ?? variant,
+    title: messageOrOptions.title,
+    message: messageOrOptions.message,
+    actionLabel: messageOrOptions.actionLabel,
+    actionHref: messageOrOptions.actionHref,
+    duration: messageOrOptions.duration ?? DEFAULT_DURATION,
+    onAction: messageOrOptions.onAction,
+  };
+}
+
+function Toast({
+  id,
+  type,
+  title,
+  message,
+  actionLabel,
+  actionHref,
+  duration = DEFAULT_DURATION,
+  onClose,
+  onAction,
+}: ToastProps) {
+  const [isVisible, setIsVisible] = useState(false);
+  const [remaining, setRemaining] = useState(duration);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const startedAtRef = useRef<number | null>(null);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+
+    startedAtRef.current = null;
+  }, []);
+
+  const closeToast = useCallback(() => {
+    clearTimer();
+    setIsVisible(false);
+    window.setTimeout(() => onClose(), EXIT_DURATION);
+  }, [clearTimer, onClose]);
+
+  const scheduleDismiss = useCallback(
+    (timeoutMs: number) => {
+      clearTimer();
+
+      if (timeoutMs <= 0) {
+        closeToast();
+        return;
+      }
+
+      setRemaining(timeoutMs);
+      startedAtRef.current = Date.now();
+      timerRef.current = setTimeout(() => {
+        closeToast();
+      }, timeoutMs);
+    },
+    [clearTimer, closeToast],
+  );
+
+  useEffect(() => {
+    const frame = window.requestAnimationFrame(() => setIsVisible(true));
+    scheduleDismiss(duration);
+
+    return () => {
+      window.cancelAnimationFrame(frame);
+      clearTimer();
+    };
+  }, [clearTimer, duration, scheduleDismiss]);
+
+  const pauseDismiss = useCallback(() => {
+    if (startedAtRef.current === null) {
+      return;
+    }
+
+    const elapsed = Date.now() - startedAtRef.current;
+    clearTimer();
+    setRemaining((current) => Math.max(0, current - elapsed));
+  }, [clearTimer]);
+
+  const resumeDismiss = useCallback(() => {
+    if (remaining > 0) {
+      scheduleDismiss(remaining);
+    }
+  }, [remaining, scheduleDismiss]);
+
+  const handleAction = useCallback(() => {
+    if (onAction) {
+      onAction();
+    } else if (actionHref) {
+      window.location.assign(actionHref);
+    }
+
+    closeToast();
+  }, [actionHref, closeToast, onAction]);
+
+  const config = VARIANT_CONFIG[type];
+  const Icon = config.icon;
+
+  return (
+    <div
+      className={cn(
+        "overflow-hidden transition-all duration-200 ease-out",
+        isVisible
+          ? "max-h-[240px] translate-y-0 opacity-100"
+          : "max-h-0 translate-y-3 opacity-0",
+      )}
+    >
+      <div
+        role="status"
+        aria-live="polite"
+        tabIndex={0}
+        onMouseEnter={pauseDismiss}
+        onMouseLeave={resumeDismiss}
+        onFocus={pauseDismiss}
+        onBlur={resumeDismiss}
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            closeToast();
+          }
+        }}
+        className={cn(
+          "pointer-events-auto w-full max-w-[320px] rounded-2xl border px-4 py-3 text-left shadow-[0_12px_32px_rgba(15,23,42,0.14)] backdrop-blur-sm",
+          "focus:outline-none focus:ring-2 focus:ring-[var(--ring)] focus:ring-offset-2",
+          config.bg,
+        )}
+      >
+        <div className="flex items-start gap-3">
+          <div className="mt-0.5 shrink-0">
+            <Icon size={18} weight="fill" className={config.iconColor} />
+          </div>
+
+          <div className="min-w-0 flex-1">
+            {title ? (
+              <p className="text-sm font-semibold text-[var(--foreground)]">
+                {title}
+              </p>
+            ) : null}
+
+            <p className="text-sm leading-5 text-[var(--foreground)]/90">
+              {message}
+            </p>
+
+            {actionLabel && (actionHref || onAction) ? (
+              <button
+                type="button"
+                onClick={handleAction}
+                className={cn(
+                  "mt-2 text-sm font-medium transition-colors focus:outline-none",
+                  config.actionClass,
+                )}
+              >
+                {actionLabel}
+              </button>
+            ) : null}
+          </div>
+
+          <button
+            type="button"
+            data-toast-close
+            onClick={closeToast}
+            aria-label="Dismiss notification"
+            className="shrink-0 rounded-md p-1 text-[var(--muted-foreground)] transition-colors hover:bg-black/5 hover:text-[var(--foreground)] focus:outline-none focus:ring-2 focus:ring-[var(--ring)]"
+          >
+            <X size={14} />
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
 
 function ToastProvider({ children }: { children: React.ReactNode }) {
   const [toasts, setToasts] = useState<ToastItem[]>([]);
 
   const dismiss = useCallback((id: string) => {
-    setToasts((prev) => prev.filter((t) => t.id !== id));
+    setToasts((prev) => prev.filter((toast) => toast.id !== id));
+  }, []);
+
+  const clearAll = useCallback(() => {
+    setToasts([]);
   }, []);
 
-  const toast = useCallback(
-    (message: string, variant: ToastVariant = "info") => {
-      const id = crypto.randomUUID();
-      setToasts((prev) => [...prev.slice(-(MAX_VISIBLE - 1)), { id, message, variant }]);
-      setTimeout(() => dismiss(id), 4000);
+  const addToast = useCallback(
+    (messageOrOptions: string | ToastInput, variant: ToastVariant = "info") => {
+      const nextToast = normalizeToastInput(messageOrOptions, variant);
+
+      setToasts((prev) => [...prev.slice(-(MAX_VISIBLE - 1)), nextToast]);
+
+      return nextToast.id;
     },
-    [dismiss]
+    [],
+  );
+
+  const contextValue = useMemo<ToastContextValue>(
+    () => ({
+      toast: addToast,
+      success: (messageOrOptions) => addToast(messageOrOptions, "success"),
+      error: (messageOrOptions) => addToast(messageOrOptions, "error"),
+      warning: (messageOrOptions) => addToast(messageOrOptions, "warning"),
+      info: (messageOrOptions) => addToast(messageOrOptions, "info"),
+      dismiss,
+      clearAll,
+    }),
+    [addToast, clearAll, dismiss],
   );
 
   return (
-    <ToastContext.Provider value={{ toast }}>
+    <ToastContext.Provider value={contextValue}>
       {children}
-      <div className="fixed bottom-4 right-4 z-[100] flex max-w-[320px] flex-col gap-2">
-        {toasts.map((t) => {
-          const cfg = VARIANT_CONFIG[t.variant];
-          const Icon = cfg.icon;
-          return (
-            <div
-              key={t.id}
-              className={cn(
-                "flex items-start gap-3 rounded-[var(--radius-md)] border px-4 py-3 shadow-[var(--shadow-md)]",
-                cfg.bg
-              )}
-              style={{ animation: "toast-slide-in 200ms ease-out" }}
-            >
-              <Icon
-                size={18}
-                weight="fill"
-                className={cn("mt-0.5 shrink-0", VARIANT_ICON_COLOR[t.variant])}
-              />
-              <p className="flex-1 text-sm text-[var(--foreground)]">{t.message}</p>
-              <button
-                onClick={() => dismiss(t.id)}
-                className="shrink-0 text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
-              >
-                <X size={14} />
-              </button>
-            </div>
-          );
-        })}
+      <div
+        aria-live="polite"
+        aria-relevant="additions text"
+        aria-label="Notifications"
+        className="pointer-events-none fixed bottom-4 right-4 z-[100] flex w-full max-w-[320px] flex-col gap-2"
+      >
+        {toasts.map((toast) => (
+          <Toast
+            key={toast.id}
+            id={toast.id}
+            type={toast.type}
+            title={toast.title}
+            message={toast.message}
+            actionLabel={toast.actionLabel}
+            actionHref={toast.actionHref}
+            duration={toast.duration}
+            onAction={toast.onAction}
+            onClose={() => dismiss(toast.id)}
+          />
+        ))}
       </div>
     </ToastContext.Provider>
   );
@@ -97,8 +359,12 @@ function ToastProvider({ children }: { children: React.ReactNode }) {
 
 function useToast() {
   const ctx = useContext(ToastContext);
-  if (!ctx) throw new Error("useToast must be used within ToastProvider");
+
+  if (!ctx) {
+    throw new Error("useToast must be used within ToastProvider");
+  }
+
   return ctx;
 }
 
-export { ToastProvider, useToast };
+export { Toast, ToastProvider, useToast };
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index cf99d92..7f482fc 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -38,7 +38,13 @@ export {
   DialogDescription,
 } from "./components/dialog";
 export { Drawer } from "./components/drawer";
-export { ToastProvider, useToast } from "./components/toast";
+export {
+  Toast,
+  ToastProvider,
+  useToast,
+  type ToastProps,
+  type ToastVariant,
+} from "./components/toast";
 export { Skeleton } from "./components/skeleton";
 export { EmptyState } from "./components/empty-state";
 export { Pagination } from "./components/pagination";