diff --git a/backend/src/app.js b/backend/src/app.js
index e57a273..d84a611 100644
--- a/backend/src/app.js
+++ b/backend/src/app.js
@@ -1,40 +1,40 @@
-import cors from "cors";
-import express from "express";
-import { Server as SocketIOServer } from "socket.io";
-import swaggerJsdoc from "swagger-jsdoc";
-import swaggerUi from "swagger-ui-express";
-import { ZodError } from "zod";
-import { httpLogger, logger } from "./lib/logger.js";
-
-import createPaymentsRouter from "./routes/payments.js";
-import merchantsRouter from "./routes/merchants.js";
-import metricsRouter from "./routes/metrics.js";
-import webhooksRouter from "./routes/webhooks.js";
-
-import { requireApiKeyAuth } from "./lib/auth.js";
-import { isHorizonReachable } from "./lib/stellar.js";
-import { supabase } from "./lib/supabase.js";
-import { pool } from "./lib/db.js";
-import { formatZodError } from "./lib/request-schemas.js";
-import { idempotencyMiddleware } from "./lib/idempotency.js";
-import {
-  createRedisRateLimitStore,
-  createVerifyPaymentRateLimit,
-} from "./lib/rate-limit.js";
-
-export async function createApp({ redisClient }) {
-  const app = express();
-
-  // Create socket.io instance (attached to HTTP server in server.js)
-  const io = new SocketIOServer({
-    cors: {
-      origin: process.env.CORS_ALLOWED_ORIGINS
-        ? process.env.CORS_ALLOWED_ORIGINS.split(",").map((o) => o.trim())
-        : ["http://localhost:3000"],
-      credentials: true,
-    },
-  });
-
+import cors from "cors";
+import express from "express";
+import { Server as SocketIOServer } from "socket.io";
+import swaggerJsdoc from "swagger-jsdoc";
+import swaggerUi from "swagger-ui-express";
+import { ZodError } from "zod";
+import { httpLogger, logger } from "./lib/logger.js";
+
+import createPaymentsRouter from "./routes/payments.js";
+import merchantsRouter from "./routes/merchants.js";
+import metricsRouter from "./routes/metrics.js";
+import webhooksRouter from "./routes/webhooks.js";
+
+import { requireApiKeyAuth } from "./lib/auth.js";
+import { isHorizonReachable } from "./lib/stellar.js";
+import { supabase } from "./lib/supabase.js";
+import { pool } from "./lib/db.js";
+import { formatZodError } from "./lib/request-schemas.js";
+import { idempotencyMiddleware } from "./lib/idempotency.js";
+import {
+  createRedisRateLimitStore,
+  createVerifyPaymentRateLimit,
+} from "./lib/rate-limit.js";
+
+export async function createApp({ redisClient }) {
+  const app = express();
+
+  // Create socket.io instance (attached to HTTP server in server.js)
+  const io = new SocketIOServer({
+    cors: {
+      origin: process.env.CORS_ALLOWED_ORIGINS
+        ? process.env.CORS_ALLOWED_ORIGINS.split(",").map((o) => o.trim())
+        : ["http://localhost:3000"],
+      credentials: true,
+    },
+  });
+
   // Socket.io room management: clients join their merchant-specific room
   io.on("connection", (socket) => {
     socket.on("join:merchant", ({ merchant_id }) => {
@@ -42,112 +42,118 @@ export async function createApp({ redisClient }) {
         socket.join(`merchant:${merchant_id}`);
       }
     });
-  });
-
-  // Make DB pool and io accessible on every request
-  app.locals.pool = pool;
-  app.locals.io = io;
-
-  const port = process.env.PORT || 4000;
-
-  const swaggerSpec = swaggerJsdoc({
-    definition: {
-      openapi: "3.0.0",
-      info: {
-        title: "Stellar Payment API",
-        version: "0.1.0",
-        description: "API for creating and verifying Stellar network payments",
-      },
-      servers: [{ url: `http://localhost:${port}` }],
-    },
-    apis: ["./src/routes/*.js"],
-  });
-
-  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
-
-  const allowedOrigins = process.env.CORS_ALLOWED_ORIGINS
-    ? process.env.CORS_ALLOWED_ORIGINS.split(",").map((o) => o.trim())
-    : ["http://localhost:3000"];
-
-  app.use(
-    cors({
-      origin: (origin, callback) => {
-        if (!origin) return callback(null, true);
-        if (allowedOrigins.includes(origin)) return callback(null, true);
-        callback(new Error("Not allowed by CORS"));
-      },
-      credentials: true,
-    }),
-  );
 
-  app.use(express.json({ limit: "1mb" }));
-  // Structured JSON logging via pino-http (replaces morgan)
-  app.use(httpLogger);
-  // Expose the root logger on app.locals so routes can use req.log or app.locals.logger
-  app.locals.logger = logger;
-
-
-  // Health check
-  app.get("/health", async (req, res) => {
-    try {
-      const [dbResult, horizonReachable] = await Promise.all([
-        supabase.from("merchants").select("id").limit(1),
-        isHorizonReachable(),
-      ]);
-
-      if (dbResult.error) {
-        return res.status(503).json({
-          ok: false,
-          error: "Database unavailable",
-          horizon_reachable: horizonReachable,
-        });
+    socket.on("join:payment", ({ payment_id }) => {
+      if (typeof payment_id === "string" && payment_id.length > 0) {
+        socket.join(`payment:${payment_id}`);
       }
-
-      if (!horizonReachable) {
-        return res.status(503).json({
-          ok: false,
-          error: "Horizon unavailable",
-          horizon_reachable: false,
-        });
-      }
-
-      res.json({ ok: true, horizon_reachable: true });
-    } catch {
-      res.status(503).json({
-        ok: false,
-        error: "Health check failed",
-        horizon_reachable: false,
-      });
-    }
-  });
-
-  const verifyPaymentRateLimit = createVerifyPaymentRateLimit({
-    store: createRedisRateLimitStore({ client: redisClient }),
-  });
-
-  app.use("/api/create-payment", requireApiKeyAuth());
-  app.use("/api/create-payment", idempotencyMiddleware);
-  app.use("/api/sessions", requireApiKeyAuth());
-  app.use("/api/sessions", idempotencyMiddleware);
-  app.use("/api/payments", requireApiKeyAuth());
-  app.use("/api/rotate-key", requireApiKeyAuth());
-  app.use("/api/merchant-branding", requireApiKeyAuth());
-  app.use("/api/webhooks", requireApiKeyAuth());
-
-  app.use("/api", createPaymentsRouter({ verifyPaymentRateLimit }));
-  app.use("/api", merchantsRouter);
-  app.use("/api", metricsRouter);
-  app.use("/api", webhooksRouter);
-
-  app.use((err, req, res, next) => {
-    if (err instanceof ZodError) {
-      return res.status(400).json({ error: formatZodError(err) });
-    }
-
-    res.status(err.status || 500).json({
-      error: err.message || "Internal Server Error",
     });
   });
-
-  return { app, io };
-}
\ No newline at end of file
+
+  // Make DB pool and io accessible on every request
+  app.locals.pool = pool;
+  app.locals.io = io;
+
+  const port = process.env.PORT || 4000;
+
+  const swaggerSpec = swaggerJsdoc({
+    definition: {
+      openapi: "3.0.0",
+      info: {
+        title: "Stellar Payment API",
+        version: "0.1.0",
+        description: "API for creating and verifying Stellar network payments",
+      },
+      servers: [{ url: `http://localhost:${port}` }],
+    },
+    apis: ["./src/routes/*.js"],
+  });
+
+  app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
+
+  const allowedOrigins = process.env.CORS_ALLOWED_ORIGINS
+    ? process.env.CORS_ALLOWED_ORIGINS.split(",").map((o) => o.trim())
+    : ["http://localhost:3000"];
+
+  app.use(
+    cors({
+      origin: (origin, callback) => {
+        if (!origin) return callback(null, true);
+        if (allowedOrigins.includes(origin)) return callback(null, true);
+        callback(new Error("Not allowed by CORS"));
+      },
+      credentials: true,
+    }),
+  );
+
+  app.use(express.json({ limit: "1mb" }));
+  // Structured JSON logging via pino-http (replaces morgan)
+  app.use(httpLogger);
+  // Expose the root logger on app.locals so routes can use req.log or app.locals.logger
+  app.locals.logger = logger;
+
+
+  // Health check
+  app.get("/health", async (req, res) => {
+    try {
+      const [dbResult, horizonReachable] = await Promise.all([
+        supabase.from("merchants").select("id").limit(1),
+        isHorizonReachable(),
+      ]);
+
+      if (dbResult.error) {
+        return res.status(503).json({
+          ok: false,
+          error: "Database unavailable",
+          horizon_reachable: horizonReachable,
+        });
+      }
+
+      if (!horizonReachable) {
+        return res.status(503).json({
+          ok: false,
+          error: "Horizon unavailable",
+          horizon_reachable: false,
+        });
+      }
+
+      res.json({ ok: true, horizon_reachable: true });
+    } catch {
+      res.status(503).json({
+        ok: false,
+        error: "Health check failed",
+        horizon_reachable: false,
+      });
+    }
+  });
+
+  const verifyPaymentRateLimit = createVerifyPaymentRateLimit({
+    store: createRedisRateLimitStore({ client: redisClient }),
+  });
+
+  app.use("/api/create-payment", requireApiKeyAuth());
+  app.use("/api/create-payment", idempotencyMiddleware);
+  app.use("/api/sessions", requireApiKeyAuth());
+  app.use("/api/sessions", idempotencyMiddleware);
+  app.use("/api/payments", requireApiKeyAuth());
+  app.use("/api/rotate-key", requireApiKeyAuth());
+  app.use("/api/merchant-branding", requireApiKeyAuth());
+  app.use("/api/webhooks", requireApiKeyAuth());
+
+  app.use("/api", createPaymentsRouter({ verifyPaymentRateLimit }));
+  app.use("/api", merchantsRouter);
+  app.use("/api", metricsRouter);
+  app.use("/api", webhooksRouter);
+
+  app.use((err, req, res, next) => {
+    if (err instanceof ZodError) {
+      return res.status(400).json({ error: formatZodError(err) });
+    }
+
+    res.status(err.status || 500).json({
+      error: err.message || "Internal Server Error",
+    });
+  });
+
+  return { app, io };
+}
diff --git a/backend/src/routes/payments.js b/backend/src/routes/payments.js
index 47a661a..de6e225 100644
--- a/backend/src/routes/payments.js
+++ b/backend/src/routes/payments.js
@@ -1,23 +1,23 @@
-import "dotenv/config";
-import express from "express";
-import rateLimit from "express-rate-limit";
-import { randomUUID } from "node:crypto";
-import {
-  findMatchingPayment,
-  createRefundTransaction,
-} from "../lib/stellar.js";
-import { supabase } from "../lib/supabase.js";
-import { validateUuidParam } from "../lib/validate-uuid.js";
-import {
-  paymentSessionZodSchema,
-  parseVersionedPaymentBody,
-} from "../lib/request-schemas.js";
-import { createCreatePaymentRateLimit } from "../lib/create-payment-rate-limit.js";
-import { sendWebhook } from "../lib/webhooks.js";
-import { resolveBrandingConfig } from "../lib/branding.js";
-
-const createPaymentRateLimit = createCreatePaymentRateLimit();
-
+import "dotenv/config";
+import express from "express";
+import rateLimit from "express-rate-limit";
+import { randomUUID } from "node:crypto";
+import {
+  findMatchingPayment,
+  createRefundTransaction,
+} from "../lib/stellar.js";
+import { supabase } from "../lib/supabase.js";
+import { validateUuidParam } from "../lib/validate-uuid.js";
+import {
+  paymentSessionZodSchema,
+  parseVersionedPaymentBody,
+} from "../lib/request-schemas.js";
+import { createCreatePaymentRateLimit } from "../lib/create-payment-rate-limit.js";
+import { sendWebhook } from "../lib/webhooks.js";
+import { resolveBrandingConfig } from "../lib/branding.js";
+
+const createPaymentRateLimit = createCreatePaymentRateLimit();
+
 const defaultVerifyPaymentRateLimit = rateLimit({
   windowMs: 15 * 60 * 1000,
   max: 10,
@@ -26,1187 +26,1215 @@ const defaultVerifyPaymentRateLimit = rateLimit({
   legacyHeaders: false,
 });
 
-function createPaymentsRouter({
-  verifyPaymentRateLimit = defaultVerifyPaymentRateLimit,
-} = {}) {
-  const router = express.Router();
-
-  /**
-   * @swagger
-   * /api/create-payment:
-   *   post:
-   *     summary: Create a new payment session request
-   *     tags: [Payments]
-   *     parameters:
-   *       - in: header
-   *         name: Idempotency-Key
-   *         schema:
-   *           type: string
-   *         description: Optional unique key for idempotent requests. Use UUID or request ID. Responses are cached for 24 hours.
-   *     requestBody:
-   *       required: true
-   *       content:
-   *         application/json:
-   *           schema:
-   *             type: object
-   *             required: [amount, asset, recipient]
-   *             properties:
-   *               amount:
-   *                 type: number
-   *                 description: Payment amount (must be positive and at least 0.01 XLM for native payments)
-   *               asset:
-   *                 type: string
-   *                 description: Asset code (e.g. XLM, USDC)
-   *               asset_issuer:
-   *                 type: string
-   *                 description: Asset issuer (required for non-native assets)
-   *               recipient:
-   *                 type: string
-   *                 description: Stellar address of the recipient
-   *               merchant_id:
-   *                 type: string
-   *               description:
-   *                 type: string
-   *               memo:
-   *                 type: string
-   *               memo_type:
-   *                 type: string
-   *                 enum: [text, id, hash, return]
-   *               webhook_url:
-   *                 type: string
-   *               branding_overrides:
-   *                 type: object
-   *                 properties:
-   *                   primary_color:
-   *                     type: string
-   *                     example: "#5ef2c0"
-   *                   secondary_color:
-   *                     type: string
-   *                     example: "#b8ffe2"
-   *                   background_color:
-   *                     type: string
-   *                     example: "#050608"
-   *     responses:
-   *       201:
-   *         description: Payment created
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 payment_id:
-   *                   type: string
-   *                 payment_link:
-   *                   type: string
-   *                 status:
-   *                   type: string
-   *                 branding_config:
-   *                   type: object
-   *       200:
-   *         description: Duplicate request — cached response returned from idempotency key
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 payment_id:
-   *                   type: string
-   *                 payment_link:
-   *                   type: string
-   *                 status:
-   *                   type: string
-   *       400:
-   *         description: Validation error or invalid Idempotency-Key
-   *       429:
-   *         description: Too many requests
-   */
-  async function createSession(req, res, next) {
-    try {
-      const body = parseVersionedPaymentBody(req);
-
-      // Per-asset payment limit validation (#153)
-      const limits = req.merchant.payment_limits;
-      if (limits && typeof limits === "object") {
-        const assetLimits = limits[body.asset];
-        if (assetLimits) {
-          if (assetLimits.min !== undefined && body.amount < assetLimits.min) {
-            return res.status(400).json({
-              error: `Amount is below the minimum for ${body.asset}`,
-              min: assetLimits.min,
-              delta: Number((assetLimits.min - body.amount).toFixed(7)),
-            });
-          }
-          if (assetLimits.max !== undefined && body.amount > assetLimits.max) {
-            return res.status(400).json({
-              error: `Amount exceeds the maximum for ${body.asset}`,
-              max: assetLimits.max,
-              delta: Number((body.amount - assetLimits.max).toFixed(7)),
-            });
-          }
-        }
-      }
-
-      // Allowed-issuers check: if the merchant has configured a non-empty
-      // allowlist, only those issuer addresses may be used.
-      const allowedIssuers = req.merchant.allowed_issuers;
-      if (Array.isArray(allowedIssuers) && allowedIssuers.length > 0) {
-        if (!body.asset_issuer || !allowedIssuers.includes(body.asset_issuer)) {
-          return res.status(400).json({
-            error: "asset_issuer is not in the merchant's list of allowed issuers",
-          });
-        }
-      }
-
-      const paymentId = randomUUID();
-      const now = new Date().toISOString();
-      const paymentLinkBase =
-        process.env.PAYMENT_LINK_BASE || "http://localhost:3000";
-      const paymentLink = `${paymentLinkBase}/pay/${paymentId}`;
-      const resolvedBrandingConfig = resolveBrandingConfig({
-        merchantBranding: req.merchant.branding_config,
-        brandingOverrides: body.branding_overrides,
-      });
-
-      const metadata =
-        body.metadata && typeof body.metadata === "object"
-          ? { ...body.metadata }
-          : {};
-      metadata.branding_config = resolvedBrandingConfig;
-
-      const payload = {
-        id: paymentId,
-        merchant_id: req.merchant.id,
-        amount: body.amount,
-        asset: body.asset,
-        asset_issuer: body.asset_issuer || null,
-        recipient: body.recipient,
-        description: body.description || null,
-        memo: body.memo || null,
-        memo_type: body.memo_type || null,
-        webhook_url: body.webhook_url || null,
-        status: "pending",
-        tx_id: null,
-        metadata,
-        created_at: now,
-      };
-
-      const { error: insertError } = await supabase
-        .from("payments")
-        .insert(payload);
-
-      if (insertError) {
-        insertError.status = 500;
-        throw insertError;
-      }
+function emitPaymentStatus(io, payment) {
+  if (!io || !payment?.id) {
+    return;
+  }
 
-      res.status(201).json({
-        payment_id: paymentId,
-        payment_link: paymentLink,
-        status: "pending",
-        branding_config: resolvedBrandingConfig,
+  const payload = {
+    id: payment.id,
+    merchant_id: payment.merchant_id ?? null,
+    amount: payment.amount,
+    asset: payment.asset,
+    asset_issuer: payment.asset_issuer ?? null,
+    recipient: payment.recipient,
+    status: payment.status,
+    tx_id: payment.tx_id ?? null,
+    updated_at: new Date().toISOString(),
+  };
+
+  io.to(`payment:${payment.id}`).emit("payment:status", payload);
+
+  if (payment.merchant_id) {
+    io.to(`merchant:${payment.merchant_id}`).emit("payment:status", payload);
+
+    if (payment.status === "confirmed") {
+      io.to(`merchant:${payment.merchant_id}`).emit("payment:confirmed", {
+        id: payment.id,
+        amount: payment.amount,
+        asset: payment.asset,
+        asset_issuer: payment.asset_issuer ?? null,
+        recipient: payment.recipient,
+        tx_id: payment.tx_id ?? null,
+        confirmed_at: payload.updated_at,
       });
-    } catch (err) {
-      next(err);
     }
   }
-
-  router.post("/create-payment", createPaymentRateLimit, createSession);
-  router.post("/sessions", createPaymentRateLimit, createSession);
-
-  /**
-   * @swagger
-   * /api/payment-status/{id}:
-   *   get:
-   *     summary: Get the status of a payment
-   *     tags: [Payments]
-   *     parameters:
-   *       - in: path
-   *         name: id
-   *         required: true
-   *         schema:
-   *           type: string
-   *         description: Payment ID
-   *     responses:
-   *       200:
-   *         description: Payment details
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 payment:
-   *                   type: object
-   *       404:
-   *         description: Payment not found
-   */
-  router.get(
-    "/payment-status/:id",
-    validateUuidParam(),
-    async (req, res, next) => {
-      try {
-        const { data, error } = await supabase
-          .from("payments")
-          .select(
-            "id, amount, asset, asset_issuer, recipient, description, memo, memo_type, status, tx_id, metadata, created_at, merchants(branding_config)",
-          )
-          .eq("id", req.params.id)
-          .maybeSingle();
-
-        if (error) {
-          error.status = 500;
-          throw error;
-        }
-
-        if (!data) {
-          return res.status(404).json({ error: "Payment not found" });
-        }
-
-        const metadataBranding = data.metadata?.branding_config || null;
-        const merchantBranding = data.merchants?.branding_config || null;
-        const brandingConfig = metadataBranding || merchantBranding || null;
-
-        const response = {
+}
+
+function createPaymentsRouter({
+  verifyPaymentRateLimit = defaultVerifyPaymentRateLimit,
+} = {}) {
+  const router = express.Router();
+
+  /**
+   * @swagger
+   * /api/create-payment:
+   *   post:
+   *     summary: Create a new payment session request
+   *     tags: [Payments]
+   *     parameters:
+   *       - in: header
+   *         name: Idempotency-Key
+   *         schema:
+   *           type: string
+   *         description: Optional unique key for idempotent requests. Use UUID or request ID. Responses are cached for 24 hours.
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [amount, asset, recipient]
+   *             properties:
+   *               amount:
+   *                 type: number
+   *                 description: Payment amount (must be positive and at least 0.01 XLM for native payments)
+   *               asset:
+   *                 type: string
+   *                 description: Asset code (e.g. XLM, USDC)
+   *               asset_issuer:
+   *                 type: string
+   *                 description: Asset issuer (required for non-native assets)
+   *               recipient:
+   *                 type: string
+   *                 description: Stellar address of the recipient
+   *               merchant_id:
+   *                 type: string
+   *               description:
+   *                 type: string
+   *               memo:
+   *                 type: string
+   *               memo_type:
+   *                 type: string
+   *                 enum: [text, id, hash, return]
+   *               webhook_url:
+   *                 type: string
+   *               branding_overrides:
+   *                 type: object
+   *                 properties:
+   *                   primary_color:
+   *                     type: string
+   *                     example: "#5ef2c0"
+   *                   secondary_color:
+   *                     type: string
+   *                     example: "#b8ffe2"
+   *                   background_color:
+   *                     type: string
+   *                     example: "#050608"
+   *     responses:
+   *       201:
+   *         description: Payment created
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 payment_id:
+   *                   type: string
+   *                 payment_link:
+   *                   type: string
+   *                 status:
+   *                   type: string
+   *                 branding_config:
+   *                   type: object
+   *       200:
+   *         description: Duplicate request — cached response returned from idempotency key
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 payment_id:
+   *                   type: string
+   *                 payment_link:
+   *                   type: string
+   *                 status:
+   *                   type: string
+   *       400:
+   *         description: Validation error or invalid Idempotency-Key
+   *       429:
+   *         description: Too many requests
+   */
+  async function createSession(req, res, next) {
+    try {
+      const body = parseVersionedPaymentBody(req);
+
+      // Per-asset payment limit validation (#153)
+      const limits = req.merchant.payment_limits;
+      if (limits && typeof limits === "object") {
+        const assetLimits = limits[body.asset];
+        if (assetLimits) {
+          if (assetLimits.min !== undefined && body.amount < assetLimits.min) {
+            return res.status(400).json({
+              error: `Amount is below the minimum for ${body.asset}`,
+              min: assetLimits.min,
+              delta: Number((assetLimits.min - body.amount).toFixed(7)),
+            });
+          }
+          if (assetLimits.max !== undefined && body.amount > assetLimits.max) {
+            return res.status(400).json({
+              error: `Amount exceeds the maximum for ${body.asset}`,
+              max: assetLimits.max,
+              delta: Number((body.amount - assetLimits.max).toFixed(7)),
+            });
+          }
+        }
+      }
+
+      // Allowed-issuers check: if the merchant has configured a non-empty
+      // allowlist, only those issuer addresses may be used.
+      const allowedIssuers = req.merchant.allowed_issuers;
+      if (Array.isArray(allowedIssuers) && allowedIssuers.length > 0) {
+        if (!body.asset_issuer || !allowedIssuers.includes(body.asset_issuer)) {
+          return res.status(400).json({
+            error: "asset_issuer is not in the merchant's list of allowed issuers",
+          });
+        }
+      }
+
+      const paymentId = randomUUID();
+      const now = new Date().toISOString();
+      const paymentLinkBase =
+        process.env.PAYMENT_LINK_BASE || "http://localhost:3000";
+      const paymentLink = `${paymentLinkBase}/pay/${paymentId}`;
+      const resolvedBrandingConfig = resolveBrandingConfig({
+        merchantBranding: req.merchant.branding_config,
+        brandingOverrides: body.branding_overrides,
+      });
+
+      const metadata =
+        body.metadata && typeof body.metadata === "object"
+          ? { ...body.metadata }
+          : {};
+      metadata.branding_config = resolvedBrandingConfig;
+
+      const payload = {
+        id: paymentId,
+        merchant_id: req.merchant.id,
+        amount: body.amount,
+        asset: body.asset,
+        asset_issuer: body.asset_issuer || null,
+        recipient: body.recipient,
+        description: body.description || null,
+        memo: body.memo || null,
+        memo_type: body.memo_type || null,
+        webhook_url: body.webhook_url || null,
+        status: "pending",
+        tx_id: null,
+        metadata,
+        created_at: now,
+      };
+
+      const { error: insertError } = await supabase
+        .from("payments")
+        .insert(payload);
+
+      if (insertError) {
+        insertError.status = 500;
+        throw insertError;
+      }
+
+      res.status(201).json({
+        payment_id: paymentId,
+        payment_link: paymentLink,
+        status: "pending",
+        branding_config: resolvedBrandingConfig,
+      });
+    } catch (err) {
+      next(err);
+    }
+  }
+
+  router.post("/create-payment", createPaymentRateLimit, createSession);
+  router.post("/sessions", createPaymentRateLimit, createSession);
+
+  /**
+   * @swagger
+   * /api/payment-status/{id}:
+   *   get:
+   *     summary: Get the status of a payment
+   *     tags: [Payments]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Payment ID
+   *     responses:
+   *       200:
+   *         description: Payment details
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 payment:
+   *                   type: object
+   *       404:
+   *         description: Payment not found
+   */
+  router.get(
+    "/payment-status/:id",
+    validateUuidParam(),
+    async (req, res, next) => {
+      try {
+        const { data, error } = await supabase
+          .from("payments")
+          .select(
+            "id, amount, asset, asset_issuer, recipient, description, memo, memo_type, status, tx_id, metadata, created_at, merchants(branding_config)",
+          )
+          .eq("id", req.params.id)
+          .maybeSingle();
+
+        if (error) {
+          error.status = 500;
+          throw error;
+        }
+
+        if (!data) {
+          return res.status(404).json({ error: "Payment not found" });
+        }
+
+        const metadataBranding = data.metadata?.branding_config || null;
+        const merchantBranding = data.merchants?.branding_config || null;
+        const brandingConfig = metadataBranding || merchantBranding || null;
+
+        const response = {
+          ...data,
+          branding_config: brandingConfig,
+        };
+        delete response.merchants;
+
+        res.json({ payment: response });
+      } catch (err) {
+        next(err);
+      }
+    },
+  );
+
+  /**
+   * @swagger
+   * /api/verify-payment/{id}:
+   *   post:
+   *     summary: Verify a payment on the Stellar network
+   *     tags: [Payments]
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Payment ID
+   *     responses:
+   *       200:
+   *         description: Verification result
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+ *                 status:
+   *                   type: string
+   *                   enum: [pending, confirmed]
+   *                 tx_id:
+   *                   type: string
+   *                 webhook:
+   *                   type: object
+   *       404:
+   *         description: Payment not found
+   */
+  router.post(
+    "/verify-payment/:id",
+    verifyPaymentRateLimit,
+    validateUuidParam(),
+    async (req, res, next) => {
+      try {
+        const { data, error } = await supabase
+          .from("payments")
+          .select(
+            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, memo, memo_type, webhook_url, merchants(webhook_secret)",
+          )
+          .eq("id", req.params.id)
+          .maybeSingle();
+
+        if (error) {
+          error.status = 500;
+          throw error;
+        }
+
+        if (!data) {
+          return res.status(404).json({ error: "Payment not found" });
+        }
+
+        if (data.status === "confirmed") {
+          return res.json({
+            status: "confirmed",
+            tx_id: data.tx_id,
+            ledger_url: `https://stellar.expert/explorer/testnet/tx/${data.tx_id}`,
+          });
+        }
+
+        const match = await findMatchingPayment({
+          recipient: data.recipient,
+          amount: data.amount,
+          assetCode: data.asset,
+          assetIssuer: data.asset_issuer,
+          memo: data.memo,
+          memoType: data.memo_type,
+        });
+
+        if (!match) {
+          return res.json({ status: "pending" });
+        }
+
+        const { error: updateError } = await supabase
+          .from("payments")
+          .update({ status: "confirmed", tx_id: match.transaction_hash })
+          .eq("id", data.id);
+
+        if (updateError) {
+          updateError.status = 500;
+          throw updateError;
+        }
+
+        emitPaymentStatus(req.app.locals.io, {
           ...data,
-          branding_config: brandingConfig,
-        };
-        delete response.merchants;
-
-        res.json({ payment: response });
-      } catch (err) {
-        next(err);
-      }
-    },
-  );
-
-  /**
-   * @swagger
-   * /api/verify-payment/{id}:
-   *   post:
-   *     summary: Verify a payment on the Stellar network
-   *     tags: [Payments]
-   *     parameters:
-   *       - in: path
-   *         name: id
-   *         required: true
-   *         schema:
-   *           type: string
-   *         description: Payment ID
-   *     responses:
-   *       200:
-   *         description: Verification result
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
- *                 status:
-   *                   type: string
-   *                   enum: [pending, confirmed]
-   *                 tx_id:
-   *                   type: string
-   *                 webhook:
-   *                   type: object
-   *       404:
-   *         description: Payment not found
-   */
-  router.post(
-    "/verify-payment/:id",
-    verifyPaymentRateLimit,
-    validateUuidParam(),
-    async (req, res, next) => {
-      try {
-        const { data, error } = await supabase
-          .from("payments")
-          .select(
-            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, memo, memo_type, webhook_url, merchants(webhook_secret)",
-          )
-          .eq("id", req.params.id)
-          .maybeSingle();
-
-        if (error) {
-          error.status = 500;
-          throw error;
-        }
-
-        if (!data) {
-          return res.status(404).json({ error: "Payment not found" });
-        }
-
-        if (data.status === "confirmed") {
-          return res.json({
-            status: "confirmed",
-            tx_id: data.tx_id,
-            ledger_url: `https://stellar.expert/explorer/testnet/tx/${data.tx_id}`,
-          });
-        }
-
-        const match = await findMatchingPayment({
-          recipient: data.recipient,
-          amount: data.amount,
-          assetCode: data.asset,
-          assetIssuer: data.asset_issuer,
-          memo: data.memo,
-          memoType: data.memo_type,
-        });
-
-        if (!match) {
-          return res.json({ status: "pending" });
-        }
-
-        const { error: updateError } = await supabase
-          .from("payments")
-          .update({ status: "confirmed", tx_id: match.transaction_hash })
-          .eq("id", data.id);
-
-        if (updateError) {
-          updateError.status = 500;
-          throw updateError;
-        }
-
-        // Emit real-time event to the merchant's private room (issue #229)
-        const io = req.app.locals.io;
-        if (io && data.merchant_id) {
-          io.to(`merchant:${data.merchant_id}`).emit("payment:confirmed", {
-            id: data.id,
-            amount: data.amount,
-            asset: data.asset,
-            asset_issuer: data.asset_issuer,
-            recipient: data.recipient,
-            tx_id: match.transaction_hash,
-            confirmed_at: new Date().toISOString(),
-          });
-        }
-
-        const merchantSecret = data.merchants?.webhook_secret;
-
-        const webhookResult = await sendWebhook(
-          data.webhook_url,
-          {
-            event: "payment.confirmed",
-            payment_id: data.id,
-            amount: data.amount,
-            asset: data.asset,
-            asset_issuer: data.asset_issuer,
-            recipient: data.recipient,
-            tx_id: match.transaction_hash,
-          },
-          merchantSecret,
-        );
-
-        if (!webhookResult.ok && !webhookResult.skipped) {
-          console.warn("Webhook failed", webhookResult);
-        }
-
-        res.json({
           status: "confirmed",
           tx_id: match.transaction_hash,
-          ledger_url: `https://stellar.expert/explorer/testnet/tx/${match.transaction_hash}`,
-          webhook: webhookResult,
         });
-      } catch (err) {
-        next(err);
-      }
-    },
-  );
-
-  /**
-   * @swagger
-   * /api/payments:
-   *   get:
-   *     summary: Get paginated list of payments for the authenticated merchant
-   *     tags: [Payments]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     parameters:
-   *       - in: query
-   *         name: page
-   *         schema:
-   *           type: integer
-   *           default: 1
-   *         description: Page number (1-indexed)
-   *       - in: query
-   *         name: limit
-   *         schema:
-   *           type: integer
-   *           default: 10
-   *         description: Number of results per page (max 100)
-   *     responses:
-   *       200:
-   *         description: Paginated payments
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 payments:
-   *                   type: array
-   *                   items:
-   *                     type: object
-   *                 total_count:
-   *                   type: integer
-   *                 total_pages:
-   *                   type: integer
-   *                 page:
-   *                   type: integer
-   *                 limit:
-   *                   type: integer
-   *       401:
-   *         description: Missing or invalid API key
-   */
-  router.get("/payments", async (req, res, next) => {
-    try {
-      let page = parseInt(req.query.page, 10) || 1;
-      let limit = parseInt(req.query.limit, 10) || 10;
-
-      if (page < 1) page = 1;
-      if (limit < 1) limit = 1;
-      if (limit > 100) limit = 100;
-
-      const offset = (page - 1) * limit;
-
-      const { count: totalCount, error: countError } = await supabase
-        .from("payments")
-        .select("*", { count: "exact", head: true })
-        .eq("merchant_id", req.merchant.id);
-
-      if (countError) {
-        countError.status = 500;
-        throw countError;
-      }
-
-      const { data: payments, error: dataError } = await supabase
-        .from("payments")
-        .select(
-          "id, amount, asset, asset_issuer, recipient, description, status, tx_id, created_at",
-        )
-        .eq("merchant_id", req.merchant.id)
-        .order("created_at", { ascending: false })
-        .range(offset, offset + limit - 1);
-
-      if (dataError) {
-        dataError.status = 500;
-        throw dataError;
-      }
-
-      const totalPages = Math.ceil(totalCount / limit);
-
-      res.json({
-        payments: payments || [],
-        total_count: totalCount,
-        total_pages: totalPages,
-        page,
-        limit,
-      });
-    } catch (err) {
-      next(err);
-    }
-  });
-
-  /**
-   * @swagger
-   * /api/metrics/7day:
-   *   get:
-   *     summary: Get 7-day rolling payment volume metrics
-   *     tags: [Metrics]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     responses:
-   *       200:
-   *         description: Daily volume data for past 7 days
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 data:
-   *                   type: array
-   *                   items:
-   *                     type: object
-   *                     properties:
-   *                       date:
-   *                         type: string
-   *                         description: Date in YYYY-MM-DD format
-   *                       volume:
-   *                         type: number
-   *                         description: Total payment amount for that day
-   *                       count:
-   *                         type: integer
-   *                         description: Number of payments on that day
-   *                 total_volume:
-   *                   type: number
-   *                   description: Total volume across all 7 days
-   *                 total_payments:
-   *                   type: integer
-   *                   description: Total payment count across all 7 days
-   *       401:
-   *         description: Missing or invalid API key
-   */
-  router.get("/metrics/7day", async (req, res, next) => {
-    try {
-      const sevenDaysAgo = new Date();
-      sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
-
-      const { data: payments, error } = await supabase
-        .from("payments")
-        .select("amount, created_at, status")
-        .eq("merchant_id", req.merchant.id)
-        .gte("created_at", sevenDaysAgo.toISOString())
-        .order("created_at", { ascending: true });
-
-      if (error) {
-        error.status = 500;
-        throw error;
-      }
-
-      const metricsMap = new Map();
-      let totalVolume = 0;
-
-      payments.forEach((payment) => {
-        const date = new Date(payment.created_at).toISOString().split("T")[0];
-        const volume = Number(payment.amount) || 0;
-
-        if (!metricsMap.has(date)) {
-          metricsMap.set(date, { date, volume: 0, count: 0 });
-        }
-
-        const dayMetric = metricsMap.get(date);
-        dayMetric.volume += volume;
-        dayMetric.count += 1;
-        totalVolume += volume;
-      });
-
-      const data = [];
-      for (let i = 6; i >= 0; i -= 1) {
-        const date = new Date();
-        date.setDate(date.getDate() - i);
-        const dateStr = date.toISOString().split("T")[0];
-
-        if (metricsMap.has(dateStr)) {
-          data.push(metricsMap.get(dateStr));
-        } else {
-          data.push({ date: dateStr, volume: 0, count: 0 });
-        }
-      }
-
-      res.json({
-        data,
-        total_volume: Number(totalVolume.toFixed(2)),
-        total_payments: payments.length,
-      });
-    } catch (err) {
-      next(err);
-    }
-  });
-
-  /**
-   * @swagger
-   * /api/payments/{id}/refund:
-   *   post:
-   *     summary: Generate a refund transaction for a confirmed payment
-   *     tags: [Payments]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     parameters:
-   *       - in: path
-   *         name: id
-   *         required: true
-   *         schema:
-   *           type: string
-   *         description: Payment ID
-   *     responses:
-   *       200:
-   *         description: Refund transaction XDR
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 xdr:
-   *                   type: string
-   *                   description: Transaction XDR to sign and submit
-   *                 hash:
-   *                   type: string
-   *                   description: Transaction hash
-   *                 instructions:
-   *                   type: string
-   *       400:
-   *         description: Payment not eligible for refund
-   *       404:
-   *         description: Payment not found
-   */
-  router.post(
-    "/payments/:id/refund",
-    validateUuidParam(),
-    async (req, res, next) => {
-      try {
-        const { data: payment, error } = await supabase
-          .from("payments")
-          .select(
-            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, metadata",
-          )
-          .eq("id", req.params.id)
-          .eq("merchant_id", req.merchant.id)
-          .maybeSingle();
-
-        if (error) {
-          error.status = 500;
-          throw error;
-        }
-
-        if (!payment) {
-          return res.status(404).json({ error: "Payment not found" });
-        }
-
-        if (payment.status !== "confirmed") {
-          return res.status(400).json({
-            error: "Only confirmed payments can be refunded",
-          });
-        }
-
-        if (payment.metadata?.refund_status === "refunded") {
-          return res.status(400).json({
-            error: "Payment already refunded",
-          });
-        }
-
-        const StellarSdk = await import("stellar-sdk");
-        const HORIZON_URL =
-          process.env.STELLAR_HORIZON_URL ||
-          (process.env.STELLAR_NETWORK === "public"
-            ? "https://horizon.stellar.org"
-            : "https://horizon-testnet.stellar.org");
-
-        const server = new StellarSdk.Horizon.Server(HORIZON_URL);
-        const tx = await server
-          .transactions()
-          .transaction(payment.tx_id)
-          .call();
-
-        const refundDestination = tx.source_account;
-
-        const refundTx = await createRefundTransaction({
-          sourceAccount: payment.recipient,
-          destination: refundDestination,
-          amount: payment.amount,
-          assetCode: payment.asset,
-          assetIssuer: payment.asset_issuer,
-          memo: `Refund: ${payment.id.substring(0, 8)}`,
-        });
-
-        await supabase
-          .from("payments")
-          .update({
-            metadata: {
-              ...payment.metadata,
-              refund_status: "pending",
-              refund_xdr: refundTx.xdr,
-              refund_created_at: new Date().toISOString(),
-            },
-          })
-          .eq("id", payment.id);
-
-        res.json({
-          xdr: refundTx.xdr,
-          hash: refundTx.hash,
-          refund_amount: payment.amount,
-          refund_destination: refundDestination,
-          instructions:
-            "Sign this transaction with your merchant wallet and submit to Stellar network. Then call POST /api/payments/:id/refund/confirm with the transaction hash.",
-        });
-      } catch (err) {
-        next(err);
-      }
-    },
-  );
-
-  /**
-   * @swagger
-   * /api/payments/{id}/refund/confirm:
-   *   post:
-   *     summary: Confirm a refund transaction has been submitted
-   *     tags: [Payments]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     parameters:
-   *       - in: path
-   *         name: id
-   *         required: true
-   *         schema:
-   *           type: string
-   *         description: Payment ID
-   *     requestBody:
-   *       required: true
-   *       content:
-   *         application/json:
-   *           schema:
-   *             type: object
-   *             required: [tx_hash]
-   *             properties:
-   *               tx_hash:
-   *                 type: string
-   *                 description: Submitted refund transaction hash
-   *     responses:
-   *       200:
-   *         description: Refund confirmed
-   *       404:
-   *         description: Payment not found
-   */
-  router.post(
-    "/payments/:id/refund/confirm",
-    validateUuidParam(),
-    async (req, res, next) => {
-      try {
-        const { tx_hash } = req.body;
-
-        if (!tx_hash) {
-          return res.status(400).json({ error: "Transaction hash required" });
-        }
-
-        const { data: payment, error } = await supabase
-          .from("payments")
-          .select("id, metadata")
-          .eq("id", req.params.id)
-          .eq("merchant_id", req.merchant.id)
-          .maybeSingle();
-
-        if (error) {
-          error.status = 500;
-          throw error;
-        }
-
-        if (!payment) {
-          return res.status(404).json({ error: "Payment not found" });
-        }
-
-        await supabase
-          .from("payments")
-          .update({
-            metadata: {
-              ...payment.metadata,
-              refund_status: "refunded",
-              refund_tx_hash: tx_hash,
-              refund_confirmed_at: new Date().toISOString(),
-            },
-          })
-          .eq("id", payment.id);
-
-        res.json({
-          status: "refunded",
-          refund_tx_hash: tx_hash,
-          message: "Refund confirmed successfully",
-        });
-      } catch (err) {
-        next(err);
-      }
-    },
-  );
-
-
-  /**
-   * Fetches the anchor's stellar.toml and extracts its SEP-0024 transfer server URL.
-   * Every SEP-compliant anchor publishes this at /.well-known/stellar.toml
-   *
-   * @param {string} anchorDomain - e.g. "testanchor.stellar.org"
-   * @returns {Promise<string>} - The TRANSFER_SERVER_SEP0024 URL
-   */
-  async function fetchAnchorToml(anchorDomain) {
-    const tomlUrl = `https://${anchorDomain}/.well-known/stellar.toml`;
-    const response = await fetch(tomlUrl);
-
-    if (!response.ok) {
-      throw Object.assign(
-        new Error(`Failed to fetch anchor TOML from ${tomlUrl}`),
-        { status: 502 }
-      );
-    }
-
-    const text = await response.text();
-
-    // Parse TRANSFER_SERVER_SEP0024 from the TOML file
-    // Example line: TRANSFER_SERVER_SEP0024 = "https://sep24.circle.com/sep24"
-    const match = text.match(/TRANSFER_SERVER_SEP0024\s*=\s*"([^"]+)"/);
-    if (!match) {
-      throw Object.assign(
-        new Error(
-          `Anchor TOML at ${tomlUrl} is missing TRANSFER_SERVER_SEP0024`
-        ),
-        { status: 502 }
-      );
-    }
-
-    return match[1]; // The base URL of the anchor's SEP-0024 API
-  }
-
-  /**
-   * @swagger
-   * /api/anchor/sep24/deposit:
-   *   post:
-   *     summary: Initiate a SEP-0024 hosted deposit (fiat → Stellar token)
-   *     description: >
-   *       Starts an interactive deposit flow with a Stellar anchor (e.g. Circle,
-   *       MoneyGram). Returns a URL the frontend should open in a popup — the anchor
-   *       hosts the deposit form, so no bank details are ever sent to this API.
-   *     tags: [Anchor / SEP-0024]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     requestBody:
-   *       required: true
-   *       content:
-   *         application/json:
-   *           schema:
-   *             type: object
-   *             required: [asset_code, account]
-   *             properties:
-   *               asset_code:
-   *                 type: string
-   *                 description: Stellar asset code to deposit (e.g. USDC, EURC)
-   *                 example: USDC
-   *               account:
-   *                 type: string
-   *                 description: User's Stellar public key that will receive the tokens
-   *               amount:
-   *                 type: number
-   *                 description: Optional pre-fill amount for the deposit form
-   *               anchor_domain:
-   *                 type: string
-   *                 description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
-   *                 example: testanchor.stellar.org
-   *     responses:
-   *       200:
-   *         description: Interactive deposit URL from the anchor
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 type:
-   *                   type: string
-   *                   example: interactive_customer_info_needed
-   *                 url:
-   *                   type: string
-   *                   description: Open this URL in a popup for the user to complete the deposit
-   *                 id:
-   *                   type: string
-   *                   description: Anchor transaction ID — use this to poll /anchor/sep24/transaction/:id
-   *                 anchor_domain:
-   *                   type: string
-   *       400:
-   *         description: Missing required fields
-   *       500:
-   *         description: ANCHOR_DOMAIN not configured
-   *       502:
-   *         description: Anchor request failed
-   */
-  router.post("/anchor/sep24/deposit", async (req, res, next) => {
-    try {
-      const { asset_code, account, amount, anchor_domain } = req.body;
-
-      if (!asset_code || !account) {
-        return res.status(400).json({
-          error: "asset_code and account are required",
-        });
-      }
-
-      const domain = anchor_domain || process.env.ANCHOR_DOMAIN;
-      if (!domain) {
-        return res.status(500).json({
-          error:
-            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file (e.g. testanchor.stellar.org)",
-        });
-      }
-
-      // Step 1: Read the anchor's TOML to get its SEP-0024 server URL
-      const transferServer = await fetchAnchorToml(domain);
-
-      // Step 2: Call the anchor's deposit endpoint
-      // The anchor returns a URL for the user to open — we never see bank details
-      const anchorRes = await fetch(
-        `${transferServer}/transactions/deposit/interactive`,
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            // If your anchor requires a JWT bearer token, add it here:
-            // "Authorization": `Bearer ${your_sep10_jwt}`,
-          },
-          body: JSON.stringify({
-            asset_code,
-            account,
-            ...(amount !== undefined && { amount: String(amount) }),
-          }),
-        }
-      );
-
-      if (!anchorRes.ok) {
-        const errBody = await anchorRes.text();
-        return res.status(502).json({
-          error: "Anchor rejected the deposit request",
-          anchor_status: anchorRes.status,
-          detail: errBody,
-        });
-      }
-
-      const anchorData = await anchorRes.json();
-
-      // anchorData shape (SEP-0024 spec):
-      // {
-      //   type: "interactive_customer_info_needed",
-      //   url:  "https://anchor.example.com/sep24/transactions/deposit?token=...",
-      //   id:   "2cb4c100-a1e2-4273-9b2c-abc123"
-      // }
-      res.json({
-        type: anchorData.type,
-        url: anchorData.url,           // Frontend opens this in a popup
-        id: anchorData.id,             // Poll this with GET /anchor/sep24/transaction/:id
-        anchor_domain: domain,
-      });
-    } catch (err) {
-      next(err);
-    }
-  });
-
-  /**
-   * @swagger
-   * /api/anchor/sep24/withdraw:
-   *   post:
-   *     summary: Initiate a SEP-0024 hosted withdrawal (Stellar token → fiat)
-   *     description: >
-   *       Starts an interactive withdrawal flow with a Stellar anchor. Returns a URL
-   *       the frontend opens in a popup where the user enters their bank/cash-out details.
-   *     tags: [Anchor / SEP-0024]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     requestBody:
-   *       required: true
-   *       content:
-   *         application/json:
-   *           schema:
-   *             type: object
-   *             required: [asset_code, account]
-   *             properties:
-   *               asset_code:
-   *                 type: string
-   *                 description: Stellar asset code to withdraw (e.g. USDC, EURC)
-   *                 example: USDC
-   *               account:
-   *                 type: string
-   *                 description: User's Stellar public key that holds the tokens
-   *               amount:
-   *                 type: number
-   *                 description: Optional pre-fill amount for the withdrawal form
-   *               anchor_domain:
-   *                 type: string
-   *                 description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
-   *     responses:
-   *       200:
-   *         description: Interactive withdrawal URL from the anchor
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 type:
-   *                   type: string
-   *                   example: interactive_customer_info_needed
-   *                 url:
-   *                   type: string
-   *                   description: Open this URL in a popup for the user to complete the withdrawal
-   *                 id:
-   *                   type: string
-   *                   description: Anchor transaction ID for polling
-   *                 anchor_domain:
-   *                   type: string
-   *       400:
-   *         description: Missing required fields
-   *       500:
-   *         description: ANCHOR_DOMAIN not configured
-   *       502:
-   *         description: Anchor request failed
-   */
-  router.post("/anchor/sep24/withdraw", async (req, res, next) => {
-    try {
-      const { asset_code, account, amount, anchor_domain } = req.body;
-
-      if (!asset_code || !account) {
-        return res.status(400).json({
-          error: "asset_code and account are required",
-        });
-      }
-
-      const domain = anchor_domain || process.env.ANCHOR_DOMAIN;
-      if (!domain) {
-        return res.status(500).json({
-          error:
-            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file (e.g. testanchor.stellar.org)",
-        });
-      }
-
-      // Step 1: Discover the anchor's SEP-0024 server from its TOML
-      const transferServer = await fetchAnchorToml(domain);
-
-      // Step 2: Call the anchor's withdrawal endpoint
-      const anchorRes = await fetch(
-        `${transferServer}/transactions/withdraw/interactive`,
-        {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            // "Authorization": `Bearer ${your_sep10_jwt}`,
-          },
-          body: JSON.stringify({
-            asset_code,
-            account,
-            ...(amount !== undefined && { amount: String(amount) }),
-          }),
-        }
-      );
-
-      if (!anchorRes.ok) {
-        const errBody = await anchorRes.text();
-        return res.status(502).json({
-          error: "Anchor rejected the withdrawal request",
-          anchor_status: anchorRes.status,
-          detail: errBody,
-        });
-      }
-
-      const anchorData = await anchorRes.json();
-
-      res.json({
-        type: anchorData.type,
-        url: anchorData.url,           // Frontend opens this in a popup
-        id: anchorData.id,             // Poll this with GET /anchor/sep24/transaction/:id
-        anchor_domain: domain,
-      });
-    } catch (err) {
-      next(err);
-    }
-  });
-
-  /**
-   * @swagger
-   * /api/anchor/sep24/transaction/{id}:
-   *   get:
-   *     summary: Poll the status of a SEP-0024 anchor transaction
-   *     description: >
-   *       Fetches the current status of a deposit or withdrawal transaction from
-   *       the anchor. Call this repeatedly after the user closes the popup to check
-   *       whether the transaction has completed.
-   *     tags: [Anchor / SEP-0024]
-   *     security:
-   *       - ApiKeyAuth: []
-   *     parameters:
-   *       - in: path
-   *         name: id
-   *         required: true
-   *         schema:
-   *           type: string
-   *         description: Anchor transaction ID returned from /deposit or /withdraw
-   *       - in: query
-   *         name: anchor_domain
-   *         schema:
-   *           type: string
-   *         description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
-   *     responses:
-   *       200:
-   *         description: Transaction object from the anchor
-   *         content:
-   *           application/json:
-   *             schema:
-   *               type: object
-   *               properties:
-   *                 transaction:
-   *                   type: object
-   *                   properties:
-   *                     id:
-   *                       type: string
-   *                     status:
-   *                       type: string
-   *                       description: >
-   *                         One of: incomplete, pending_user_transfer_start,
-   *                         pending_anchor, pending_stellar, completed, error
-   *                     amount_in:
-   *                       type: string
-   *                     amount_out:
-   *                       type: string
-   *                     stellar_transaction_id:
-   *                       type: string
-   *                     more_info_url:
-   *                       type: string
-   *       400:
-   *         description: Missing transaction ID
-   *       500:
-   *         description: ANCHOR_DOMAIN not configured
-   *       502:
-   *         description: Anchor request failed
-   */
-  router.get("/anchor/sep24/transaction/:id", async (req, res, next) => {
-    try {
-      const { id } = req.params;
-
-      if (!id) {
-        return res.status(400).json({ error: "Transaction ID is required" });
-      }
-
-      const domain = req.query.anchor_domain || process.env.ANCHOR_DOMAIN;
-      if (!domain) {
-        return res.status(500).json({
-          error:
-            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file",
-        });
-      }
-
-      // Discover the anchor's SEP-0024 server
-      const transferServer = await fetchAnchorToml(domain);
-
-      // Fetch the transaction status from the anchor
-      const anchorRes = await fetch(
-        `${transferServer}/transaction?id=${encodeURIComponent(id)}`,
-        {
-          headers: {
-            // "Authorization": `Bearer ${your_sep10_jwt}`,
-          },
-        }
-      );
-
-      if (!anchorRes.ok) {
-        return res.status(502).json({
-          error: "Failed to fetch transaction status from anchor",
-          anchor_status: anchorRes.status,
-        });
-      }
-
-      const data = await anchorRes.json();
-
-      // Anchor response shape (SEP-0024 spec):
-      // {
-      //   transaction: {
-      //     id:                     "2cb4c100-...",
-      //     kind:                   "deposit",
-      //     status:                 "completed",   ← watch this field
-      //     amount_in:              "100.00",
-      //     amount_out:             "99.50",
-      //     amount_fee:             "0.50",
-      //     stellar_transaction_id: "abc123...",   ← on-chain tx hash when done
-      //     more_info_url:          "https://..."
-      //   }
-      // }
-      //
-      // Possible status values:
-      //   incomplete                  — user hasn't finished the popup form yet
-      //   pending_user_transfer_start — waiting for user to send Stellar tokens (withdraw only)
-      //   pending_anchor              — anchor is processing
-      //   pending_stellar             — anchor is waiting for Stellar confirmation
-      //   completed                   — done, tokens delivered
-      //   error                       — something went wrong on the anchor's side
-
-      res.json(data);
-    } catch (err) {
-      next(err);
-    }
-  });
-
-  return router;
-}
-
-export default createPaymentsRouter;
\ No newline at end of file
+
+        const merchantSecret = data.merchants?.webhook_secret;
+
+        const webhookResult = await sendWebhook(
+          data.webhook_url,
+          {
+            event: "payment.confirmed",
+            payment_id: data.id,
+            amount: data.amount,
+            asset: data.asset,
+            asset_issuer: data.asset_issuer,
+            recipient: data.recipient,
+            tx_id: match.transaction_hash,
+          },
+          merchantSecret,
+        );
+
+        if (!webhookResult.ok && !webhookResult.skipped) {
+          console.warn("Webhook failed", webhookResult);
+        }
+
+        res.json({
+          status: "confirmed",
+          tx_id: match.transaction_hash,
+          ledger_url: `https://stellar.expert/explorer/testnet/tx/${match.transaction_hash}`,
+          webhook: webhookResult,
+        });
+      } catch (err) {
+        next(err);
+      }
+    },
+  );
+
+  /**
+   * @swagger
+   * /api/payments:
+   *   get:
+   *     summary: Get paginated list of payments for the authenticated merchant
+   *     tags: [Payments]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     parameters:
+   *       - in: query
+   *         name: page
+   *         schema:
+   *           type: integer
+   *           default: 1
+   *         description: Page number (1-indexed)
+   *       - in: query
+   *         name: limit
+   *         schema:
+   *           type: integer
+   *           default: 10
+   *         description: Number of results per page (max 100)
+   *     responses:
+   *       200:
+   *         description: Paginated payments
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 payments:
+   *                   type: array
+   *                   items:
+   *                     type: object
+   *                 total_count:
+   *                   type: integer
+   *                 total_pages:
+   *                   type: integer
+   *                 page:
+   *                   type: integer
+   *                 limit:
+   *                   type: integer
+   *       401:
+   *         description: Missing or invalid API key
+   */
+  router.get("/payments", async (req, res, next) => {
+    try {
+      let page = parseInt(req.query.page, 10) || 1;
+      let limit = parseInt(req.query.limit, 10) || 10;
+
+      if (page < 1) page = 1;
+      if (limit < 1) limit = 1;
+      if (limit > 100) limit = 100;
+
+      const offset = (page - 1) * limit;
+
+      const { count: totalCount, error: countError } = await supabase
+        .from("payments")
+        .select("*", { count: "exact", head: true })
+        .eq("merchant_id", req.merchant.id);
+
+      if (countError) {
+        countError.status = 500;
+        throw countError;
+      }
+
+      const { data: payments, error: dataError } = await supabase
+        .from("payments")
+        .select(
+          "id, amount, asset, asset_issuer, recipient, description, status, tx_id, created_at",
+        )
+        .eq("merchant_id", req.merchant.id)
+        .order("created_at", { ascending: false })
+        .range(offset, offset + limit - 1);
+
+      if (dataError) {
+        dataError.status = 500;
+        throw dataError;
+      }
+
+      const totalPages = Math.ceil(totalCount / limit);
+
+      res.json({
+        payments: payments || [],
+        total_count: totalCount,
+        total_pages: totalPages,
+        page,
+        limit,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  /**
+   * @swagger
+   * /api/metrics/7day:
+   *   get:
+   *     summary: Get 7-day rolling payment volume metrics
+   *     tags: [Metrics]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     responses:
+   *       200:
+   *         description: Daily volume data for past 7 days
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 data:
+   *                   type: array
+   *                   items:
+   *                     type: object
+   *                     properties:
+   *                       date:
+   *                         type: string
+   *                         description: Date in YYYY-MM-DD format
+   *                       volume:
+   *                         type: number
+   *                         description: Total payment amount for that day
+   *                       count:
+   *                         type: integer
+   *                         description: Number of payments on that day
+   *                 total_volume:
+   *                   type: number
+   *                   description: Total volume across all 7 days
+   *                 total_payments:
+   *                   type: integer
+   *                   description: Total payment count across all 7 days
+   *       401:
+   *         description: Missing or invalid API key
+   */
+  router.get("/metrics/7day", async (req, res, next) => {
+    try {
+      const sevenDaysAgo = new Date();
+      sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+
+      const { data: payments, error } = await supabase
+        .from("payments")
+        .select("amount, created_at, status")
+        .eq("merchant_id", req.merchant.id)
+        .gte("created_at", sevenDaysAgo.toISOString())
+        .order("created_at", { ascending: true });
+
+      if (error) {
+        error.status = 500;
+        throw error;
+      }
+
+      const metricsMap = new Map();
+      let totalVolume = 0;
+
+      payments.forEach((payment) => {
+        const date = new Date(payment.created_at).toISOString().split("T")[0];
+        const volume = Number(payment.amount) || 0;
+
+        if (!metricsMap.has(date)) {
+          metricsMap.set(date, { date, volume: 0, count: 0 });
+        }
+
+        const dayMetric = metricsMap.get(date);
+        dayMetric.volume += volume;
+        dayMetric.count += 1;
+        totalVolume += volume;
+      });
+
+      const data = [];
+      for (let i = 6; i >= 0; i -= 1) {
+        const date = new Date();
+        date.setDate(date.getDate() - i);
+        const dateStr = date.toISOString().split("T")[0];
+
+        if (metricsMap.has(dateStr)) {
+          data.push(metricsMap.get(dateStr));
+        } else {
+          data.push({ date: dateStr, volume: 0, count: 0 });
+        }
+      }
+
+      res.json({
+        data,
+        total_volume: Number(totalVolume.toFixed(2)),
+        total_payments: payments.length,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  /**
+   * @swagger
+   * /api/payments/{id}/refund:
+   *   post:
+   *     summary: Generate a refund transaction for a confirmed payment
+   *     tags: [Payments]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Payment ID
+   *     responses:
+   *       200:
+   *         description: Refund transaction XDR
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 xdr:
+   *                   type: string
+   *                   description: Transaction XDR to sign and submit
+   *                 hash:
+   *                   type: string
+   *                   description: Transaction hash
+   *                 instructions:
+   *                   type: string
+   *       400:
+   *         description: Payment not eligible for refund
+   *       404:
+   *         description: Payment not found
+   */
+  router.post(
+    "/payments/:id/refund",
+    validateUuidParam(),
+    async (req, res, next) => {
+      try {
+        const { data: payment, error } = await supabase
+          .from("payments")
+          .select(
+            "id, merchant_id, amount, asset, asset_issuer, recipient, status, tx_id, metadata",
+          )
+          .eq("id", req.params.id)
+          .eq("merchant_id", req.merchant.id)
+          .maybeSingle();
+
+        if (error) {
+          error.status = 500;
+          throw error;
+        }
+
+        if (!payment) {
+          return res.status(404).json({ error: "Payment not found" });
+        }
+
+        if (payment.status !== "confirmed") {
+          return res.status(400).json({
+            error: "Only confirmed payments can be refunded",
+          });
+        }
+
+        if (payment.metadata?.refund_status === "refunded") {
+          return res.status(400).json({
+            error: "Payment already refunded",
+          });
+        }
+
+        const StellarSdk = await import("stellar-sdk");
+        const HORIZON_URL =
+          process.env.STELLAR_HORIZON_URL ||
+          (process.env.STELLAR_NETWORK === "public"
+            ? "https://horizon.stellar.org"
+            : "https://horizon-testnet.stellar.org");
+
+        const server = new StellarSdk.Horizon.Server(HORIZON_URL);
+        const tx = await server
+          .transactions()
+          .transaction(payment.tx_id)
+          .call();
+
+        const refundDestination = tx.source_account;
+
+        const refundTx = await createRefundTransaction({
+          sourceAccount: payment.recipient,
+          destination: refundDestination,
+          amount: payment.amount,
+          assetCode: payment.asset,
+          assetIssuer: payment.asset_issuer,
+          memo: `Refund: ${payment.id.substring(0, 8)}`,
+        });
+
+        await supabase
+          .from("payments")
+          .update({
+            metadata: {
+              ...payment.metadata,
+              refund_status: "pending",
+              refund_xdr: refundTx.xdr,
+              refund_created_at: new Date().toISOString(),
+            },
+          })
+          .eq("id", payment.id);
+
+        res.json({
+          xdr: refundTx.xdr,
+          hash: refundTx.hash,
+          refund_amount: payment.amount,
+          refund_destination: refundDestination,
+          instructions:
+            "Sign this transaction with your merchant wallet and submit to Stellar network. Then call POST /api/payments/:id/refund/confirm with the transaction hash.",
+        });
+      } catch (err) {
+        next(err);
+      }
+    },
+  );
+
+  /**
+   * @swagger
+   * /api/payments/{id}/refund/confirm:
+   *   post:
+   *     summary: Confirm a refund transaction has been submitted
+   *     tags: [Payments]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Payment ID
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [tx_hash]
+   *             properties:
+   *               tx_hash:
+   *                 type: string
+   *                 description: Submitted refund transaction hash
+   *     responses:
+   *       200:
+   *         description: Refund confirmed
+   *       404:
+   *         description: Payment not found
+   */
+  router.post(
+    "/payments/:id/refund/confirm",
+    validateUuidParam(),
+    async (req, res, next) => {
+      try {
+        const { tx_hash } = req.body;
+
+        if (!tx_hash) {
+          return res.status(400).json({ error: "Transaction hash required" });
+        }
+
+        const { data: payment, error } = await supabase
+          .from("payments")
+          .select("id, metadata")
+          .eq("id", req.params.id)
+          .eq("merchant_id", req.merchant.id)
+          .maybeSingle();
+
+        if (error) {
+          error.status = 500;
+          throw error;
+        }
+
+        if (!payment) {
+          return res.status(404).json({ error: "Payment not found" });
+        }
+
+        await supabase
+          .from("payments")
+          .update({
+            metadata: {
+              ...payment.metadata,
+              refund_status: "refunded",
+              refund_tx_hash: tx_hash,
+              refund_confirmed_at: new Date().toISOString(),
+            },
+          })
+          .eq("id", payment.id);
+
+        res.json({
+          status: "refunded",
+          refund_tx_hash: tx_hash,
+          message: "Refund confirmed successfully",
+        });
+      } catch (err) {
+        next(err);
+      }
+    },
+  );
+
+
+  /**
+   * Fetches the anchor's stellar.toml and extracts its SEP-0024 transfer server URL.
+   * Every SEP-compliant anchor publishes this at /.well-known/stellar.toml
+   *
+   * @param {string} anchorDomain - e.g. "testanchor.stellar.org"
+   * @returns {Promise<string>} - The TRANSFER_SERVER_SEP0024 URL
+   */
+  async function fetchAnchorToml(anchorDomain) {
+    const tomlUrl = `https://${anchorDomain}/.well-known/stellar.toml`;
+    const response = await fetch(tomlUrl);
+
+    if (!response.ok) {
+      throw Object.assign(
+        new Error(`Failed to fetch anchor TOML from ${tomlUrl}`),
+        { status: 502 }
+      );
+    }
+
+    const text = await response.text();
+
+    // Parse TRANSFER_SERVER_SEP0024 from the TOML file
+    // Example line: TRANSFER_SERVER_SEP0024 = "https://sep24.circle.com/sep24"
+    const match = text.match(/TRANSFER_SERVER_SEP0024\s*=\s*"([^"]+)"/);
+    if (!match) {
+      throw Object.assign(
+        new Error(
+          `Anchor TOML at ${tomlUrl} is missing TRANSFER_SERVER_SEP0024`
+        ),
+        { status: 502 }
+      );
+    }
+
+    return match[1]; // The base URL of the anchor's SEP-0024 API
+  }
+
+  /**
+   * @swagger
+   * /api/anchor/sep24/deposit:
+   *   post:
+   *     summary: Initiate a SEP-0024 hosted deposit (fiat → Stellar token)
+   *     description: >
+   *       Starts an interactive deposit flow with a Stellar anchor (e.g. Circle,
+   *       MoneyGram). Returns a URL the frontend should open in a popup — the anchor
+   *       hosts the deposit form, so no bank details are ever sent to this API.
+   *     tags: [Anchor / SEP-0024]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [asset_code, account]
+   *             properties:
+   *               asset_code:
+   *                 type: string
+   *                 description: Stellar asset code to deposit (e.g. USDC, EURC)
+   *                 example: USDC
+   *               account:
+   *                 type: string
+   *                 description: User's Stellar public key that will receive the tokens
+   *               amount:
+   *                 type: number
+   *                 description: Optional pre-fill amount for the deposit form
+   *               anchor_domain:
+   *                 type: string
+   *                 description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
+   *                 example: testanchor.stellar.org
+   *     responses:
+   *       200:
+   *         description: Interactive deposit URL from the anchor
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 type:
+   *                   type: string
+   *                   example: interactive_customer_info_needed
+   *                 url:
+   *                   type: string
+   *                   description: Open this URL in a popup for the user to complete the deposit
+   *                 id:
+   *                   type: string
+   *                   description: Anchor transaction ID — use this to poll /anchor/sep24/transaction/:id
+   *                 anchor_domain:
+   *                   type: string
+   *       400:
+   *         description: Missing required fields
+   *       500:
+   *         description: ANCHOR_DOMAIN not configured
+   *       502:
+   *         description: Anchor request failed
+   */
+  router.post("/anchor/sep24/deposit", async (req, res, next) => {
+    try {
+      const { asset_code, account, amount, anchor_domain } = req.body;
+
+      if (!asset_code || !account) {
+        return res.status(400).json({
+          error: "asset_code and account are required",
+        });
+      }
+
+      const domain = anchor_domain || process.env.ANCHOR_DOMAIN;
+      if (!domain) {
+        return res.status(500).json({
+          error:
+            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file (e.g. testanchor.stellar.org)",
+        });
+      }
+
+      // Step 1: Read the anchor's TOML to get its SEP-0024 server URL
+      const transferServer = await fetchAnchorToml(domain);
+
+      // Step 2: Call the anchor's deposit endpoint
+      // The anchor returns a URL for the user to open — we never see bank details
+      const anchorRes = await fetch(
+        `${transferServer}/transactions/deposit/interactive`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // If your anchor requires a JWT bearer token, add it here:
+            // "Authorization": `Bearer ${your_sep10_jwt}`,
+          },
+          body: JSON.stringify({
+            asset_code,
+            account,
+            ...(amount !== undefined && { amount: String(amount) }),
+          }),
+        }
+      );
+
+      if (!anchorRes.ok) {
+        const errBody = await anchorRes.text();
+        return res.status(502).json({
+          error: "Anchor rejected the deposit request",
+          anchor_status: anchorRes.status,
+          detail: errBody,
+        });
+      }
+
+      const anchorData = await anchorRes.json();
+
+      // anchorData shape (SEP-0024 spec):
+      // {
+      //   type: "interactive_customer_info_needed",
+      //   url:  "https://anchor.example.com/sep24/transactions/deposit?token=...",
+      //   id:   "2cb4c100-a1e2-4273-9b2c-abc123"
+      // }
+      res.json({
+        type: anchorData.type,
+        url: anchorData.url,           // Frontend opens this in a popup
+        id: anchorData.id,             // Poll this with GET /anchor/sep24/transaction/:id
+        anchor_domain: domain,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  /**
+   * @swagger
+   * /api/anchor/sep24/withdraw:
+   *   post:
+   *     summary: Initiate a SEP-0024 hosted withdrawal (Stellar token → fiat)
+   *     description: >
+   *       Starts an interactive withdrawal flow with a Stellar anchor. Returns a URL
+   *       the frontend opens in a popup where the user enters their bank/cash-out details.
+   *     tags: [Anchor / SEP-0024]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     requestBody:
+   *       required: true
+   *       content:
+   *         application/json:
+   *           schema:
+   *             type: object
+   *             required: [asset_code, account]
+   *             properties:
+   *               asset_code:
+   *                 type: string
+   *                 description: Stellar asset code to withdraw (e.g. USDC, EURC)
+   *                 example: USDC
+   *               account:
+   *                 type: string
+   *                 description: User's Stellar public key that holds the tokens
+   *               amount:
+   *                 type: number
+   *                 description: Optional pre-fill amount for the withdrawal form
+   *               anchor_domain:
+   *                 type: string
+   *                 description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
+   *     responses:
+   *       200:
+   *         description: Interactive withdrawal URL from the anchor
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 type:
+   *                   type: string
+   *                   example: interactive_customer_info_needed
+   *                 url:
+   *                   type: string
+   *                   description: Open this URL in a popup for the user to complete the withdrawal
+   *                 id:
+   *                   type: string
+   *                   description: Anchor transaction ID for polling
+   *                 anchor_domain:
+   *                   type: string
+   *       400:
+   *         description: Missing required fields
+   *       500:
+   *         description: ANCHOR_DOMAIN not configured
+   *       502:
+   *         description: Anchor request failed
+   */
+  router.post("/anchor/sep24/withdraw", async (req, res, next) => {
+    try {
+      const { asset_code, account, amount, anchor_domain } = req.body;
+
+      if (!asset_code || !account) {
+        return res.status(400).json({
+          error: "asset_code and account are required",
+        });
+      }
+
+      const domain = anchor_domain || process.env.ANCHOR_DOMAIN;
+      if (!domain) {
+        return res.status(500).json({
+          error:
+            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file (e.g. testanchor.stellar.org)",
+        });
+      }
+
+      // Step 1: Discover the anchor's SEP-0024 server from its TOML
+      const transferServer = await fetchAnchorToml(domain);
+
+      // Step 2: Call the anchor's withdrawal endpoint
+      const anchorRes = await fetch(
+        `${transferServer}/transactions/withdraw/interactive`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // "Authorization": `Bearer ${your_sep10_jwt}`,
+          },
+          body: JSON.stringify({
+            asset_code,
+            account,
+            ...(amount !== undefined && { amount: String(amount) }),
+          }),
+        }
+      );
+
+      if (!anchorRes.ok) {
+        const errBody = await anchorRes.text();
+        return res.status(502).json({
+          error: "Anchor rejected the withdrawal request",
+          anchor_status: anchorRes.status,
+          detail: errBody,
+        });
+      }
+
+      const anchorData = await anchorRes.json();
+
+      res.json({
+        type: anchorData.type,
+        url: anchorData.url,           // Frontend opens this in a popup
+        id: anchorData.id,             // Poll this with GET /anchor/sep24/transaction/:id
+        anchor_domain: domain,
+      });
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  /**
+   * @swagger
+   * /api/anchor/sep24/transaction/{id}:
+   *   get:
+   *     summary: Poll the status of a SEP-0024 anchor transaction
+   *     description: >
+   *       Fetches the current status of a deposit or withdrawal transaction from
+   *       the anchor. Call this repeatedly after the user closes the popup to check
+   *       whether the transaction has completed.
+   *     tags: [Anchor / SEP-0024]
+   *     security:
+   *       - ApiKeyAuth: []
+   *     parameters:
+   *       - in: path
+   *         name: id
+   *         required: true
+   *         schema:
+   *           type: string
+   *         description: Anchor transaction ID returned from /deposit or /withdraw
+   *       - in: query
+   *         name: anchor_domain
+   *         schema:
+   *           type: string
+   *         description: Anchor domain override (defaults to ANCHOR_DOMAIN env var)
+   *     responses:
+   *       200:
+   *         description: Transaction object from the anchor
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 transaction:
+   *                   type: object
+   *                   properties:
+   *                     id:
+   *                       type: string
+   *                     status:
+   *                       type: string
+   *                       description: >
+   *                         One of: incomplete, pending_user_transfer_start,
+   *                         pending_anchor, pending_stellar, completed, error
+   *                     amount_in:
+   *                       type: string
+   *                     amount_out:
+   *                       type: string
+   *                     stellar_transaction_id:
+   *                       type: string
+   *                     more_info_url:
+   *                       type: string
+   *       400:
+   *         description: Missing transaction ID
+   *       500:
+   *         description: ANCHOR_DOMAIN not configured
+   *       502:
+   *         description: Anchor request failed
+   */
+  router.get("/anchor/sep24/transaction/:id", async (req, res, next) => {
+    try {
+      const { id } = req.params;
+
+      if (!id) {
+        return res.status(400).json({ error: "Transaction ID is required" });
+      }
+
+      const domain = req.query.anchor_domain || process.env.ANCHOR_DOMAIN;
+      if (!domain) {
+        return res.status(500).json({
+          error:
+            "No anchor domain configured. Set ANCHOR_DOMAIN in your .env file",
+        });
+      }
+
+      // Discover the anchor's SEP-0024 server
+      const transferServer = await fetchAnchorToml(domain);
+
+      // Fetch the transaction status from the anchor
+      const anchorRes = await fetch(
+        `${transferServer}/transaction?id=${encodeURIComponent(id)}`,
+        {
+          headers: {
+            // "Authorization": `Bearer ${your_sep10_jwt}`,
+          },
+        }
+      );
+
+      if (!anchorRes.ok) {
+        return res.status(502).json({
+          error: "Failed to fetch transaction status from anchor",
+          anchor_status: anchorRes.status,
+        });
+      }
+
+      const data = await anchorRes.json();
+
+      // Anchor response shape (SEP-0024 spec):
+      // {
+      //   transaction: {
+      //     id:                     "2cb4c100-...",
+      //     kind:                   "deposit",
+      //     status:                 "completed",   ← watch this field
+      //     amount_in:              "100.00",
+      //     amount_out:             "99.50",
+      //     amount_fee:             "0.50",
+      //     stellar_transaction_id: "abc123...",   ← on-chain tx hash when done
+      //     more_info_url:          "https://..."
+      //   }
+      // }
+      //
+      // Possible status values:
+      //   incomplete                  — user hasn't finished the popup form yet
+      //   pending_user_transfer_start — waiting for user to send Stellar tokens (withdraw only)
+      //   pending_anchor              — anchor is processing
+      //   pending_stellar             — anchor is waiting for Stellar confirmation
+      //   completed                   — done, tokens delivered
+      //   error                       — something went wrong on the anchor's side
+
+      res.json(data);
+    } catch (err) {
+      next(err);
+    }
+  });
+
+  return router;
+}
+
+export default createPaymentsRouter;
diff --git a/frontend/src/app/(public)/pay/[id]/page.tsx b/frontend/src/app/(public)/pay/[id]/page.tsx
index 47d2b67..d898854 100644
--- a/frontend/src/app/(public)/pay/[id]/page.tsx
+++ b/frontend/src/app/(public)/pay/[id]/page.tsx
@@ -1,530 +1,527 @@
-"use client";
-
-import { useEffect, useState, type CSSProperties } from "react";
+"use client";
+
+import { useEffect, useState, type CSSProperties } from "react";
 import { useParams } from "next/navigation";
 import { useWallet } from "@/lib/wallet-context";
 import { usePayment } from "@/lib/usePayment";
+import { usePaymentStatusSocket } from "@/lib/usePaymentSocket";
 import CopyButton from "@/components/CopyButton";
 import WalletSelector from "@/components/WalletSelector";
 import toast from "react-hot-toast";
-import Skeleton, { SkeletonTheme } from "react-loading-skeleton";
-import "react-loading-skeleton/dist/skeleton.css";
-import { QRCodeSVG } from "qrcode.react";
-
-const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
-
-// Use Stellar.expert as the block explorer (Horizon is an API, not an explorer).
-// Defaults to testnet; set NEXT_PUBLIC_STELLAR_NETWORK=public for mainnet.
-const NETWORK = process.env.NEXT_PUBLIC_STELLAR_NETWORK ?? "testnet";
-const EXPLORER_BASE =
-  NETWORK === "public"
-    ? "https://stellar.expert/explorer/public"
-    : "https://stellar.expert/explorer/testnet";
-
-interface PaymentDetails {
-  id: string;
-  amount: number;
-  asset: string;
-  asset_issuer: string | null;
-  recipient: string;
-  description: string | null;
-  memo?: string | null;
-  memo_type?: string | null;
-  status: string; // pending | confirmed | completed | failed
-  tx_id: string | null;
-  created_at: string;
-  branding_config?: {
-    primary_color?: string;
-    secondary_color?: string;
-    background_color?: string;
-  } | null;
-}
-
-const DEFAULT_CHECKOUT_THEME = {
-  primary_color: "#5ef2c0",
-  secondary_color: "#b8ffe2",
-  background_color: "#050608",
-};
-
-// ─── Asset badge ────────────────────────────────────────────────────────────
-
-function AssetBadge({ asset }: { asset: string }) {
-  const a = asset.toUpperCase();
-  if (a === "XLM" || a === "NATIVE") {
-    return (
-      <span
-        aria-hidden="true"
-        className="inline-flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-white/15 via-mint/20 to-mint/40 text-mint shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
-      >
-        <svg viewBox="0 0 24 24" className="h-5 w-5" fill="none" stroke="currentColor" strokeWidth={1.8}>
-          <path d="M14.5 3.5 9 9l4.5.5L13 14l5.5-5.5" strokeLinecap="round" strokeLinejoin="round" />
-          <path d="M6 18c3.5-1 6-3.5 7-7" strokeLinecap="round" />
-          <path d="M7.5 16.5 4.5 19.5" strokeLinecap="round" />
-        </svg>
-      </span>
-    );
-  }
-  if (a === "USDC") {
-    return (
-      <span
-        aria-hidden="true"
-        className="inline-flex h-10 w-10 items-center justify-center rounded-full bg-[#2775CA] text-[10px] font-bold tracking-[0.18em] text-white shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
-      >
-        USDC
-      </span>
-    );
-  }
-  return (
-    <span className="inline-flex h-10 w-10 items-center justify-center rounded-full border border-white/20 bg-white/10 text-xs font-bold text-white">
-      {asset.slice(0, 3)}
-    </span>
-  );
-}
-
-// ─── Status badge ────────────────────────────────────────────────────────────
-
-const STATUS_MAP: Record<string, { label: string; classes: string }> = {
-  pending:   { label: "Awaiting Payment",  classes: "bg-yellow-500/15 text-yellow-400 border border-yellow-500/30" },
-  confirmed: { label: "Confirmed",         classes: "bg-mint/10 text-mint border border-mint/30" },
-  completed: { label: "Completed",         classes: "bg-green-500/15 text-green-400 border border-green-500/30" },
-  failed:    { label: "Failed",            classes: "bg-red-500/15 text-red-400 border border-red-500/30" },
-};
-
-function StatusBadge({ status }: { status: string }) {
-  const s = STATUS_MAP[status.toLowerCase()] ?? {
-    label: status,
-    classes: "bg-white/10 text-slate-400 border border-white/10",
-  };
-  return (
-    <span className={`rounded-full px-3 py-1 text-xs font-semibold ${s.classes}`}>
-      {s.label}
-    </span>
-  );
-}
-
-function buildSep7Uri(payment: PaymentDetails) {
-  const params = new URLSearchParams({
-    destination: payment.recipient,
-    amount: String(payment.amount),
-    asset_code: payment.asset.toUpperCase(),
-  });
-
-  if (payment.asset_issuer) {
-    params.set("asset_issuer", payment.asset_issuer);
-  }
-  if (payment.memo) {
-    params.set("memo", payment.memo);
-  }
-  if (payment.memo_type) {
-    params.set("memo_type", payment.memo_type);
-  }
-
-  return `web+stellar:pay?${params.toString()}`;
-}
-
-// ─── Skeleton ─────────────────────────────────────────────────────────────────
-
-/**
- * Mirrors the layout of the real payment card so there is no layout shift
- * once data loads. Themed to match the dark design system.
- */
-function LoadingSkeleton() {
-  return (
-    <SkeletonTheme baseColor="#151d2e" highlightColor="#1f2d44">
-      <main className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-8 px-6 py-16">
-        {/* Header */}
-        <header className="flex flex-col gap-2">
-          <Skeleton width={96} height={12} borderRadius={999} />
-          <Skeleton width={220} height={36} borderRadius={10} />
-          <Skeleton width={280} height={10} borderRadius={999} />
-        </header>
-
-        {/* Card */}
-        <div className="rounded-3xl border border-white/10 bg-white/5 shadow-2xl backdrop-blur overflow-hidden">
-
-          {/* Hero section */}
-          <div className="flex flex-col items-center gap-3 border-b border-white/10 px-8 py-10">
-            {/* Asset badge */}
-            <Skeleton circle width={40} height={40} />
-            {/* Amount */}
-            <Skeleton width={200} height={52} borderRadius={10} />
-            {/* Description line */}
-            <Skeleton width={140} height={14} borderRadius={999} />
-            {/* Status badge */}
-            <Skeleton width={120} height={26} borderRadius={999} />
-          </div>
-
-          {/* Details section */}
-          <div className="flex flex-col gap-5 p-8">
-            {/* Recipient */}
-            <div className="flex flex-col gap-1.5">
-              <Skeleton width={72} height={10} borderRadius={999} />
-              <Skeleton height={46} borderRadius={12} />
-            </div>
-
-            {/* Created date */}
-            <div className="flex flex-col gap-1">
-              <Skeleton width={56} height={10} borderRadius={999} />
-              <Skeleton width={160} height={16} borderRadius={6} />
-            </div>
-
-            {/* CTA button */}
-            <Skeleton height={48} borderRadius={12} className="mt-2" />
-          </div>
-        </div>
-      </main>
-    </SkeletonTheme>
-  );
-}
-
-// ─── Page ─────────────────────────────────────────────────────────────────────
-
-export default function PaymentPage() {
-  const params = useParams();
-  const paymentId = params.id as string;
-
-  const [payment, setPayment] = useState<PaymentDetails | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [fetchError, setFetchError] = useState<string | null>(null);
-  const [actionError, setActionError] = useState<string | null>(null);
-  const [walletReady, setWalletReady] = useState(false);
-
-  const { activeProvider } = useWallet();
-  const { isProcessing, status: txStatus, error: paymentError, processPayment } = usePayment(activeProvider);
-
-  const networkPassphrase =
-    process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE ||
-    "Test SDF Network ; September 2015";
-
-  // ── Fetch payment details ──────────────────────────────────────────────────
+import Skeleton, { SkeletonTheme } from "react-loading-skeleton";
+import "react-loading-skeleton/dist/skeleton.css";
+import { QRCodeSVG } from "qrcode.react";
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+
+// Use Stellar.expert as the block explorer (Horizon is an API, not an explorer).
+// Defaults to testnet; set NEXT_PUBLIC_STELLAR_NETWORK=public for mainnet.
+const NETWORK = process.env.NEXT_PUBLIC_STELLAR_NETWORK ?? "testnet";
+const EXPLORER_BASE =
+  NETWORK === "public"
+    ? "https://stellar.expert/explorer/public"
+    : "https://stellar.expert/explorer/testnet";
+
+interface PaymentDetails {
+  id: string;
+  amount: number;
+  asset: string;
+  asset_issuer: string | null;
+  recipient: string;
+  description: string | null;
+  memo?: string | null;
+  memo_type?: string | null;
+  status: string; // pending | confirmed | completed | failed
+  tx_id: string | null;
+  created_at: string;
+  branding_config?: {
+    primary_color?: string;
+    secondary_color?: string;
+    background_color?: string;
+  } | null;
+}
+
+const DEFAULT_CHECKOUT_THEME = {
+  primary_color: "#5ef2c0",
+  secondary_color: "#b8ffe2",
+  background_color: "#050608",
+};
+
+// ─── Asset badge ────────────────────────────────────────────────────────────
+
+function AssetBadge({ asset }: { asset: string }) {
+  const a = asset.toUpperCase();
+  if (a === "XLM" || a === "NATIVE") {
+    return (
+      <span
+        aria-hidden="true"
+        className="inline-flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-white/15 via-mint/20 to-mint/40 text-mint shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
+      >
+        <svg viewBox="0 0 24 24" className="h-5 w-5" fill="none" stroke="currentColor" strokeWidth={1.8}>
+          <path d="M14.5 3.5 9 9l4.5.5L13 14l5.5-5.5" strokeLinecap="round" strokeLinejoin="round" />
+          <path d="M6 18c3.5-1 6-3.5 7-7" strokeLinecap="round" />
+          <path d="M7.5 16.5 4.5 19.5" strokeLinecap="round" />
+        </svg>
+      </span>
+    );
+  }
+  if (a === "USDC") {
+    return (
+      <span
+        aria-hidden="true"
+        className="inline-flex h-10 w-10 items-center justify-center rounded-full bg-[#2775CA] text-[10px] font-bold tracking-[0.18em] text-white shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
+      >
+        USDC
+      </span>
+    );
+  }
+  return (
+    <span className="inline-flex h-10 w-10 items-center justify-center rounded-full border border-white/20 bg-white/10 text-xs font-bold text-white">
+      {asset.slice(0, 3)}
+    </span>
+  );
+}
+
+// ─── Status badge ────────────────────────────────────────────────────────────
+
+const STATUS_MAP: Record<string, { label: string; classes: string }> = {
+  pending:   { label: "Awaiting Payment",  classes: "bg-yellow-500/15 text-yellow-400 border border-yellow-500/30" },
+  confirmed: { label: "Confirmed",         classes: "bg-mint/10 text-mint border border-mint/30" },
+  completed: { label: "Completed",         classes: "bg-green-500/15 text-green-400 border border-green-500/30" },
+  failed:    { label: "Failed",            classes: "bg-red-500/15 text-red-400 border border-red-500/30" },
+};
+
+function StatusBadge({ status }: { status: string }) {
+  const s = STATUS_MAP[status.toLowerCase()] ?? {
+    label: status,
+    classes: "bg-white/10 text-slate-400 border border-white/10",
+  };
+  return (
+    <span className={`rounded-full px-3 py-1 text-xs font-semibold ${s.classes}`}>
+      {s.label}
+    </span>
+  );
+}
+
+function buildSep7Uri(payment: PaymentDetails) {
+  const params = new URLSearchParams({
+    destination: payment.recipient,
+    amount: String(payment.amount),
+    asset_code: payment.asset.toUpperCase(),
+  });
+
+  if (payment.asset_issuer) {
+    params.set("asset_issuer", payment.asset_issuer);
+  }
+  if (payment.memo) {
+    params.set("memo", payment.memo);
+  }
+  if (payment.memo_type) {
+    params.set("memo_type", payment.memo_type);
+  }
+
+  return `web+stellar:pay?${params.toString()}`;
+}
+
+// ─── Skeleton ─────────────────────────────────────────────────────────────────
+
+/**
+ * Mirrors the layout of the real payment card so there is no layout shift
+ * once data loads. Themed to match the dark design system.
+ */
+function LoadingSkeleton() {
+  return (
+    <SkeletonTheme baseColor="#151d2e" highlightColor="#1f2d44">
+      <main className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-8 px-6 py-16">
+        {/* Header */}
+        <header className="flex flex-col gap-2">
+          <Skeleton width={96} height={12} borderRadius={999} />
+          <Skeleton width={220} height={36} borderRadius={10} />
+          <Skeleton width={280} height={10} borderRadius={999} />
+        </header>
+
+        {/* Card */}
+        <div className="rounded-3xl border border-white/10 bg-white/5 shadow-2xl backdrop-blur overflow-hidden">
+
+          {/* Hero section */}
+          <div className="flex flex-col items-center gap-3 border-b border-white/10 px-8 py-10">
+            {/* Asset badge */}
+            <Skeleton circle width={40} height={40} />
+            {/* Amount */}
+            <Skeleton width={200} height={52} borderRadius={10} />
+            {/* Description line */}
+            <Skeleton width={140} height={14} borderRadius={999} />
+            {/* Status badge */}
+            <Skeleton width={120} height={26} borderRadius={999} />
+          </div>
+
+          {/* Details section */}
+          <div className="flex flex-col gap-5 p-8">
+            {/* Recipient */}
+            <div className="flex flex-col gap-1.5">
+              <Skeleton width={72} height={10} borderRadius={999} />
+              <Skeleton height={46} borderRadius={12} />
+            </div>
+
+            {/* Created date */}
+            <div className="flex flex-col gap-1">
+              <Skeleton width={56} height={10} borderRadius={999} />
+              <Skeleton width={160} height={16} borderRadius={6} />
+            </div>
+
+            {/* CTA button */}
+            <Skeleton height={48} borderRadius={12} className="mt-2" />
+          </div>
+        </div>
+      </main>
+    </SkeletonTheme>
+  );
+}
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+export default function PaymentPage() {
+  const params = useParams();
+  const paymentId = params.id as string;
+
+  const [payment, setPayment] = useState<PaymentDetails | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [fetchError, setFetchError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [walletReady, setWalletReady] = useState(false);
+
+  const { activeProvider } = useWallet();
+  const { isProcessing, status: txStatus, error: paymentError, processPayment } = usePayment(activeProvider);
+
+  const networkPassphrase =
+    process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE ||
+    "Test SDF Network ; September 2015";
+
+  // ── Fetch payment details ──────────────────────────────────────────────────
   useEffect(() => {
     const controller = new AbortController();
-
-    const load = async () => {
-      try {
-        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`, {
-          signal: controller.signal,
-        });
-        if (res.status === 404) throw new Error("Payment not found.");
-        if (!res.ok) throw new Error("Could not load payment details.");
-        const data = await res.json();
-        setPayment(data.payment);
-      } catch (err: unknown) {
-        if (err instanceof Error && err.name === "AbortError") return;
-        setFetchError(err instanceof Error ? err.message : "Failed to load payment.");
-      } finally {
-        setLoading(false);
-      }
-    };
-
+
+    const load = async () => {
+      try {
+        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`, {
+          signal: controller.signal,
+        });
+        if (res.status === 404) throw new Error("Payment not found.");
+        if (!res.ok) throw new Error("Could not load payment details.");
+        const data = await res.json();
+        setPayment(data.payment);
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        setFetchError(err instanceof Error ? err.message : "Failed to load payment.");
+      } finally {
+        setLoading(false);
+      }
+    };
+
     load();
     return () => controller.abort();
   }, [paymentId]);
 
-  // ── Poll until settled ─────────────────────────────────────────────────────
-  useEffect(() => {
-    if (loading || !payment) return;
-    const settled = ["confirmed", "completed", "failed"].includes(payment.status);
-    if (settled) return;
-
-    const id = setInterval(async () => {
-      try {
-        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`);
-        if (!res.ok) return;
-        const data = await res.json();
-        if (data.payment) setPayment(data.payment);
-      } catch { /* silent — retry next tick */ }
-    }, 5000);
-
-    return () => clearInterval(id);
-  }, [paymentId, payment, loading]);
-
-  // ── Wallet readiness ───────────────────────────────────────────────────────
-  useEffect(() => {
-    setWalletReady(!!activeProvider);
-  }, [activeProvider]);
-
-  // ── Pay handler ───────────────────────────────────────────────────────────
-  const handlePay = async () => {
-    if (!payment) return;
-    setActionError(null);
-
-    try {
-      const result = await processPayment({
-        recipient: payment.recipient,
-        amount: String(payment.amount),
-        assetCode: payment.asset,
-        assetIssuer: payment.asset_issuer,
-      });
-
-      setPayment({ ...payment, status: "completed", tx_id: result.hash });
-      toast.success("Payment sent!");
-
-      // Best-effort backend verification
-      setTimeout(async () => {
-        try {
-          await fetch(`${API_URL}/api/verify-payment/${paymentId}`, { method: "POST" });
-        } catch { /* non-critical */ }
-      }, 2000);
-    } catch {
-      const msg = paymentError ?? "Payment failed. Please try again.";
-      setActionError(msg);
-      toast.error(msg);
-    }
-  };
-
-  // ── Early returns ──────────────────────────────────────────────────────────
-  if (loading) return <LoadingSkeleton />;
-
-  if (fetchError || !payment) {
-    return (
-      <main className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-6 px-6 py-16">
-        <div className="rounded-2xl border border-red-500/30 bg-red-500/10 p-8 text-center">
-          <p className="text-sm font-medium uppercase tracking-wider text-red-400">Error</p>
-          <h1 className="mt-3 text-lg font-semibold text-white">
-            {fetchError ?? "Payment not found"}
-          </h1>
-          <p className="mt-2 text-sm text-slate-400">
-            Check the payment link and try again, or contact the sender.
-          </p>
-        </div>
-      </main>
-    );
-  }
-
-  const isSettled = payment.status === "confirmed" || payment.status === "completed";
-  const isFailed  = payment.status === "failed";
-  const checkoutTheme = {
-    ...DEFAULT_CHECKOUT_THEME,
-    ...(payment.branding_config || {}),
-  };
-
-  return (
-    <>
-      {/* ── Full-screen processing overlay ── */}
-      {isProcessing && (
-        <div className="fixed inset-0 z-50 flex flex-col items-center justify-center gap-5 bg-black/85 backdrop-blur-sm">
-          <div className="h-14 w-14 animate-spin rounded-full border-4 border-white/15 border-t-mint" />
-          <div className="flex flex-col items-center gap-1 text-center">
-            <p className="text-base font-semibold text-white">
-              {txStatus ?? "Processing transaction…"}
-            </p>
-            <p className="text-sm text-slate-400">Do not close this tab</p>
-          </div>
-        </div>
-      )}
-
-      <main
-        className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-8 px-6 py-16"
-        style={
-          {
-            "--checkout-primary": checkoutTheme.primary_color,
-            "--checkout-secondary": checkoutTheme.secondary_color,
-            "--checkout-bg": checkoutTheme.background_color,
-            background:
-              "radial-gradient(1200px circle at 10% -10%, color-mix(in srgb, var(--checkout-primary) 18%, #15233b) 0%, var(--checkout-bg) 45%, #050608 100%)",
-          } as CSSProperties
-        }
-      >
-        {/* ── Page header ── */}
-        <header className="flex flex-col gap-2">
-          <p className="font-mono text-xs uppercase tracking-[0.3em]" style={{ color: "var(--checkout-primary)" }}>
-            Payment Request
-          </p>
-          <h1 className="text-3xl font-bold text-white">Complete Payment</h1>
-          <p className="font-mono text-xs text-slate-500 break-all">
-            ID: {payment.id}
-          </p>
-        </header>
-
-        {/* ── Main card ── */}
-        <div className="rounded-3xl border border-white/10 bg-white/5 shadow-2xl backdrop-blur">
-
-          {/* Amount hero */}
-          <div className="flex flex-col items-center gap-3 border-b border-white/10 px-8 py-10">
-            <AssetBadge asset={payment.asset} />
-            <div className="flex items-baseline gap-2">
-              <span className="text-5xl font-bold tracking-tight text-white">
-                {payment.amount.toLocaleString(undefined, {
-                  minimumFractionDigits: 0,
-                  maximumFractionDigits: 7,
-                })}
-              </span>
-              <span className="text-2xl font-semibold" style={{ color: "var(--checkout-secondary)" }}>
-                {payment.asset.toUpperCase()}
-              </span>
-            </div>
-            {payment.description && (
-              <p className="mt-1 text-sm text-slate-400">{payment.description}</p>
-            )}
-            <StatusBadge status={payment.status} />
-          </div>
-
-          {/* Details */}
-          <div className="flex flex-col gap-5 p-8">
-
-      {/* Recipient */}
-      <div className="flex flex-col gap-1.5">
-        <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
-          Recipient
-        </p>
-        <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-          <code className="flex-1 truncate font-mono text-sm text-slate-200">
-            {payment.recipient}
-          </code>
-          <CopyButton text={payment.recipient} />
-        </div>
-      </div>
-
-      {/* QR Code */}
-      <div className="flex flex-col gap-1.5">
-        <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
-          Scan to Pay
-        </p>
-        <div className="flex items-center justify-center rounded-xl border border-white/10 bg-white p-4">
-          <QRCodeSVG
-            value={payment.recipient}
-            size={160}
-            level="M"
-            bgColor="#ffffff"
-            fgColor="#000000"
-          />
-        </div>
-        <p className="text-center text-xs text-slate-500">
-          Scan with Freighter or any Stellar wallet
-        </p>
-        <div className="sm:hidden">
-          {/* Mobile-only SEP-0007 fallback for manual wallet paste */}
-          <button
-            type="button"
-            onClick={() => setShowRawIntent((prev) => !prev)}
-            className="mx-auto mt-2 text-xs font-medium text-mint transition-colors hover:text-glow"
-          >
-            {showRawIntent ? "Hide raw intent link" : "View raw intent link"}
-          </button>
-          {showRawIntent && (
-            <div className="mt-3 flex items-start gap-2 rounded-lg border border-white/10 bg-black/40 p-3">
-              <code className="flex-1 break-all font-mono text-[11px] text-slate-200">
-                {buildSep7Uri(payment)}
-              </code>
-              <CopyButton text={buildSep7Uri(payment)} className="mt-0.5" />
-            </div>
-          )}
-        </div>
-      </div>
-
-            {/* Date */}
-            <div className="flex flex-col gap-1">
-              <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
-                Created
-              </p>
-              <p className="text-sm text-slate-300">
-                {new Date(payment.created_at).toLocaleString(undefined, {
-                  dateStyle: "medium",
-                  timeStyle: "short",
-                })}
-              </p>
-            </div>
-
-            {/* Transaction hash (after payment) */}
-            {payment.tx_id && (
-              <div className="flex flex-col gap-1.5">
-                <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
-                  Transaction
-                </p>
-                <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                  <a
-                    href={`${EXPLORER_BASE}/tx/${payment.tx_id}`}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    className="flex-1 truncate font-mono text-sm text-mint underline underline-offset-2 hover:text-glow"
-                  >
-                    {payment.tx_id}
-                  </a>
-                  <CopyButton text={payment.tx_id} />
-                </div>
-              </div>
-            )}
-
-            {/* Action error */}
-            {actionError && (
-              <div
-                role="alert"
-                className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-400"
-              >
-                {actionError}
-              </div>
-            )}
-
-            {/* ── CTA section ── */}
-            {!isSettled && !isFailed && (
-              <div className="flex flex-col gap-3 pt-2">
-                {walletReady ? (
-                  <>
-                    <p className="text-center text-xs text-slate-500">
-                      Connected via {activeProvider?.name}
-                    </p>
-                    <button
-                      type="button"
-                      onClick={handlePay}
-                      disabled={isProcessing}
-                      className="group relative flex h-12 w-full items-center justify-center rounded-xl bg-mint font-bold text-black transition-all hover:bg-glow disabled:cursor-not-allowed disabled:opacity-50"
-                    >
-                      {isProcessing ? (
-                        <span className="flex items-center gap-2">
-                          <svg className="h-4 w-4 animate-spin" viewBox="0 0 24 24">
-                            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
-                            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                          </svg>
-                          Processing…
-                        </span>
-                      ) : (
-                        `Pay with ${activeProvider?.name ?? "Wallet"}`
-                      )}
-                      <div className="absolute inset-0 -z-10 bg-mint/20 opacity-0 blur-xl transition-opacity group-hover:opacity-100" />
-                    </button>
-                  </>
-                ) : (
-                  <WalletSelector
-                    networkPassphrase={networkPassphrase}
-                    onConnected={() => setWalletReady(true)}
-                  />
-                )}
-              </div>
-            )}
-
-            {/* Settled success note */}
-            {isSettled && (
-              <div
-                className="rounded-xl border p-4 text-center"
-                style={{
-                  borderColor: "color-mix(in srgb, var(--checkout-primary) 30%, transparent)",
-                  backgroundColor: "color-mix(in srgb, var(--checkout-primary) 7%, transparent)",
-                }}
-              >
-                <p className="text-sm font-semibold" style={{ color: "var(--checkout-primary)" }}>
-                  This payment has been received.
-                </p>
-                <p className="mt-1 text-xs text-slate-400">
-                  The transaction was confirmed on the Stellar network.
-                </p>
-              </div>
-            )}
+  usePaymentStatusSocket(paymentId, (event) => {
+    setPayment((current) => {
+      if (!current || current.id !== event.id) {
+        return current;
+      }
 
-            {/* Failed note */}
-            {isFailed && (
-              <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-center">
-                <p className="text-sm font-semibold text-red-400">
-                  This payment has failed.
-                </p>
-                <p className="mt-1 text-xs text-slate-500">
-                  Contact the merchant if you believe this is an error.
-                </p>
-              </div>
-            )}
-          </div>
-        </div>
-      </main>
-    </>
-  );
-}
+      return {
+        ...current,
+        status: event.status,
+        tx_id: event.tx_id,
+      };
+    });
+  });
+
+  // ── Wallet readiness ───────────────────────────────────────────────────────
+  useEffect(() => {
+    setWalletReady(!!activeProvider);
+  }, [activeProvider]);
+
+  // ── Pay handler ───────────────────────────────────────────────────────────
+  const handlePay = async () => {
+    if (!payment) return;
+    setActionError(null);
+
+    try {
+      const result = await processPayment({
+        recipient: payment.recipient,
+        amount: String(payment.amount),
+        assetCode: payment.asset,
+        assetIssuer: payment.asset_issuer,
+      });
+
+      setPayment({ ...payment, status: "completed", tx_id: result.hash });
+      toast.success("Payment sent!");
+
+      // Best-effort backend verification
+      setTimeout(async () => {
+        try {
+          await fetch(`${API_URL}/api/verify-payment/${paymentId}`, { method: "POST" });
+        } catch { /* non-critical */ }
+      }, 2000);
+    } catch {
+      const msg = paymentError ?? "Payment failed. Please try again.";
+      setActionError(msg);
+      toast.error(msg);
+    }
+  };
+
+  // ── Early returns ──────────────────────────────────────────────────────────
+  if (loading) return <LoadingSkeleton />;
+
+  if (fetchError || !payment) {
+    return (
+      <main className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-6 px-6 py-16">
+        <div className="rounded-2xl border border-red-500/30 bg-red-500/10 p-8 text-center">
+          <p className="text-sm font-medium uppercase tracking-wider text-red-400">Error</p>
+          <h1 className="mt-3 text-lg font-semibold text-white">
+            {fetchError ?? "Payment not found"}
+          </h1>
+          <p className="mt-2 text-sm text-slate-400">
+            Check the payment link and try again, or contact the sender.
+          </p>
+        </div>
+      </main>
+    );
+  }
+
+  const isSettled = payment.status === "confirmed" || payment.status === "completed";
+  const isFailed  = payment.status === "failed";
+  const checkoutTheme = {
+    ...DEFAULT_CHECKOUT_THEME,
+    ...(payment.branding_config || {}),
+  };
+
+  return (
+    <>
+      {/* ── Full-screen processing overlay ── */}
+      {isProcessing && (
+        <div className="fixed inset-0 z-50 flex flex-col items-center justify-center gap-5 bg-black/85 backdrop-blur-sm">
+          <div className="h-14 w-14 animate-spin rounded-full border-4 border-white/15 border-t-mint" />
+          <div className="flex flex-col items-center gap-1 text-center">
+            <p className="text-base font-semibold text-white">
+              {txStatus ?? "Processing transaction…"}
+            </p>
+            <p className="text-sm text-slate-400">Do not close this tab</p>
+          </div>
+        </div>
+      )}
+
+      <main
+        className="mx-auto flex min-h-screen max-w-lg flex-col justify-center gap-8 px-6 py-16"
+        style={
+          {
+            "--checkout-primary": checkoutTheme.primary_color,
+            "--checkout-secondary": checkoutTheme.secondary_color,
+            "--checkout-bg": checkoutTheme.background_color,
+            background:
+              "radial-gradient(1200px circle at 10% -10%, color-mix(in srgb, var(--checkout-primary) 18%, #15233b) 0%, var(--checkout-bg) 45%, #050608 100%)",
+          } as CSSProperties
+        }
+      >
+        {/* ── Page header ── */}
+        <header className="flex flex-col gap-2">
+          <p className="font-mono text-xs uppercase tracking-[0.3em]" style={{ color: "var(--checkout-primary)" }}>
+            Payment Request
+          </p>
+          <h1 className="text-3xl font-bold text-white">Complete Payment</h1>
+          <p className="font-mono text-xs text-slate-500 break-all">
+            ID: {payment.id}
+          </p>
+        </header>
+
+        {/* ── Main card ── */}
+        <div className="rounded-3xl border border-white/10 bg-white/5 shadow-2xl backdrop-blur">
+
+          {/* Amount hero */}
+          <div className="flex flex-col items-center gap-3 border-b border-white/10 px-8 py-10">
+            <AssetBadge asset={payment.asset} />
+            <div className="flex items-baseline gap-2">
+              <span className="text-5xl font-bold tracking-tight text-white">
+                {payment.amount.toLocaleString(undefined, {
+                  minimumFractionDigits: 0,
+                  maximumFractionDigits: 7,
+                })}
+              </span>
+              <span className="text-2xl font-semibold" style={{ color: "var(--checkout-secondary)" }}>
+                {payment.asset.toUpperCase()}
+              </span>
+            </div>
+            {payment.description && (
+              <p className="mt-1 text-sm text-slate-400">{payment.description}</p>
+            )}
+            <StatusBadge status={payment.status} />
+          </div>
+
+          {/* Details */}
+          <div className="flex flex-col gap-5 p-8">
+
+      {/* Recipient */}
+      <div className="flex flex-col gap-1.5">
+        <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
+          Recipient
+        </p>
+        <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+          <code className="flex-1 truncate font-mono text-sm text-slate-200">
+            {payment.recipient}
+          </code>
+          <CopyButton text={payment.recipient} />
+        </div>
+      </div>
+
+      {/* QR Code */}
+      <div className="flex flex-col gap-1.5">
+        <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
+          Scan to Pay
+        </p>
+        <div className="flex items-center justify-center rounded-xl border border-white/10 bg-white p-4">
+          <QRCodeSVG
+            value={payment.recipient}
+            size={160}
+            level="M"
+            bgColor="#ffffff"
+            fgColor="#000000"
+          />
+        </div>
+        <p className="text-center text-xs text-slate-500">
+          Scan with Freighter or any Stellar wallet
+        </p>
+        <div className="sm:hidden">
+          {/* Mobile-only SEP-0007 fallback for manual wallet paste */}
+          <button
+            type="button"
+            onClick={() => setShowRawIntent((prev) => !prev)}
+            className="mx-auto mt-2 text-xs font-medium text-mint transition-colors hover:text-glow"
+          >
+            {showRawIntent ? "Hide raw intent link" : "View raw intent link"}
+          </button>
+          {showRawIntent && (
+            <div className="mt-3 flex items-start gap-2 rounded-lg border border-white/10 bg-black/40 p-3">
+              <code className="flex-1 break-all font-mono text-[11px] text-slate-200">
+                {buildSep7Uri(payment)}
+              </code>
+              <CopyButton text={buildSep7Uri(payment)} className="mt-0.5" />
+            </div>
+          )}
+        </div>
+      </div>
+
+            {/* Date */}
+            <div className="flex flex-col gap-1">
+              <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
+                Created
+              </p>
+              <p className="text-sm text-slate-300">
+                {new Date(payment.created_at).toLocaleString(undefined, {
+                  dateStyle: "medium",
+                  timeStyle: "short",
+                })}
+              </p>
+            </div>
+
+            {/* Transaction hash (after payment) */}
+            {payment.tx_id && (
+              <div className="flex flex-col gap-1.5">
+                <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
+                  Transaction
+                </p>
+                <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                  <a
+                    href={`${EXPLORER_BASE}/tx/${payment.tx_id}`}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="flex-1 truncate font-mono text-sm text-mint underline underline-offset-2 hover:text-glow"
+                  >
+                    {payment.tx_id}
+                  </a>
+                  <CopyButton text={payment.tx_id} />
+                </div>
+              </div>
+            )}
+
+            {/* Action error */}
+            {actionError && (
+              <div
+                role="alert"
+                className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-400"
+              >
+                {actionError}
+              </div>
+            )}
+
+            {/* ── CTA section ── */}
+            {!isSettled && !isFailed && (
+              <div className="flex flex-col gap-3 pt-2">
+                {walletReady ? (
+                  <>
+                    <p className="text-center text-xs text-slate-500">
+                      Connected via {activeProvider?.name}
+                    </p>
+                    <button
+                      type="button"
+                      onClick={handlePay}
+                      disabled={isProcessing}
+                      className="group relative flex h-12 w-full items-center justify-center rounded-xl bg-mint font-bold text-black transition-all hover:bg-glow disabled:cursor-not-allowed disabled:opacity-50"
+                    >
+                      {isProcessing ? (
+                        <span className="flex items-center gap-2">
+                          <svg className="h-4 w-4 animate-spin" viewBox="0 0 24 24">
+                            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+                            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                          </svg>
+                          Processing…
+                        </span>
+                      ) : (
+                        `Pay with ${activeProvider?.name ?? "Wallet"}`
+                      )}
+                      <div className="absolute inset-0 -z-10 bg-mint/20 opacity-0 blur-xl transition-opacity group-hover:opacity-100" />
+                    </button>
+                  </>
+                ) : (
+                  <WalletSelector
+                    networkPassphrase={networkPassphrase}
+                    onConnected={() => setWalletReady(true)}
+                  />
+                )}
+              </div>
+            )}
+
+            {/* Settled success note */}
+            {isSettled && (
+              <div
+                className="rounded-xl border p-4 text-center"
+                style={{
+                  borderColor: "color-mix(in srgb, var(--checkout-primary) 30%, transparent)",
+                  backgroundColor: "color-mix(in srgb, var(--checkout-primary) 7%, transparent)",
+                }}
+              >
+                <p className="text-sm font-semibold" style={{ color: "var(--checkout-primary)" }}>
+                  This payment has been received.
+                </p>
+                <p className="mt-1 text-xs text-slate-400">
+                  The transaction was confirmed on the Stellar network.
+                </p>
+              </div>
+            )}
+
+            {/* Failed note */}
+            {isFailed && (
+              <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-center">
+                <p className="text-sm font-semibold text-red-400">
+                  This payment has failed.
+                </p>
+                <p className="mt-1 text-xs text-slate-500">
+                  Contact the merchant if you believe this is an error.
+                </p>
+              </div>
+            )}
+          </div>
+        </div>
+      </main>
+    </>
+  );
+}
diff --git a/frontend/src/components/PaymentDetailModal.tsx b/frontend/src/components/PaymentDetailModal.tsx
index 127b06a..cb5fb41 100644
--- a/frontend/src/components/PaymentDetailModal.tsx
+++ b/frontend/src/components/PaymentDetailModal.tsx
@@ -1,639 +1,631 @@
-"use client";
-
-import { useCallback, useEffect, useRef, useState } from "react";
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useWallet } from "@/lib/wallet-context";
 import { usePayment } from "@/lib/usePayment";
+import { usePaymentStatusSocket } from "@/lib/usePaymentSocket";
 import WalletSelector from "@/components/WalletSelector";
 import CopyButton from "@/components/CopyButton";
 import toast from "react-hot-toast";
 import { QRCodeSVG } from "qrcode.react";
-
-const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
-const NETWORK = process.env.NEXT_PUBLIC_STELLAR_NETWORK ?? "testnet";
-const EXPLORER_BASE =
-  NETWORK === "public"
-    ? "https://stellar.expert/explorer/public"
-    : "https://stellar.expert/explorer/testnet";
-
-/* ------------------------------------------------------------------ */
-/*  Types                                                              */
-/* ------------------------------------------------------------------ */
-
-interface PaymentDetails {
-  id: string;
-  amount: number;
-  asset: string;
-  asset_issuer: string | null;
-  recipient: string;
-  description: string | null;
-  memo: string | null;
-  memo_type: string | null;
-  status: string;
-  tx_id: string | null;
-  metadata: Record<string, unknown> | null;
-  created_at: string;
-}
-
-interface PaymentDetailModalProps {
-  paymentId: string;
-  isOpen: boolean;
-  onClose: () => void;
-}
-
-function AssetBadge({ asset }: { asset: string }) {
-  const a = asset.toUpperCase();
-  if (a === "XLM" || a === "NATIVE") {
-    return (
-      <span
-        aria-hidden="true"
-        className="inline-flex h-8 w-8 items-center justify-center rounded-full bg-gradient-to-br from-white/15 via-mint/20 to-mint/40 text-mint shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
-      >
-        <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor" strokeWidth={1.8}>
-          <path d="M14.5 3.5 9 9l4.5.5L13 14l5.5-5.5" strokeLinecap="round" strokeLinejoin="round" />
-          <path d="M6 18c3.5-1 6-3.5 7-7" strokeLinecap="round" />
-          <path d="M7.5 16.5 4.5 19.5" strokeLinecap="round" />
-        </svg>
-      </span>
-    );
-  }
-  if (a === "USDC") {
-    return (
-      <span
-        aria-hidden="true"
-        className="inline-flex h-8 w-8 items-center justify-center rounded-full bg-[#2775CA] text-[8px] font-bold tracking-[0.18em] text-white shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
-      >
-        USDC
-      </span>
-    );
-  }
-  return (
-    <span className="inline-flex h-8 w-8 items-center justify-center rounded-full border border-white/20 bg-white/10 text-xs font-bold text-white">
-      {asset.slice(0, 3)}
-    </span>
-  );
-}
-
-const STATUS_MAP: Record<string, { label: string; classes: string }> = {
-  pending:   { label: "Awaiting Payment",  classes: "bg-yellow-500/15 text-yellow-400 border border-yellow-500/30" },
-  confirmed: { label: "Confirmed",         classes: "bg-mint/10 text-mint border border-mint/30" },
-  completed: { label: "Completed",         classes: "bg-green-500/15 text-green-400 border border-green-500/30" },
-  failed:    { label: "Failed",            classes: "bg-red-500/15 text-red-400 border border-red-500/30" },
-};
-
-function StatusBadge({ status }: { status: string }) {
-  const s = STATUS_MAP[status.toLowerCase()] ?? {
-    label: status,
-    classes: "bg-white/10 text-slate-400 border border-white/10",
-  };
-  return (
-    <span className={`rounded-full px-2.5 py-1 text-xs font-semibold ${s.classes}`}>
-      {s.label}
-    </span>
-  );
-}
-
-/** A labelled detail row used in the attributes grid */
-function DetailRow({
-  label,
-  children,
-}: {
-  label: string;
-  children: React.ReactNode;
-}) {
-  return (
-    <div className="flex flex-col gap-1">
-      <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
-        {label}
-      </p>
-      {children}
-    </div>
-  );
-}
-
-/** Recursively render a JSON metadata tree */
-function MetadataValue({ value }: { value: unknown }) {
-  if (value === null || value === undefined) {
-    return <span className="text-slate-600">null</span>;
-  }
-
-  if (typeof value === "boolean") {
-    return (
-      <span className={value ? "text-green-400" : "text-red-400"}>
-        {String(value)}
-      </span>
-    );
-  }
-
-  if (typeof value === "number") {
-    return <span className="text-amber-300">{value}</span>;
-  }
-
-  if (typeof value === "string") {
-    return <span className="text-sky-300 break-all">{value}</span>;
-  }
-
-  if (Array.isArray(value)) {
-    if (value.length === 0) return <span className="text-slate-500">[]</span>;
-    return (
-      <div className="flex flex-col gap-1 pl-3 border-l border-white/10">
-        {value.map((item, i) => (
-          <div key={i} className="flex items-start gap-2">
-            <span className="text-slate-600 text-xs mt-0.5">{i}</span>
-            <MetadataValue value={item} />
-          </div>
-        ))}
-      </div>
-    );
-  }
-
-  if (typeof value === "object") {
-    const entries = Object.entries(value as Record<string, unknown>);
-    if (entries.length === 0) return <span className="text-slate-500">{"{}"}</span>;
-    return (
-      <div className="flex flex-col gap-2 pl-3 border-l border-white/10">
-        {entries.map(([key, val]) => (
-          <div key={key} className="flex flex-col gap-0.5">
-            <span className="font-mono text-xs text-slate-400">{key}</span>
-            <MetadataValue value={val} />
-          </div>
-        ))}
-      </div>
-    );
-  }
-
-  return <span className="text-slate-400">{String(value)}</span>;
-}
-
-export default function PaymentDetailModal({
-  paymentId,
-  isOpen,
-  onClose,
-}: PaymentDetailModalProps) {
-  const [payment, setPayment] = useState<PaymentDetails | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [actionError, setActionError] = useState<string | null>(null);
-  const [metadataExpanded, setMetadataExpanded] = useState(false);
-
-  const [mounted, setMounted] = useState(false);
-  const [visible, setVisible] = useState(false);
-
-  const sheetRef = useRef<HTMLDivElement>(null);
-  const { activeProvider } = useWallet();
-  const walletReady = !!activeProvider;
-
-  const { isProcessing, error: paymentError, processPayment } = usePayment(activeProvider);
-
-  useEffect(() => {
-    if (isOpen) {
-      setMounted(true);
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => setVisible(true));
-      });
-    } else {
-      setVisible(false);
-      const timer = setTimeout(() => setMounted(false), 300);
-      return () => clearTimeout(timer);
-    }
-  }, [isOpen]);
-
-  /* ---------- body scroll lock ---------- */
-
-  useEffect(() => {
-    if (!isOpen) return;
-    const original = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    return () => {
-      document.body.style.overflow = original;
-    };
-  }, [isOpen]);
-
-  /* ---------- fetch payment details ---------- */
-
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+const NETWORK = process.env.NEXT_PUBLIC_STELLAR_NETWORK ?? "testnet";
+const EXPLORER_BASE =
+  NETWORK === "public"
+    ? "https://stellar.expert/explorer/public"
+    : "https://stellar.expert/explorer/testnet";
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+interface PaymentDetails {
+  id: string;
+  amount: number;
+  asset: string;
+  asset_issuer: string | null;
+  recipient: string;
+  description: string | null;
+  memo: string | null;
+  memo_type: string | null;
+  status: string;
+  tx_id: string | null;
+  metadata: Record<string, unknown> | null;
+  created_at: string;
+}
+
+interface PaymentDetailModalProps {
+  paymentId: string;
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+function AssetBadge({ asset }: { asset: string }) {
+  const a = asset.toUpperCase();
+  if (a === "XLM" || a === "NATIVE") {
+    return (
+      <span
+        aria-hidden="true"
+        className="inline-flex h-8 w-8 items-center justify-center rounded-full bg-gradient-to-br from-white/15 via-mint/20 to-mint/40 text-mint shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
+      >
+        <svg viewBox="0 0 24 24" className="h-4 w-4" fill="none" stroke="currentColor" strokeWidth={1.8}>
+          <path d="M14.5 3.5 9 9l4.5.5L13 14l5.5-5.5" strokeLinecap="round" strokeLinejoin="round" />
+          <path d="M6 18c3.5-1 6-3.5 7-7" strokeLinecap="round" />
+          <path d="M7.5 16.5 4.5 19.5" strokeLinecap="round" />
+        </svg>
+      </span>
+    );
+  }
+  if (a === "USDC") {
+    return (
+      <span
+        aria-hidden="true"
+        className="inline-flex h-8 w-8 items-center justify-center rounded-full bg-[#2775CA] text-[8px] font-bold tracking-[0.18em] text-white shadow-[0_0_0_1px_rgba(255,255,255,0.08)]"
+      >
+        USDC
+      </span>
+    );
+  }
+  return (
+    <span className="inline-flex h-8 w-8 items-center justify-center rounded-full border border-white/20 bg-white/10 text-xs font-bold text-white">
+      {asset.slice(0, 3)}
+    </span>
+  );
+}
+
+const STATUS_MAP: Record<string, { label: string; classes: string }> = {
+  pending:   { label: "Awaiting Payment",  classes: "bg-yellow-500/15 text-yellow-400 border border-yellow-500/30" },
+  confirmed: { label: "Confirmed",         classes: "bg-mint/10 text-mint border border-mint/30" },
+  completed: { label: "Completed",         classes: "bg-green-500/15 text-green-400 border border-green-500/30" },
+  failed:    { label: "Failed",            classes: "bg-red-500/15 text-red-400 border border-red-500/30" },
+};
+
+function StatusBadge({ status }: { status: string }) {
+  const s = STATUS_MAP[status.toLowerCase()] ?? {
+    label: status,
+    classes: "bg-white/10 text-slate-400 border border-white/10",
+  };
+  return (
+    <span className={`rounded-full px-2.5 py-1 text-xs font-semibold ${s.classes}`}>
+      {s.label}
+    </span>
+  );
+}
+
+/** A labelled detail row used in the attributes grid */
+function DetailRow({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="flex flex-col gap-1">
+      <p className="text-xs font-medium uppercase tracking-wider text-slate-500">
+        {label}
+      </p>
+      {children}
+    </div>
+  );
+}
+
+/** Recursively render a JSON metadata tree */
+function MetadataValue({ value }: { value: unknown }) {
+  if (value === null || value === undefined) {
+    return <span className="text-slate-600">null</span>;
+  }
+
+  if (typeof value === "boolean") {
+    return (
+      <span className={value ? "text-green-400" : "text-red-400"}>
+        {String(value)}
+      </span>
+    );
+  }
+
+  if (typeof value === "number") {
+    return <span className="text-amber-300">{value}</span>;
+  }
+
+  if (typeof value === "string") {
+    return <span className="text-sky-300 break-all">{value}</span>;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return <span className="text-slate-500">[]</span>;
+    return (
+      <div className="flex flex-col gap-1 pl-3 border-l border-white/10">
+        {value.map((item, i) => (
+          <div key={i} className="flex items-start gap-2">
+            <span className="text-slate-600 text-xs mt-0.5">{i}</span>
+            <MetadataValue value={item} />
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) return <span className="text-slate-500">{"{}"}</span>;
+    return (
+      <div className="flex flex-col gap-2 pl-3 border-l border-white/10">
+        {entries.map(([key, val]) => (
+          <div key={key} className="flex flex-col gap-0.5">
+            <span className="font-mono text-xs text-slate-400">{key}</span>
+            <MetadataValue value={val} />
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  return <span className="text-slate-400">{String(value)}</span>;
+}
+
+export default function PaymentDetailModal({
+  paymentId,
+  isOpen,
+  onClose,
+}: PaymentDetailModalProps) {
+  const [payment, setPayment] = useState<PaymentDetails | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [metadataExpanded, setMetadataExpanded] = useState(false);
+
+  const [mounted, setMounted] = useState(false);
+  const [visible, setVisible] = useState(false);
+
+  const sheetRef = useRef<HTMLDivElement>(null);
+  const { activeProvider } = useWallet();
+  const walletReady = !!activeProvider;
+
+  const { isProcessing, error: paymentError, processPayment } = usePayment(activeProvider);
+
+  useEffect(() => {
+    if (isOpen) {
+      setMounted(true);
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => setVisible(true));
+      });
+    } else {
+      setVisible(false);
+      const timer = setTimeout(() => setMounted(false), 300);
+      return () => clearTimeout(timer);
+    }
+  }, [isOpen]);
+
+  /* ---------- body scroll lock ---------- */
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const original = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = original;
+    };
+  }, [isOpen]);
+
+  /* ---------- fetch payment details ---------- */
+
   useEffect(() => {
     if (!isOpen || !paymentId) return;
-
-    const controller = new AbortController();
-    setLoading(true);
-    setError(null);
-    setMetadataExpanded(false);
-
-    const load = async () => {
-      try {
-        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`, {
-          signal: controller.signal,
-        });
-        if (res.status === 404) throw new Error("Payment not found.");
-        if (!res.ok) throw new Error("Could not load payment details.");
-        const data = await res.json();
-        setPayment(data.payment);
-      } catch (err: unknown) {
-        if (err instanceof Error && err.name === "AbortError") return;
-        setError(err instanceof Error ? err.message : "Failed to load payment.");
-      } finally {
-        setLoading(false);
-      }
-    };
-
+
+    const controller = new AbortController();
+    setLoading(true);
+    setError(null);
+    setMetadataExpanded(false);
+
+    const load = async () => {
+      try {
+        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`, {
+          signal: controller.signal,
+        });
+        if (res.status === 404) throw new Error("Payment not found.");
+        if (!res.ok) throw new Error("Could not load payment details.");
+        const data = await res.json();
+        setPayment(data.payment);
+      } catch (err: unknown) {
+        if (err instanceof Error && err.name === "AbortError") return;
+        setError(err instanceof Error ? err.message : "Failed to load payment.");
+      } finally {
+        setLoading(false);
+      }
+    };
+
     load();
     return () => controller.abort();
   }, [paymentId, isOpen]);
 
-  /* ---------- poll until settled ---------- */
-
-  useEffect(() => {
-    if (!isOpen || loading || !payment) return;
-    const settled = ["confirmed", "completed", "failed"].includes(
-      payment.status,
-    );
-    if (settled) return;
-
-    const id = setInterval(async () => {
-      try {
-        const res = await fetch(`${API_URL}/api/payment-status/${paymentId}`);
-        if (!res.ok) return;
-        const data = await res.json();
-        if (data.payment) setPayment(data.payment);
-      } catch {
-        /* silent — retry next tick */
+  usePaymentStatusSocket(isOpen ? paymentId : null, (event) => {
+    setPayment((current) => {
+      if (!current || current.id !== event.id) {
+        return current;
       }
-    }, 5000);
-
-    return () => clearInterval(id);
-  }, [paymentId, payment, loading, isOpen]);
-
-  const networkPassphrase =
-    process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE ?? "Test SDF Network ; September 2015";
-
-  /* ---------- keyboard & focus ---------- */
-
-  const stableOnClose = useCallback(() => onClose(), [onClose]);
-
-  useEffect(() => {
-    if (!isOpen) return;
-
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "Escape") stableOnClose();
-    };
-
-    document.addEventListener("keydown", handleKeyDown);
-    // Move focus into the sheet
-    sheetRef.current?.focus();
-
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [isOpen, stableOnClose]);
-
-  /* ---------- pay handler ---------- */
-
-  const handlePay = async () => {
-    if (!payment) return;
-    setActionError(null);
-
-    try {
-      const result = await processPayment({
-        recipient: payment.recipient,
-        amount: String(payment.amount),
-        assetCode: payment.asset,
-        assetIssuer: payment.asset_issuer,
-      });
-
-      setPayment({ ...payment, status: "completed", tx_id: result.hash });
-      toast.success("Payment sent!");
-
-      // Best-effort backend verification
-      setTimeout(async () => {
-        try {
-          await fetch(`${API_URL}/api/verify-payment/${paymentId}`, {
-            method: "POST",
-          });
-        } catch {
-          /* non-critical */
-        }
-      }, 2000);
-    } catch {
-      const msg = paymentError ?? "Payment failed. Please try again.";
-      setActionError(msg);
-      toast.error(msg);
-    }
-  };
-
-  /* ---------- derived state ---------- */
-
-  const isSettled =
-    payment?.status === "confirmed" || payment?.status === "completed";
-  const isFailed = payment?.status === "failed";
-
-  // Filter out internal/branding keys from metadata for display
-  const displayMetadata = payment?.metadata
-    ? Object.fromEntries(
-        Object.entries(payment.metadata).filter(
-          ([key]) => key !== "branding_config",
-        ),
-      )
-    : null;
-  const hasMetadata =
-    displayMetadata !== null && Object.keys(displayMetadata).length > 0;
-
-  /* ---------- render nothing until first open ---------- */
-
-  if (!mounted) return null;
-
-  return (
-    <>
-      {/* Backdrop */}
-      <div
-        className={`fixed inset-0 z-40 bg-black/60 backdrop-blur-sm transition-opacity duration-300 ${
-          visible ? "opacity-100" : "opacity-0"
-        }`}
-        onClick={stableOnClose}
-        aria-hidden="true"
-      />
-
-      {/* Right sliding sheet */}
-      <div
-        ref={sheetRef}
-        role="dialog"
-        aria-modal="true"
-        aria-label="Payment details"
-        tabIndex={-1}
-        className={`fixed right-0 top-0 z-50 flex h-full w-full max-w-lg flex-col bg-slate-900 shadow-2xl outline-none transition-transform duration-300 ease-in-out ${
-          visible ? "translate-x-0" : "translate-x-full"
-        }`}
-      >
-        {/* Header */}
-        <div className="flex flex-shrink-0 items-center justify-between border-b border-white/10 p-6">
-          <div>
-            <p className="font-mono text-xs uppercase tracking-[0.3em] text-mint">
-              Payment Details
-            </p>
-            <p className="mt-1 font-mono text-xs text-slate-500">
-              ID: {paymentId}
-            </p>
-          </div>
-          <button
-            onClick={stableOnClose}
-            aria-label="Close payment details"
-            className="rounded-lg p-2 text-slate-400 transition-colors hover:bg-white/10 hover:text-white"
-          >
-            <svg
-              className="h-5 w-5"
-              fill="none"
-              stroke="currentColor"
-              viewBox="0 0 24 24"
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeWidth={2}
-                d="M6 18L18 6M6 6l12 12"
-              />
-            </svg>
-          </button>
-        </div>
-
-        {/* Scrollable content */}
-        <div className="flex-1 overflow-y-auto">
-          {loading ? (
-            <div className="p-6 space-y-4">
-              <div className="animate-pulse space-y-3">
-                <div className="h-8 w-32 rounded-lg bg-white/10" />
-                <div className="h-12 w-48 rounded-lg bg-white/10" />
-                <div className="h-6 w-64 rounded-lg bg-white/10" />
-                <div className="h-20 w-full rounded-lg bg-white/10" />
-                <div className="h-20 w-full rounded-lg bg-white/10" />
-              </div>
-            </div>
-          ) : error || !payment ? (
-            <div className="p-6">
-              <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-6 text-center">
-                <p className="text-sm font-medium uppercase tracking-wider text-red-400">
-                  Error
-                </p>
-                <p className="mt-3 text-lg font-semibold text-white">
-                  {error ?? "Payment not found"}
-                </p>
-              </div>
-            </div>
-          ) : (
-            <div className="p-6 space-y-6">
-              {/* ── Amount hero ── */}
-              <div className="flex flex-col items-center gap-3 text-center">
-                <AssetBadge asset={payment.asset} />
-                <div className="flex items-baseline gap-2">
-                  <span className="text-4xl font-bold tracking-tight text-white">
-                    {payment.amount.toLocaleString(undefined, {
-                      minimumFractionDigits: 0,
-                      maximumFractionDigits: 7,
-                    })}
-                  </span>
-                  <span className="text-xl font-semibold text-slate-400">
-                    {payment.asset.toUpperCase()}
-                  </span>
-                </div>
-                {payment.description && (
-                  <p className="text-sm text-slate-400">
-                    {payment.description}
-                  </p>
-                )}
-                <StatusBadge status={payment.status} />
-              </div>
-
-              {/* ── Core attributes ── */}
-              <div className="space-y-4">
-                {/* Recipient */}
-                <DetailRow label="Recipient">
-                  <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                    <code className="flex-1 truncate font-mono text-sm text-slate-200">
-                      {payment.recipient}
-                    </code>
-                    <CopyButton text={payment.recipient} />
-                  </div>
-                </DetailRow>
-
-                {/* Asset issuer (non-native) */}
-                {payment.asset_issuer && (
-                  <DetailRow label="Asset Issuer">
-                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                      <code className="flex-1 truncate font-mono text-sm text-slate-200">
-                        {payment.asset_issuer}
-                      </code>
-                      <CopyButton text={payment.asset_issuer} />
-                    </div>
-                  </DetailRow>
-                )}
-
-                {/* Memo */}
-                {payment.memo && (
-                  <DetailRow label={`Memo${payment.memo_type ? ` (${payment.memo_type})` : ""}`}>
-                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                      <code className="flex-1 break-all font-mono text-sm text-slate-200">
-                        {payment.memo}
-                      </code>
-                      <CopyButton text={payment.memo} />
-                    </div>
-                  </DetailRow>
-                )}
-
-                {/* QR Code — only for unsettled payments */}
-                {!isSettled && !isFailed && (
-                  <DetailRow label="Scan to Pay">
-                    <div className="flex items-center justify-center rounded-xl border border-white/10 bg-white p-4">
-                      <QRCodeSVG
-                        value={payment.recipient}
-                        size={140}
-                        level="M"
-                        bgColor="#ffffff"
-                        fgColor="#000000"
-                      />
-                    </div>
-                    <p className="text-center text-xs text-slate-500">
-                      Scan with Freighter or any Stellar wallet
-                    </p>
-                  </DetailRow>
-                )}
-
-                {/* Date */}
-                <DetailRow label="Created">
-                  <p className="text-sm text-slate-300">
-                    {new Date(payment.created_at).toLocaleString(undefined, {
-                      dateStyle: "medium",
-                      timeStyle: "short",
-                    })}
-                  </p>
-                </DetailRow>
-
-                {/* Transaction hash */}
-                {payment.tx_id && (
-                  <DetailRow label="Transaction">
-                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                      <a
-                        href={`${EXPLORER_BASE}/tx/${payment.tx_id}`}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        className="flex-1 truncate font-mono text-sm text-mint underline underline-offset-2 hover:text-glow"
-                      >
-                        {payment.tx_id}
-                      </a>
-                      <CopyButton text={payment.tx_id} />
-                    </div>
-                  </DetailRow>
-                )}
-
-                {/* Payment ID (copiable) */}
-                <DetailRow label="Payment ID">
-                  <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
-                    <code className="flex-1 truncate font-mono text-sm text-slate-200">
-                      {payment.id}
-                    </code>
-                    <CopyButton text={payment.id} />
-                  </div>
-                </DetailRow>
-              </div>
-
-              {/* ── Metadata section ── */}
-              {hasMetadata && (
-                <div className="space-y-2">
-                  <button
-                    type="button"
-                    onClick={() => setMetadataExpanded((v) => !v)}
-                    className="flex w-full items-center justify-between rounded-xl border border-white/10 bg-white/5 px-4 py-3 text-left transition-colors hover:bg-white/10"
-                  >
-                    <span className="text-xs font-medium uppercase tracking-wider text-slate-400">
-                      Metadata
-                    </span>
-                    <svg
-                      className={`h-4 w-4 text-slate-500 transition-transform duration-200 ${
-                        metadataExpanded ? "rotate-180" : ""
-                      }`}
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M19 9l-7 7-7-7"
-                      />
-                    </svg>
-                  </button>
-
-                  {metadataExpanded && (
-                    <div className="rounded-xl border border-white/10 bg-black/30 p-4 font-mono text-sm">
-                      <MetadataValue value={displayMetadata} />
-                    </div>
-                  )}
-                </div>
-              )}
-
-              {/* ── Action error ── */}
-              {actionError && (
-                <div
-                  role="alert"
-                  className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-400"
-                >
-                  {actionError}
-                </div>
-              )}
-
-                {/* CTA section */}
-                {!isSettled && !isFailed && (
-                  <div className="flex flex-col gap-3 pt-2">
-                    {walletReady ? (
-                      <button
-                        type="button"
-                        onClick={handlePay}
-                        disabled={isProcessing}
-                        className="group relative flex h-12 w-full items-center justify-center rounded-xl bg-mint font-bold text-black transition-all hover:bg-glow disabled:cursor-not-allowed disabled:opacity-50"
-                      >
-                        {isProcessing ? (
-                          <span className="flex items-center gap-2">
-                            <svg className="h-4 w-4 animate-spin" viewBox="0 0 24 24">
-                              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
-                              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
-                            </svg>
-                            Processing…
-                          </span>
-                        ) : (
-                          `Pay with ${activeProvider!.name}`
-                        )}
-                        <div className="absolute inset-0 -z-10 bg-mint/20 opacity-0 blur-xl transition-opacity group-hover:opacity-100" />
-                      </button>
-                    ) : (
-                      <WalletSelector
-                        networkPassphrase={networkPassphrase}
-                        onConnected={() => {}}
-                      />
-                    )}
-                  </div>
-                )}
-
-              {/* ── Status messages ── */}
-              {isSettled && (
-                <div className="rounded-xl border border-mint/30 bg-mint/5 p-4 text-center">
-                  <p className="text-sm font-semibold text-mint">
-                    This payment has been received.
-                  </p>
-                  <p className="mt-1 text-xs text-slate-400">
-                    The transaction was confirmed on the Stellar network.
-                  </p>
-                </div>
-              )}
 
-              {isFailed && (
-                <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-center">
-                  <p className="text-sm font-semibold text-red-400">
-                    This payment has failed.
-                  </p>
-                  <p className="mt-1 text-xs text-slate-500">
-                    Contact the merchant if you believe this is an error.
-                  </p>
-                </div>
-              )}
-            </div>
-          )}
-        </div>
-      </div>
-    </>
-  );
-}
+      return {
+        ...current,
+        status: event.status,
+        tx_id: event.tx_id,
+      };
+    });
+  });
+
+  const networkPassphrase =
+    process.env.NEXT_PUBLIC_NETWORK_PASSPHRASE ?? "Test SDF Network ; September 2015";
+
+  /* ---------- keyboard & focus ---------- */
+
+  const stableOnClose = useCallback(() => onClose(), [onClose]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") stableOnClose();
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    // Move focus into the sheet
+    sheetRef.current?.focus();
+
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [isOpen, stableOnClose]);
+
+  /* ---------- pay handler ---------- */
+
+  const handlePay = async () => {
+    if (!payment) return;
+    setActionError(null);
+
+    try {
+      const result = await processPayment({
+        recipient: payment.recipient,
+        amount: String(payment.amount),
+        assetCode: payment.asset,
+        assetIssuer: payment.asset_issuer,
+      });
+
+      setPayment({ ...payment, status: "completed", tx_id: result.hash });
+      toast.success("Payment sent!");
+
+      // Best-effort backend verification
+      setTimeout(async () => {
+        try {
+          await fetch(`${API_URL}/api/verify-payment/${paymentId}`, {
+            method: "POST",
+          });
+        } catch {
+          /* non-critical */
+        }
+      }, 2000);
+    } catch {
+      const msg = paymentError ?? "Payment failed. Please try again.";
+      setActionError(msg);
+      toast.error(msg);
+    }
+  };
+
+  /* ---------- derived state ---------- */
+
+  const isSettled =
+    payment?.status === "confirmed" || payment?.status === "completed";
+  const isFailed = payment?.status === "failed";
+
+  // Filter out internal/branding keys from metadata for display
+  const displayMetadata = payment?.metadata
+    ? Object.fromEntries(
+        Object.entries(payment.metadata).filter(
+          ([key]) => key !== "branding_config",
+        ),
+      )
+    : null;
+  const hasMetadata =
+    displayMetadata !== null && Object.keys(displayMetadata).length > 0;
+
+  /* ---------- render nothing until first open ---------- */
+
+  if (!mounted) return null;
+
+  return (
+    <>
+      {/* Backdrop */}
+      <div
+        className={`fixed inset-0 z-40 bg-black/60 backdrop-blur-sm transition-opacity duration-300 ${
+          visible ? "opacity-100" : "opacity-0"
+        }`}
+        onClick={stableOnClose}
+        aria-hidden="true"
+      />
+
+      {/* Right sliding sheet */}
+      <div
+        ref={sheetRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label="Payment details"
+        tabIndex={-1}
+        className={`fixed right-0 top-0 z-50 flex h-full w-full max-w-lg flex-col bg-slate-900 shadow-2xl outline-none transition-transform duration-300 ease-in-out ${
+          visible ? "translate-x-0" : "translate-x-full"
+        }`}
+      >
+        {/* Header */}
+        <div className="flex flex-shrink-0 items-center justify-between border-b border-white/10 p-6">
+          <div>
+            <p className="font-mono text-xs uppercase tracking-[0.3em] text-mint">
+              Payment Details
+            </p>
+            <p className="mt-1 font-mono text-xs text-slate-500">
+              ID: {paymentId}
+            </p>
+          </div>
+          <button
+            onClick={stableOnClose}
+            aria-label="Close payment details"
+            className="rounded-lg p-2 text-slate-400 transition-colors hover:bg-white/10 hover:text-white"
+          >
+            <svg
+              className="h-5 w-5"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </button>
+        </div>
+
+        {/* Scrollable content */}
+        <div className="flex-1 overflow-y-auto">
+          {loading ? (
+            <div className="p-6 space-y-4">
+              <div className="animate-pulse space-y-3">
+                <div className="h-8 w-32 rounded-lg bg-white/10" />
+                <div className="h-12 w-48 rounded-lg bg-white/10" />
+                <div className="h-6 w-64 rounded-lg bg-white/10" />
+                <div className="h-20 w-full rounded-lg bg-white/10" />
+                <div className="h-20 w-full rounded-lg bg-white/10" />
+              </div>
+            </div>
+          ) : error || !payment ? (
+            <div className="p-6">
+              <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-6 text-center">
+                <p className="text-sm font-medium uppercase tracking-wider text-red-400">
+                  Error
+                </p>
+                <p className="mt-3 text-lg font-semibold text-white">
+                  {error ?? "Payment not found"}
+                </p>
+              </div>
+            </div>
+          ) : (
+            <div className="p-6 space-y-6">
+              {/* ── Amount hero ── */}
+              <div className="flex flex-col items-center gap-3 text-center">
+                <AssetBadge asset={payment.asset} />
+                <div className="flex items-baseline gap-2">
+                  <span className="text-4xl font-bold tracking-tight text-white">
+                    {payment.amount.toLocaleString(undefined, {
+                      minimumFractionDigits: 0,
+                      maximumFractionDigits: 7,
+                    })}
+                  </span>
+                  <span className="text-xl font-semibold text-slate-400">
+                    {payment.asset.toUpperCase()}
+                  </span>
+                </div>
+                {payment.description && (
+                  <p className="text-sm text-slate-400">
+                    {payment.description}
+                  </p>
+                )}
+                <StatusBadge status={payment.status} />
+              </div>
+
+              {/* ── Core attributes ── */}
+              <div className="space-y-4">
+                {/* Recipient */}
+                <DetailRow label="Recipient">
+                  <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                    <code className="flex-1 truncate font-mono text-sm text-slate-200">
+                      {payment.recipient}
+                    </code>
+                    <CopyButton text={payment.recipient} />
+                  </div>
+                </DetailRow>
+
+                {/* Asset issuer (non-native) */}
+                {payment.asset_issuer && (
+                  <DetailRow label="Asset Issuer">
+                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                      <code className="flex-1 truncate font-mono text-sm text-slate-200">
+                        {payment.asset_issuer}
+                      </code>
+                      <CopyButton text={payment.asset_issuer} />
+                    </div>
+                  </DetailRow>
+                )}
+
+                {/* Memo */}
+                {payment.memo && (
+                  <DetailRow label={`Memo${payment.memo_type ? ` (${payment.memo_type})` : ""}`}>
+                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                      <code className="flex-1 break-all font-mono text-sm text-slate-200">
+                        {payment.memo}
+                      </code>
+                      <CopyButton text={payment.memo} />
+                    </div>
+                  </DetailRow>
+                )}
+
+                {/* QR Code — only for unsettled payments */}
+                {!isSettled && !isFailed && (
+                  <DetailRow label="Scan to Pay">
+                    <div className="flex items-center justify-center rounded-xl border border-white/10 bg-white p-4">
+                      <QRCodeSVG
+                        value={payment.recipient}
+                        size={140}
+                        level="M"
+                        bgColor="#ffffff"
+                        fgColor="#000000"
+                      />
+                    </div>
+                    <p className="text-center text-xs text-slate-500">
+                      Scan with Freighter or any Stellar wallet
+                    </p>
+                  </DetailRow>
+                )}
+
+                {/* Date */}
+                <DetailRow label="Created">
+                  <p className="text-sm text-slate-300">
+                    {new Date(payment.created_at).toLocaleString(undefined, {
+                      dateStyle: "medium",
+                      timeStyle: "short",
+                    })}
+                  </p>
+                </DetailRow>
+
+                {/* Transaction hash */}
+                {payment.tx_id && (
+                  <DetailRow label="Transaction">
+                    <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                      <a
+                        href={`${EXPLORER_BASE}/tx/${payment.tx_id}`}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="flex-1 truncate font-mono text-sm text-mint underline underline-offset-2 hover:text-glow"
+                      >
+                        {payment.tx_id}
+                      </a>
+                      <CopyButton text={payment.tx_id} />
+                    </div>
+                  </DetailRow>
+                )}
+
+                {/* Payment ID (copiable) */}
+                <DetailRow label="Payment ID">
+                  <div className="flex items-center gap-2 rounded-xl border border-white/10 bg-black/30 p-3">
+                    <code className="flex-1 truncate font-mono text-sm text-slate-200">
+                      {payment.id}
+                    </code>
+                    <CopyButton text={payment.id} />
+                  </div>
+                </DetailRow>
+              </div>
+
+              {/* ── Metadata section ── */}
+              {hasMetadata && (
+                <div className="space-y-2">
+                  <button
+                    type="button"
+                    onClick={() => setMetadataExpanded((v) => !v)}
+                    className="flex w-full items-center justify-between rounded-xl border border-white/10 bg-white/5 px-4 py-3 text-left transition-colors hover:bg-white/10"
+                  >
+                    <span className="text-xs font-medium uppercase tracking-wider text-slate-400">
+                      Metadata
+                    </span>
+                    <svg
+                      className={`h-4 w-4 text-slate-500 transition-transform duration-200 ${
+                        metadataExpanded ? "rotate-180" : ""
+                      }`}
+                      fill="none"
+                      stroke="currentColor"
+                      viewBox="0 0 24 24"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M19 9l-7 7-7-7"
+                      />
+                    </svg>
+                  </button>
+
+                  {metadataExpanded && (
+                    <div className="rounded-xl border border-white/10 bg-black/30 p-4 font-mono text-sm">
+                      <MetadataValue value={displayMetadata} />
+                    </div>
+                  )}
+                </div>
+              )}
+
+              {/* ── Action error ── */}
+              {actionError && (
+                <div
+                  role="alert"
+                  className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-sm text-red-400"
+                >
+                  {actionError}
+                </div>
+              )}
+
+                {/* CTA section */}
+                {!isSettled && !isFailed && (
+                  <div className="flex flex-col gap-3 pt-2">
+                    {walletReady ? (
+                      <button
+                        type="button"
+                        onClick={handlePay}
+                        disabled={isProcessing}
+                        className="group relative flex h-12 w-full items-center justify-center rounded-xl bg-mint font-bold text-black transition-all hover:bg-glow disabled:cursor-not-allowed disabled:opacity-50"
+                      >
+                        {isProcessing ? (
+                          <span className="flex items-center gap-2">
+                            <svg className="h-4 w-4 animate-spin" viewBox="0 0 24 24">
+                              <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
+                              <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" />
+                            </svg>
+                            Processing…
+                          </span>
+                        ) : (
+                          `Pay with ${activeProvider!.name}`
+                        )}
+                        <div className="absolute inset-0 -z-10 bg-mint/20 opacity-0 blur-xl transition-opacity group-hover:opacity-100" />
+                      </button>
+                    ) : (
+                      <WalletSelector
+                        networkPassphrase={networkPassphrase}
+                        onConnected={() => {}}
+                      />
+                    )}
+                  </div>
+                )}
+
+              {/* ── Status messages ── */}
+              {isSettled && (
+                <div className="rounded-xl border border-mint/30 bg-mint/5 p-4 text-center">
+                  <p className="text-sm font-semibold text-mint">
+                    This payment has been received.
+                  </p>
+                  <p className="mt-1 text-xs text-slate-400">
+                    The transaction was confirmed on the Stellar network.
+                  </p>
+                </div>
+              )}
+
+              {isFailed && (
+                <div className="rounded-xl border border-red-500/30 bg-red-500/10 p-4 text-center">
+                  <p className="text-sm font-semibold text-red-400">
+                    This payment has failed.
+                  </p>
+                  <p className="mt-1 text-xs text-slate-500">
+                    Contact the merchant if you believe this is an error.
+                  </p>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </div>
+    </>
+  );
+}
diff --git a/frontend/src/lib/usePaymentSocket.ts b/frontend/src/lib/usePaymentSocket.ts
index 7627194..d44ffcd 100644
--- a/frontend/src/lib/usePaymentSocket.ts
+++ b/frontend/src/lib/usePaymentSocket.ts
@@ -1,61 +1,109 @@
 "use client";
 
-import { useEffect, useRef, useCallback } from "react";
+import { useEffect, useRef } from "react";
 import { io, Socket } from "socket.io-client";
 
-export interface ConfirmedPaymentEvent {
+export interface ConfirmedPaymentEvent {
+  id: string;
+  amount: number;
+  asset: string;
+  asset_issuer: string | null;
+  recipient: string;
+  tx_id: string;
+  confirmed_at: string;
+}
+
+type Handler = (payment: ConfirmedPaymentEvent) => void;
+type PaymentStatusHandler = (payment: PaymentStatusEvent) => void;
+
+export interface PaymentStatusEvent {
   id: string;
+  merchant_id: string | null;
   amount: number;
   asset: string;
   asset_issuer: string | null;
   recipient: string;
-  tx_id: string;
-  confirmed_at: string;
+  status: string;
+  tx_id: string | null;
+  updated_at: string;
 }
 
-type Handler = (payment: ConfirmedPaymentEvent) => void;
+function createSocketConnection() {
+  const apiUrl = process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000";
 
-/**
- * Connects to the backend Socket.io server and joins the merchant's private
- * room so the component receives `payment:confirmed` events in real time.
- *
- * @param merchantId  The authenticated merchant's UUID
- * @param onConfirmed Callback invoked for every confirmed payment event
- */
+  return io(apiUrl, {
+    transports: ["websocket"],
+    reconnectionAttempts: 5,
+    reconnectionDelay: 2000,
+  });
+}
+
+/**
+ * Connects to the backend Socket.io server and joins the merchant's private
+ * room so the component receives `payment:confirmed` events in real time.
+ *
+ * @param merchantId  The authenticated merchant's UUID
+ * @param onConfirmed Callback invoked for every confirmed payment event
+ */
 export function usePaymentSocket(
   merchantId: string | null | undefined,
   onConfirmed: Handler,
 ) {
-  const socketRef = useRef<Socket | null>(null);
-  // Keep a stable ref to the handler so the effect doesn't re-run on every render
-  const handlerRef = useRef<Handler>(onConfirmed);
-  handlerRef.current = onConfirmed;
-
+  const socketRef = useRef<Socket | null>(null);
+  // Keep a stable ref to the handler so the effect doesn't re-run on every render
+  const handlerRef = useRef<Handler>(onConfirmed);
+  handlerRef.current = onConfirmed;
+
   useEffect(() => {
     if (!merchantId) return;
 
-    const apiUrl = process.env.NEXT_PUBLIC_API_URL || "http://localhost:4000";
+    const socket = createSocketConnection();
+
+    socketRef.current = socket;
+
+    socket.on("connect", () => {
+      // Join the merchant's private room — the backend emits only to this room
+      socket.emit("join:merchant", { merchant_id: merchantId });
+    });
+
+    socket.on("payment:confirmed", (payload: ConfirmedPaymentEvent) => {
+      handlerRef.current(payload);
+    });
+
+    return () => {
+      socket.disconnect();
+      socketRef.current = null;
+    };
+  }, [merchantId]);
+}
 
-    const socket = io(apiUrl, {
-      transports: ["websocket"],
-      reconnectionAttempts: 5,
-      reconnectionDelay: 2000,
-    });
+export function usePaymentStatusSocket(
+  paymentId: string | null | undefined,
+  onStatus: PaymentStatusHandler,
+) {
+  const socketRef = useRef<Socket | null>(null);
+  const handlerRef = useRef<PaymentStatusHandler>(onStatus);
+  handlerRef.current = onStatus;
+
+  useEffect(() => {
+    if (!paymentId) return;
 
+    const socket = createSocketConnection();
     socketRef.current = socket;
 
     socket.on("connect", () => {
-      // Join the merchant's private room — the backend emits only to this room
-      socket.emit("join:merchant", { merchant_id: merchantId });
+      socket.emit("join:payment", { payment_id: paymentId });
     });
 
-    socket.on("payment:confirmed", (payload: ConfirmedPaymentEvent) => {
-      handlerRef.current(payload);
+    socket.on("payment:status", (payload: PaymentStatusEvent) => {
+      if (payload.id === paymentId) {
+        handlerRef.current(payload);
+      }
     });
 
     return () => {
       socket.disconnect();
       socketRef.current = null;
     };
-  }, [merchantId]);
+  }, [paymentId]);
 }