@kwespay/widget 1.0.8 → 1.0.9

package/dist/esm/index.js

@@ -5,10 +5,17 @@ const SUPPORTED_CURRENCIES = {
   GHS: "GHS",
 };
 
-const STABLECOIN_SYMBOLS = ["USDT", "USDC", "DAI", "BUSD", "USDc"];
+const STABLECOIN_SYMBOLS = [
+  "USDT",
+  "USDC",
+  "DAI",
+  "BUSD",
+  "USDc",
+  "MUSD",
+];
 
 const DEFAULT_CONFIG = {
-  graphqlEndpoint: "https://api.kwespay.xyz/",
+  graphqlEndpoint: "https://api.testnet.kwespay.xyz/graphql",
   currency: SUPPORTED_CURRENCIES.USD,
 };
 
@@ -49,11 +56,29 @@ const NETWORK_CONFIGS = {
     explorer: "https://blockscout.lisk.com/tx/",
     type: "mainnet",
   },
+  mezo: {
+    name: "Mezo",
+    chainId: 31612,
+    rpcUrl: "https://rpc.mezo.org",
+    contractAddress: "",
+    logo: "https://arthuremma2.github.io/img-hosting/mezo.png",
+    explorer: "https://explorer.mezo.org/tx/",
+    type: "mainnet",
+  },
+  arbitrum: {
+    name: "Arbitrum",
+    chainId: 42161,
+    rpcUrl: "https://arb1.arbitrum.io/rpc",
+    contractAddress: "",
+    logo: "https://arthuremma2.github.io/img-hosting/arb44.svg",
+    explorer: "https://arbiscan.io/tx/",
+    type: "mainnet",
+  },
   sepolia: {
     name: "Sepolia",
     chainId: 11155111,
     rpcUrl: "https://rpc.sepolia.org",
-    contractAddress: "0x39bE436D6A34d0990cb71c9cBD24a5361d85e00B",
+    contractAddress: "0xD9312df771aEf74a6748c0C46A706873C67F44C7",
     logo: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
     explorer: "https://sepolia.etherscan.io/tx/",
     type: "testnet",
@@ -62,7 +87,7 @@ const NETWORK_CONFIGS = {
     name: "Polygon Amoy",
     chainId: 80002,
     rpcUrl: "https://rpc-amoy.polygon.technology",
-    contractAddress: "0xD31dF3eBd220Fd3e190A346F8927819295d28980",
+    contractAddress: "0xEb40935599d5D8ef39C1aAE38E7A1f6d9c89B3fF",
     logo: "https://arthuremma2.github.io/img-hosting/Polygon_Icon.png",
     explorer: "https://amoy.polygonscan.com/tx/",
     type: "testnet",
@@ -71,7 +96,7 @@ const NETWORK_CONFIGS = {
     name: "Base Sepolia",
     chainId: 84532,
     rpcUrl: "https://sepolia.base.org",
-    contractAddress: "0x7515b1b1BcA33E7a9ccBd5E2b93771884654De77",
+    contractAddress: "0x3d7A6a7aD72374D2d3dca4e97053bAbFA6E49ec0",
     logo: "https://arthuremma2.github.io/img-hosting/base23.png",
     explorer: "https://sepolia.basescan.org/tx/",
     type: "testnet",
@@ -80,11 +105,29 @@ const NETWORK_CONFIGS = {
     name: "Lisk Sepolia",
     chainId: 4202,
     rpcUrl: "https://rpc.sepolia-api.lisk.com",
-    contractAddress: "0xd04A78a998146EBAD04c2b68E020C06Dc3b3717f",
+    contractAddress: "0x3378B6074A9DA47Aef8b7C849aFcaF58b8D8134b",
     logo: "https://arthuremma2.github.io/img-hosting/liskt.png",
     explorer: "https://sepolia-blockscout.lisk.com/tx/",
     type: "testnet",
   },
+  mezoTestnet: {
+    name: "Mezo Testnet",
+    chainId: 31611,
+    rpcUrl: "https://rpc.test.mezo.org",
+    contractAddress: "0x67f3Df6B5BE714303F397104d8F2A3861b9E8b6d",
+    logo: "https://arthuremma2.github.io/img-hosting/mezo.png",
+    explorer: "https://explorer.test.mezo.org/tx/",
+    type: "testnet",
+  },
+  arbitrumSepolia: {
+    name: "Arbitrum Sepolia",
+    chainId: 421614,
+    rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc",
+    contractAddress: "0xa430B2e0D1273464809f8541286058e90781DA9C",
+    logo: "https://arthuremma2.github.io/img-hosting/arb44.svg",
+    explorer: "https://sepolia.arbiscan.io/tx/",
+    type: "testnet",
+  },
 };
 
 const TOKEN_CONFIGS = {
@@ -116,6 +159,15 @@ const TOKEN_CONFIGS = {
       coingeckoId: "usd-coin",
       binanceSymbol: "USDCUSDT",
     },
+    {
+      symbol: "DAI",
+      name: "Dai Stablecoin",
+      icon: "https://move-flow.github.io/assets/dai-logo.svg",
+      address: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+      decimals: 18,
+      coingeckoId: "dai",
+      binanceSymbol: "DAIUSDT",
+    },
   ],
   polygon: [
     {
@@ -136,6 +188,15 @@ const TOKEN_CONFIGS = {
       coingeckoId: "tether",
       binanceSymbol: "USDTUSDT",
     },
+    {
+      symbol: "USDC",
+      name: "USD Coin",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
+      address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+      decimals: 6,
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
+    },
   ],
   base: [
     {
@@ -156,38 +217,172 @@ const TOKEN_CONFIGS = {
       coingeckoId: "usd-coin",
       binanceSymbol: "USDCUSDT",
     },
+    {
+      symbol: "USDbC",
+      name: "USD Base Coin",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
+      address: "0xd9aAEc86B65D86f6A7B5B1b0c42FFA531710b6CA",
+      decimals: 6,
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
+    },
   ],
   lisk: [
     {
       symbol: "ETH",
-      name: "Lisk",
-      icon: "https://arthuremma2.github.io/img-hosting/liskt.png",
+      name: "Ethereum",
+      icon: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
       address: "0x0000000000000000000000000000000000000000",
       decimals: 18,
       coingeckoId: "ethereum",
       binanceSymbol: "ETHUSDT",
     },
+    {
+      symbol: "LSK",
+      name: "Lisk",
+      icon: "https://arthuremma2.github.io/img-hosting/liskt.png",
+      address: "0x0000000000000000000000000000000000000000",
+      decimals: 18,
+      coingeckoId: "lisk",
+      binanceSymbol: "LSKUSDT",
+    },
   ],
-  sepolia: [
+  mezo: [
+    // {
+    //   symbol: "BTC",
+    //   name: "Bitcoin",
+    //   icon: "https://arthuremma2.github.io/img-hosting/btc.png",
+    //   address: "0x0000000000000000000000000000000000000000",
+    //   decimals: 18,
+    //   coingeckoId: "bitcoin",
+    //   binanceSymbol: "BTCUSDT",
+    // },
+    {
+      symbol: "MEZO",
+      name: "Mezo",
+      icon: "https://arthuremma2.github.io/img-hosting/mezo.png",
+      address: "0x0000000000000000000000000000000000000000",
+      decimals: 18,
+      coingeckoId: "mezo",
+      binanceSymbol: null,
+    },
+    {
+      symbol: "USDT",
+      name: "Mock USDT",
+      icon: "https://move-flow.github.io/assets/tether-usdt-logo.svg",
+      address: "0xd16c9c341Bc15B5db7E25881893CA5a3117bB9A5",
+      decimals: 6,
+      coingeckoId: "tether",
+      binanceSymbol: "USDTUSDT",
+    },
+  ],
+  arbitrum: [
     {
       symbol: "ETH",
-      name: "Sepolia ETH",
+      name: "Ethereum",
       icon: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
       address: "0x0000000000000000000000000000000000000000",
       decimals: 18,
       coingeckoId: "ethereum",
       binanceSymbol: "ETHUSDT",
     },
+    {
+      symbol: "USDC",
+      name: "USD Coin",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
+      address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+      decimals: 6,
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
+    },
     {
       symbol: "USDT",
-      name: "Mock USDT",
+      name: "Tether USD",
       icon: "https://move-flow.github.io/assets/tether-usdt-logo.svg",
-      address: "0x261322E2378467dd1cF5ac60A66817223db68fA3",
+      address: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+      decimals: 6,
+      coingeckoId: "tether",
+      binanceSymbol: "USDTUSDT",
+    },
+  ],
+  mezoTestnet: [
+    // {
+    //   symbol: "BTC",
+    //   name: "Bitcoin (Testnet)",
+    //   icon: "https://arthuremma2.github.io/img-hosting/btc.png",
+    //   address: "0x0000000000000000000000000000000000000000",
+    //   decimals: 18,
+    //   coingeckoId: "bitcoin",
+    //   binanceSymbol: "BTCUSDT",
+    // },
+    {
+      symbol: "Mezo",
+      name: "Mezo",
+      icon: "https://arthuremma2.github.io/img-hosting/mezo.png",
+      address: "0x7B7c000000000000000000000000000000000001",
       decimals: 18,
+      coingeckoId: "mezo",
+      binanceSymbol: "mezo",
+    },
+    {
+      symbol: "USDT",
+      name: "Mock USDT",
+      icon: "https://move-flow.github.io/assets/tether-usdt-logo.svg",
+      address: "0xd16c9c341Bc15B5db7E25881893CA5a3117bB9A5",
+      decimals: 6,
       coingeckoId: "tether",
       binanceSymbol: "USDTUSDT",
     },
   ],
+  liskTestnet: [
+    {
+      symbol: "ETH",
+      name: "Lisk Sepolia ETH",
+      icon: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
+      address: "0x0000000000000000000000000000000000000000",
+      decimals: 18,
+      coingeckoId: "ethereum",
+      binanceSymbol: "ETHUSDT",
+    },
+    {
+      symbol: "LSK",
+      name: "Lisk",
+      icon: "https://arthuremma2.github.io/img-hosting/liskt.png",
+      address: "0x8a21CF9Ba08Ae709D64Cb25AfAA951183EC9FF6D",
+      decimals: 18,
+      coingeckoId: "lisk",
+      binanceSymbol: "LSKUSDT",
+    },
+  ],
+  sepolia: [
+    {
+      symbol: "ETH",
+      name: "Sepolia ETH",
+      icon: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
+      address: "0x0000000000000000000000000000000000000000",
+      decimals: 18,
+      coingeckoId: "ethereum",
+      binanceSymbol: "ETHUSDT",
+    },
+    {
+      symbol: "MUSD",
+      name: "MUSD",
+      icon: "https://arthuremma2.github.io/img-hosting/MUSD.png",
+      address: "0xeB5a5d39dE4Ea42C2Aa6A57EcA2894376683bB8E",
+      decimals: 18,
+      coingeckoId: "",
+      binanceSymbol: "",
+    },
+    {
+      symbol: "USDC",
+      name: "Mock USDC",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
+      address: "0xeB5a5d39dE4Ea42C2Aa6A57EcA2894376683bB8E",
+      decimals: 6,
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
+    },
+  ],
   polygonAmoy: [
     {
       symbol: "MATIC",
@@ -199,13 +394,13 @@ const TOKEN_CONFIGS = {
       binanceSymbol: "MATICUSDT",
     },
     {
-      symbol: "USDc",
-      name: "Mock USDT",
-      icon: "https://move-flow.github.io/assets/tether-usdt-logo.svg",
+      symbol: "USDC",
+      name: "Mock USDC",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
       address: "0x8B0180f2101c8260d49339abfEe87927412494B4",
       decimals: 6,
-      coingeckoId: "tether",
-      binanceSymbol: "USDTUSDT",
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
     },
   ],
   baseSepolia: [
@@ -220,7 +415,7 @@ const TOKEN_CONFIGS = {
     },
     {
       symbol: "USDC",
-      name: "USD Coin",
+      name: "Mock USDC",
       icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
       address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
       decimals: 6,
@@ -228,24 +423,33 @@ const TOKEN_CONFIGS = {
       binanceSymbol: "USDCUSDT",
     },
   ],
-  liskTestnet: [
+  arbitrumSepolia: [
     {
       symbol: "ETH",
-      name: "Lisk Sepolia",
-      icon: "https://arthuremma2.github.io/img-hosting/lisk-logo.png",
+      name: "Arbitrum Sepolia ETH",
+      icon: "https://arthuremma2.github.io/img-hosting/ethereum-eth.svg",
       address: "0x0000000000000000000000000000000000000000",
       decimals: 18,
       coingeckoId: "ethereum",
       binanceSymbol: "ETHUSDT",
     },
     {
-      symbol: "LSK",
-      name: "Lisk",
-      icon: "https://arthuremma2.github.io/img-hosting/liskt.png",
-      address: "0x8a21CF9Ba08Ae709D64Cb25AfAA951183EC9FF6D",
+      symbol: "USDC",
+      name: "Mock USDC",
+      icon: "https://move-flow.github.io/assets/usd-coin-usdc-logo.svg",
+      address: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
+      decimals: 6,
+      coingeckoId: "usd-coin",
+      binanceSymbol: "USDCUSDT",
+    },
+    {
+      symbol: "ARB",
+      name: "Arbitrum (Testnet)",
+      icon: "https://arthuremma2.github.io/img-hosting/arb44.svg",
+      address: "0x15dd68a7a37d7edBf284b93Bc25d6b286d33fCc3",
       decimals: 18,
-      coingeckoId: "LSK",
-      binanceSymbol: "LSK",
+      coingeckoId: "arbitrum",
+      binanceSymbol: "ARBUSDT",
     },
   ],
 };
@@ -809,36 +1013,36 @@ class PaymentService {
   constructor(apiKey, graphqlEndpoint) {
     this.apiKey = apiKey;
     this.graphqlEndpoint = graphqlEndpoint;
+    this._graphqlEndpoint = graphqlEndpoint;
+    this._apiKey = apiKey;
     this.client = null;
-
-    console.log("[KwesPay] PaymentService initialized", {
-      apiKey: this.apiKey?.slice(0, 6) + "...",
-    });
   }
 
   async _initClient() {
     if (this.client) return;
-
-    console.log("[KwesPay] Initializing SDK client...");
-
-    const { KwesPayClient } = await import('./index-338l55OY.js');
-
+    const { KwesPayClient } = await import('./index-BDgXWGKX.js');
     this.client = new KwesPayClient({ apiKey: this.apiKey });
+  }
 
-    console.log("[KwesPay] SDK client ready");
+  async _rawGql(query, variables) {
+    const res = await fetch(this._graphqlEndpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-API-Key": this._apiKey,
+      },
+      body: JSON.stringify({ query, variables }),
+    });
+    return res.json();
   }
 
   async validateAPIKey() {
     try {
       await this._initClient();
-
       const result = await this.client.validateKey();
-
       if (!result.isValid) {
-        console.error("[KwesPay] Invalid API key:", result.error);
         return { valid: false, error: result.error ?? "Invalid access key" };
       }
-
       return {
         valid: true,
         keyId: result.keyId,
@@ -855,94 +1059,94 @@ class PaymentService {
 
   async getQuote(params) {
     await this._initClient();
-
-    console.log("[KwesPay] Requesting quote...", params);
-
-    const quote = await this.client.quote({
-      vendorIdentifier: params.vendorId,
+    return this.client.getQuote({
+      vendorIdentifier: params.vendorIdentifier,
       fiatAmount: params.fiatAmount,
       fiatCurrency: params.fiatCurrency || "USD",
       cryptoCurrency: params.cryptoCurrency,
       network: params.network,
-      payerWalletAddress: params.payerWalletAddress,
     });
-
-    console.log("[KwesPay] Quote received:", quote);
-
-    return quote;
   }
 
   async createPayment({ payload, walletProvider, onStatusUpdate }) {
     await this._initClient();
 
-    console.log("[KwesPay] 💳 createPayment called", {
-      payloadKeys: payload ? Object.keys(payload) : null,
-      amountBaseUnits: payload?.amountBaseUnits,
-      contractAddress: payload?.contractAddress,
-      paymentId: payload?.paymentId,
-      vendorAddress: payload?.vendorAddress,
-      expiresAt: payload?.expiresAt,
-      providerType: walletProvider?.constructor?.name,
-    });
-
-    try {
-      const result = await this.client.pay({
-        provider: walletProvider,
-        payload,
-        onStatus: (status) => {
-          console.log("[KwesPay] 📋 Payment status update:", status);
-          onStatusUpdate?.(status);
-        },
-      });
+    const accounts = await walletProvider.request({ method: "eth_accounts" });
+    const payerWalletAddress = accounts[0];
+
+    // Call createTransaction directly so we can request the deadline field,
+    // which the SDK's GQL_CREATE_TRANSACTION query does not yet include.
+    const rawTx = await this._rawGql(
+      `mutation CreateTransaction($input: CreateTransactionInput!) {
+        createTransaction(input: $input) {
+          success
+          message
+          paymentIdBytes32
+          backendSignature
+          tokenAddress
+          amountBaseUnits
+          chainId
+          deadline
+          expiresAt
+          transaction {
+            transactionReference
+            transactionStatus
+          }
+        }
+      }`,
+      { input: { quoteId: payload.quoteId, payerWalletAddress } }
+    );
 
-      console.log("[KwesPay] ✅ Payment completed:", result);
+    const ct = rawTx?.data?.createTransaction;
 
-      return {
-        hash: result.txHash,
-        blockNumber: result.blockNumber,
-        transactionReference: result.transactionReference,
-        paymentIdBytes32: result.paymentIdBytes32,
-      };
-    } catch (err) {
-      console.error("[KwesPay] ❌ createPayment error:", {
-        message: err?.message,
-        code: err?.code,
-        reason: err?.reason,
-        data: err?.data,
-        transaction: err?.transaction
-          ? {
-              to: err.transaction?.to,
-              from: err.transaction?.from,
-              value: err.transaction?.value?.toString(),
-              gasLimit: err.transaction?.gasLimit?.toString(),
-              data: err.transaction?.data,
-            }
-          : undefined,
-        receipt: err?.receipt
-          ? {
-              status: err.receipt?.status,
-              gasUsed: err.receipt?.gasUsed?.toString(),
-              blockNumber: err.receipt?.blockNumber,
-              transactionHash: err.receipt?.transactionHash,
-            }
-          : undefined,
-        stack: err?.stack,
-        raw: err,
-      });
-      throw err;
+    if (!ct?.success) {
+      throw new Error(ct?.message ?? "Transaction creation failed");
     }
-  }
 
-  async getTransactionStatus(transactionReference) {
-    await this._initClient();
+    if (!ct.deadline) {
+      throw new Error("Backend did not return a deadline");
+    }
 
-    console.log("[KwesPay] Fetching transaction status:", transactionReference);
+    // Compute totalBaseUnits locally — mirrors the contract formula:
+    // fee = (amount * 50) / 10000,  total = amount + fee
+    const PLATFORM_FEE_BPS = 50n;
+    const amountBig = BigInt(ct.amountBaseUnits);
+    const feeBig = (amountBig * PLATFORM_FEE_BPS) / 10000n;
+    const totalBig = amountBig + feeBig;
+
+    // Build the complete TransactionPayload the SDK's pay() expects.
+    const txPayload = {
+      paymentIdBytes32: ct.paymentIdBytes32,
+      backendSignature: ct.backendSignature,
+      tokenAddress: ct.tokenAddress,
+      amountBaseUnits: ct.amountBaseUnits,
+      totalBaseUnits: totalBig.toString(),
+      chainId: ct.chainId,
+      deadline: ct.deadline,
+      expiresAt: ct.expiresAt,
+      transactionReference: ct.transaction.transactionReference,
+      transactionStatus: ct.transaction.transactionStatus,
+      network: payload.network,
+      vendorIdentifier: payload.vendorIdentifier,
+    };
 
-    const status = await this.client.getTransactionStatus(transactionReference);
+    const result = await this.client.pay({
+      provider: walletProvider,
+      payload: txPayload,
+      onStatus: (title, detail) => onStatusUpdate?.(title, detail),
+    });
 
-    console.log("[KwesPay] Transaction status:", status);
+    return {
+      hash: result.txHash,
+      blockNumber: result.blockNumber,
+      transactionReference: result.transactionReference,
+      paymentIdBytes32: result.paymentIdBytes32,
+    };
+  }
 
-    return status;
+  async getTransactionStatus(transactionReference) {
+    await this._initClient();
+    return this.client.getTransactionStatus(transactionReference);
   }
 
   async pollTransactionStatus(
@@ -950,28 +1154,13 @@ class PaymentService {
     { onStatus, intervalMs = 4000, maxAttempts = 60 } = {}
   ) {
     await this._initClient();
-
-    console.log("[KwesPay] Starting polling...", {
-      transactionReference,
-      intervalMs,
-    });
-
     let attempts = 0;
-
     return new Promise((resolve, reject) => {
       const id = setInterval(async () => {
         attempts++;
-
         try {
           const status = await this.getTransactionStatus(transactionReference);
-
-          console.log(
-            `[KwesPay] Poll attempt ${attempts}:`,
-            status.transactionStatus
-          );
-
           onStatus?.(status.transactionStatus);
-
           const terminal = [
             "completed",
             "failed",
@@ -980,22 +1169,14 @@ class PaymentService {
             "overpaid",
             "refunded",
           ];
-
           if (terminal.includes(status.transactionStatus)) {
-            console.log(
-              "[KwesPay] Final status reached:",
-              status.transactionStatus
-            );
             clearInterval(id);
             resolve(status);
           } else if (attempts >= maxAttempts) {
-            console.error("[KwesPay] Polling timeout");
             clearInterval(id);
             reject(new Error("Transaction status polling timed out."));
           }
         } catch (err) {
-          console.error("[KwesPay] Polling error:", err);
-
           if (attempts >= maxAttempts) {
             clearInterval(id);
             reject(err);
@@ -1026,6 +1207,18 @@ function truncateHash(hash, startChars = 10, endChars = 8) {
   return `${hash.slice(0, startChars)}...${hash.slice(-endChars)}`;
 }
 
+function formatCryptoAmount(amount, symbol = "") {
+  const num = typeof amount === "string" ? parseFloat(amount) : amount;
+  if (isNaN(num) || num === 0) return symbol ? `0 ${symbol}` : "0";
+
+  const magnitude = Math.floor(Math.log10(Math.abs(num)));
+  const decimalPlaces = Math.max(0, 5 - magnitude);
+  const capped = Math.min(decimalPlaces, 8);
+  const formatted = num.toFixed(capped).replace(/\.?0+$/, "");
+
+  return symbol ? `${formatted} ${symbol}` : formatted;
+}
+
 function getErrorType(error) {
   const msg = error?.message ?? "";
   if (
@@ -1090,20 +1283,20 @@ const WIDGET_STYLES = `
   * { margin: 0; padding: 0; box-sizing: border-box; }
 
   :root {
-    --kp-bg: #0a0a0f;
-    --kp-surface: #0f0f18;
-    --kp-surface-2: #16161f;
-    --kp-border: rgba(255,255,255,0.06);
+    --kp-bg:           #0a0a0f;
+    --kp-surface:      #0f0f18;
+    --kp-surface-2:    #16161f;
+    --kp-border:       rgba(255,255,255,0.06);
     --kp-border-active: rgba(99,102,241,0.5);
-    --kp-accent: #6366f1;
-    --kp-accent-dim: rgba(99,102,241,0.1);
-    --kp-accent-glow: rgba(99,102,241,0.25);
-    --kp-green: #10b981;
-    --kp-red: #f43f5e;
-    --kp-text: #f1f0ff;
-    --kp-muted: #6b6a80;
-    --kp-mono: 'Inter', monospace;
-    --kp-sans: 'Inter', sans-serif;
+    --kp-accent:       #6366f1;
+    --kp-accent-dim:   rgba(99,102,241,0.1);
+    --kp-accent-glow:  rgba(99,102,241,0.25);
+    --kp-green:        #10b981;
+    --kp-red:          #f43f5e;
+    --kp-text:         #f1f0ff;
+    --kp-muted:        #6b6a80;
+    --kp-mono:         'Inter', monospace;
+    --kp-sans:         'Inter', sans-serif;
   }
 
   body.kwespay-open {
@@ -1128,19 +1321,17 @@ const WIDGET_STYLES = `
 
   .kwespay-close-btn {
     position: absolute;
-    top: 20px; right: 20px;
+    top: 12px; right: 12px;
     background: rgba(255,255,255,0.06);
     border: 1px solid var(--kp-border);
     color: var(--kp-muted);
-    width: 34px; height: 34px;
-    border-radius: 8px;
+    width: 28px; height: 28px;
+    border-radius: 7px;
     cursor: pointer;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    font-size: 18px;
+    display: flex; align-items: center; justify-content: center;
+    font-size: 16px;
     transition: all 0.15s;
-    z-index: 1000000;
+    z-index: 10;
   }
 
   .kwespay-close-btn:hover {
@@ -1149,6 +1340,12 @@ const WIDGET_STYLES = `
     border-color: var(--kp-border-active);
   }
 
+  .kwespay-steps-wrapper {
+    position: relative;
+    flex: 1;
+    overflow: hidden;
+  }
+
   .material-symbols-outlined {
     font-variation-settings: "FILL" 0, "wght" 400, "GRAD" 0, "opsz" 24;
   }
@@ -1207,6 +1404,8 @@ const WIDGET_STYLES = `
     to   { opacity: 0; }
   }
 
+
+
   .kp-topbar {
     display: flex;
     align-items: center;
@@ -1223,11 +1422,8 @@ const WIDGET_STYLES = `
   }
 
   .kp-back-btn {
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    width: 28px;
-    height: 28px;
+    display: flex; align-items: center; justify-content: center;
+    width: 28px; height: 28px;
     border-radius: 7px;
     background: rgba(255,255,255,0.04);
     border: 1px solid var(--kp-border);
@@ -1252,11 +1448,12 @@ const WIDGET_STYLES = `
     background: var(--kp-accent);
     box-shadow: 0 0 8px var(--kp-accent-glow);
     animation: kpPulse 2s ease infinite;
+    flex-shrink: 0;
   }
 
   @keyframes kpPulse {
     0%, 100% { opacity: 1; }
-    50% { opacity: 0.5; }
+    50%       { opacity: 0.4; }
   }
 
   .kp-topbar-name {
@@ -1267,9 +1464,7 @@ const WIDGET_STYLES = `
   }
 
   .kp-topbar-secure {
-    display: flex;
-    align-items: center;
-    gap: 5px;
+    display: flex; align-items: center; gap: 5px;
     font-family: var(--kp-mono);
     font-size: 10px;
     color: var(--kp-muted);
@@ -1277,10 +1472,8 @@ const WIDGET_STYLES = `
     font-weight: 500;
   }
 
-  .kp-topbar-secure .material-symbols-outlined {
-    font-size: 13px;
-    color: var(--kp-green);
-  }
+  .kp-topbar-secure .material-symbols-outlined { font-size: 13px; color: var(--kp-green); }
+
 
   .kp-amount-block {
     padding: 20px 20px 16px;
@@ -1327,6 +1520,8 @@ const WIDGET_STYLES = `
 
   .kp-amount-crypto.loading { opacity: 0.4; }
 
+  /* ── Progress ───────────────────────────────────────────────────────────── */
+
   .progress-section {
     padding: 14px 20px 12px;
     border-bottom: 1px solid var(--kp-border);
@@ -1334,9 +1529,7 @@ const WIDGET_STYLES = `
   }
 
   .progress-info {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
+    display: flex; align-items: center; justify-content: space-between;
     margin-bottom: 8px;
   }
 
@@ -1359,8 +1552,7 @@ const WIDGET_STYLES = `
   .progress-bars { display: flex; width: 100%; gap: 5px; }
 
   .progress-bar {
-    height: 2px;
-    flex: 1;
+    height: 2px; flex: 1;
     border-radius: 999px;
     background: var(--kp-surface-2);
     transition: background 0.3s ease;
@@ -1371,6 +1563,8 @@ const WIDGET_STYLES = `
     box-shadow: 0 0 8px var(--kp-accent-glow);
   }
 
+  /* ── Scrollable content ─────────────────────────────────────────────────── */
+
   .section-hint {
     font-size: 12px;
     color: var(--kp-muted);
@@ -1394,10 +1588,10 @@ const WIDGET_STYLES = `
     border-radius: 10px;
   }
 
+  /* ── Network list ───────────────────────────────────────────────────────── */
+
   .item-list {
-    display: flex;
-    flex-direction: column;
-    gap: 6px;
+    display: flex; flex-direction: column; gap: 6px;
     margin-bottom: 6px;
   }
 
@@ -1416,9 +1610,7 @@ const WIDGET_STYLES = `
   }
 
   .list-item {
-    display: flex;
-    align-items: center;
-    gap: 12px;
+    display: flex; align-items: center; gap: 12px;
     background: var(--kp-surface);
     padding: 12px 14px;
     border-radius: 12px;
@@ -1443,15 +1635,11 @@ const WIDGET_STYLES = `
     flex-shrink: 0;
   }
 
-  .item-icon img { width: 22px; height: 22px; object-fit: contain; }
+  .item-icon img { width: 28px; height: 28px; object-fit: contain; }
   .item-info { display: flex; flex-direction: column; flex: 1; }
   .item-name-row { display: flex; align-items: center; gap: 7px; }
 
-  .item-name {
-    font-size: 13px;
-    font-weight: 600;
-    color: var(--kp-text);
-  }
+  .item-name { font-size: 13px; font-weight: 600; color: var(--kp-text); }
 
   .item-badge {
     padding: 1px 6px;
@@ -1479,10 +1667,10 @@ const WIDGET_STYLES = `
 
   .item-chevron { color: var(--kp-muted); font-size: 16px; }
 
+  /* ── Token list ─────────────────────────────────────────────────────────── */
+
   .token-item {
-    display: flex;
-    align-items: center;
-    gap: 12px;
+    display: flex; align-items: center; gap: 12px;
     padding: 13px 14px;
     cursor: pointer;
     transition: all 0.15s;
@@ -1495,14 +1683,24 @@ const WIDGET_STYLES = `
   }
 
   .token-item:last-child { margin-bottom: 0; }
-  .token-item:hover { border-color: var(--kp-border-active); background: var(--kp-accent-dim); }
-  .token-item.selected { background: var(--kp-accent-dim); border-color: var(--kp-accent); }
+
+  .token-item:hover {
+    border-color: var(--kp-border-active);
+    background: var(--kp-accent-dim);
+  }
+
+  .token-item.selected {
+    background: var(--kp-accent-dim);
+    border-color: var(--kp-accent);
+  }
+
   .token-item.selected::after {
     content: '';
     position: absolute; inset: 0;
     background: linear-gradient(90deg, rgba(99,102,241,0.08) 0%, transparent 100%);
     pointer-events: none;
   }
+
   .token-item.selected .token-symbol { color: var(--kp-accent); }
 
   .token-left { display: flex; align-items: center; gap: 12px; flex: 1; }
@@ -1512,11 +1710,8 @@ const WIDGET_STYLES = `
     border-radius: 10px;
     background: var(--kp-surface-2);
     border: 1px solid var(--kp-border);
-    overflow: hidden;
-    flex-shrink: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
+    overflow: hidden; flex-shrink: 0;
+    display: flex; align-items: center; justify-content: center;
   }
 
   .token-icon img { width: 22px; height: 22px; object-fit: contain; }
@@ -1542,6 +1737,8 @@ const WIDGET_STYLES = `
   .token-chevron { color: var(--kp-muted); font-size: 16px; flex-shrink: 0; }
   #kwespay-tokenList { display: flex; flex-direction: column; }
 
+  /* ── Buttons ────────────────────────────────────────────────────────────── */
+
   .bottom-action {
     padding: 12px 20px 16px;
     background: var(--kp-bg);
@@ -1583,6 +1780,7 @@ const WIDGET_STYLES = `
   }
 
   .action-btn.secondary::before { display: none; }
+
   .action-btn.secondary:hover {
     background: var(--kp-surface-2);
     border-color: var(--kp-border-active);
@@ -1592,14 +1790,13 @@ const WIDGET_STYLES = `
 
   .action-btn:disabled { opacity: 0.3; cursor: not-allowed; box-shadow: none; }
 
+  /* ── Footer ─────────────────────────────────────────────────────────────── */
+
   .kp-footer {
     padding: 10px 20px 12px;
     background: var(--kp-bg);
     border-top: 1px solid var(--kp-border);
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    gap: 6px;
+    display: flex; align-items: center; justify-content: center; gap: 6px;
     flex-shrink: 0;
   }
 
@@ -1615,11 +1812,11 @@ const WIDGET_STYLES = `
 
   .kp-footer-text span { color: var(--kp-text); font-weight: 500; }
 
+  /* ── Spinner / loading ──────────────────────────────────────────────────── */
+
   .loading-container {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
     padding: 24px 20px;
     flex: 1;
   }
@@ -1649,6 +1846,21 @@ const WIDGET_STYLES = `
     animation: kpSpin 1.2s linear infinite reverse;
   }
 
+  .kp-spin-soft.spinner-ring {
+    border-top-color: rgba(16,185,129,0.55);
+    animation-duration: 1.6s;
+  }
+
+  .kp-spin-soft.spinner-ring-2 {
+    border-bottom-color: rgba(16,185,129,0.18);
+    animation-duration: 2.2s;
+  }
+
+  .kp-spinner-icon-green {
+    background: rgba(16,185,129,0.08) !important;
+    border-color: rgba(16,185,129,0.15) !important;
+  }
+
   @keyframes kpSpin { to { transform: rotate(360deg); } }
 
   .spinner-icon {
@@ -1682,6 +1894,39 @@ const WIDGET_STYLES = `
     font-weight: 400;
   }
 
+  /* ── Processing badges ──────────────────────────────────────────────────── */
+
+  .kp-onchain-badge {
+    display: inline-flex; align-items: center; gap: 5px;
+    margin-top: 14px;
+    padding: 6px 14px;
+    border-radius: 20px;
+    background: rgba(16,185,129,0.08);
+    border: 1px solid rgba(16,185,129,0.18);
+    font-family: var(--kp-mono);
+    font-size: 10px;
+    color: var(--kp-green);
+    letter-spacing: 0.04em;
+    font-weight: 500;
+  }
+
+  .kp-onchain-badge .material-symbols-outlined { font-size: 12px; color: var(--kp-green); }
+
+  .kp-confirmed-bar {
+    display: flex; align-items: center; justify-content: center; gap: 6px;
+    padding: 8px 20px;
+    background: rgba(16,185,129,0.06);
+    border-bottom: 1px solid rgba(16,185,129,0.12);
+    font-family: var(--kp-mono);
+    font-size: 10px;
+    color: var(--kp-green);
+    letter-spacing: 0.04em;
+    font-weight: 500;
+    flex-shrink: 0;
+  }
+
+  /* ── Success icons ──────────────────────────────────────────────────────── */
+
   .success-icon {
     width: 64px; height: 64px;
     border-radius: 16px;
@@ -1693,6 +1938,8 @@ const WIDGET_STYLES = `
 
   .success-icon .material-symbols-outlined { font-size: 36px; color: var(--kp-green); }
 
+  /* ── Error icon + hint ──────────────────────────────────────────────────── */
+
   .error-icon {
     width: 64px; height: 64px;
     border-radius: 16px;
@@ -1704,12 +1951,28 @@ const WIDGET_STYLES = `
 
   .error-icon .material-symbols-outlined { font-size: 36px; color: var(--kp-red); }
 
+  /* Reassuring strip below the error message */
+  .kp-error-hint {
+    display: flex; align-items: flex-start; gap: 7px;
+    margin-top: 16px;
+    padding: 10px 14px;
+    border-radius: 10px;
+    background: rgba(255,255,255,0.03);
+    border: 1px solid var(--kp-border);
+    font-family: var(--kp-mono);
+    font-size: 11px;
+    color: var(--kp-muted);
+    line-height: 1.55;
+    max-width: 280px;
+    text-align: left;
+  }
+
+  /* ── Network status pill ────────────────────────────────────────────────── */
+
   .network-status { padding: 14px 20px 0; }
 
   .status-card {
-    display: flex;
-    align-items: center;
-    gap: 10px;
+    display: flex; align-items: center; gap: 10px;
     background: var(--kp-accent-dim);
     border: 1px solid rgba(99,102,241,0.2);
     border-radius: 10px;
@@ -1727,6 +1990,8 @@ const WIDGET_STYLES = `
   .status-icon img { width: 16px; height: 16px; object-fit: contain; }
   .status-text { color: var(--kp-accent); font-size: 12px; font-weight: 600; flex: 1; }
 
+  /* ── Review body ────────────────────────────────────────────────────────── */
+
   .kp-review-body { flex: 1; overflow-y: auto; padding: 16px 20px; }
   .kp-review-body::-webkit-scrollbar { width: 3px; }
   .kp-review-body::-webkit-scrollbar-thumb { background: rgba(99,102,241,0.2); border-radius: 10px; }
@@ -1758,6 +2023,8 @@ const WIDGET_STYLES = `
 
   .kp-review-crypto-line.loading { opacity: 0.4; }
 
+  /* ── Detail / fee blocks ────────────────────────────────────────────────── */
+
   .kp-detail-block {
     background: var(--kp-surface);
     border: 1px solid var(--kp-border);
@@ -1767,9 +2034,7 @@ const WIDGET_STYLES = `
   }
 
   .kp-detail-row {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
+    display: flex; justify-content: space-between; align-items: center;
     padding: 11px 16px;
     border-bottom: 1px solid var(--kp-border);
   }
@@ -1793,7 +2058,7 @@ const WIDGET_STYLES = `
   }
 
   .kp-detail-val.accent { color: var(--kp-accent); }
-  .kp-detail-val.green { color: var(--kp-green); }
+  .kp-detail-val.green  { color: var(--kp-green); }
 
   .kp-fee-block {
     background: rgba(16,185,129,0.04);
@@ -1823,6 +2088,8 @@ const WIDGET_STYLES = `
 
   .kp-fee-header .material-symbols-outlined { font-size: 13px; color: var(--kp-green); }
 
+  /* ── Transaction receipt ────────────────────────────────────────────────── */
+
   .tx-details {
     width: 100%;
     background: var(--kp-surface);
@@ -1833,17 +2100,15 @@ const WIDGET_STYLES = `
   }
 
   .tx-row {
-    display: flex;
-    justify-content: space-between;
-    align-items: center;
+    display: flex; justify-content: space-between; align-items: center;
     padding: 10px 16px;
     border-bottom: 1px solid var(--kp-border);
   }
 
   .tx-row:last-child { border-bottom: none; }
 
-  .tx-label { font-family: var(--kp-mono); color: var(--kp-muted); font-size: 10px; letter-spacing: 0.02em; font-weight: 400; }
-  .tx-value { color: var(--kp-text); font-size: 11px; font-weight: 500; font-family: var(--kp-mono); }
+  .tx-label  { font-family: var(--kp-mono); color: var(--kp-muted); font-size: 10px; letter-spacing: 0.02em; font-weight: 400; }
+  .tx-value  { color: var(--kp-text); font-size: 11px; font-weight: 500; font-family: var(--kp-mono); }
   .tx-hash-row { display: flex; align-items: center; gap: 8px; }
 
   .explorer-link {
@@ -1860,26 +2125,57 @@ const WIDGET_STYLES = `
   .explorer-link:hover { background: rgba(99,102,241,0.2); }
   .explorer-link .material-symbols-outlined { font-size: 12px; color: var(--kp-accent); }
 
+
+
+  /* Full-width track that drains left-to-right */
+  .kp-countdown-track {
+    width: 100%;
+    height: 3px;
+    border-radius: 999px;
+    background: var(--kp-surface-2);
+    overflow: hidden;
+    margin-bottom: 6px;
+  }
+
+  .kp-countdown-bar {
+    height: 100%;
+    width: 100%;
+    border-radius: 999px;
+    background: var(--kp-accent);
+    /* smooth drain: transition only width changes */
+    transition: width 0.9s linear, background 0.4s ease;
+  }
+
+  .kp-countdown-label {
+    font-family: var(--kp-mono);
+    font-size: 10px;
+    color: var(--kp-muted);
+    text-align: center;
+    letter-spacing: 0.04em;
+    font-weight: 400;
+    margin-bottom: 2px;
+  }
+
+
+
   .mobile-instruction {
     background: var(--kp-accent-dim);
     border: 1px solid rgba(99,102,241,0.2);
     border-radius: 10px;
     padding: 12px;
     margin: 12px 0 0;
-    display: flex;
-    align-items: flex-start;
-    gap: 10px;
+    display: flex; align-items: flex-start; gap: 10px;
   }
 
   .mobile-instruction-icon { color: var(--kp-accent); font-size: 18px; flex-shrink: 0; margin-top: 1px; }
   .mobile-instruction-text { flex: 1; }
   .mobile-instruction-title { color: var(--kp-text); font-size: 12px; font-weight: 600; margin-bottom: 3px; }
-  .mobile-instruction-desc { color: var(--kp-muted); font-size: 11px; line-height: 1.5; font-weight: 400; }
+  .mobile-instruction-desc  { color: var(--kp-muted); font-size: 11px; line-height: 1.5; font-weight: 400; }
+
+  /* ── Quote timer ────────────────────────────────────────────────────────── */
 
   .kp-quote-timer {
-    display: flex;
-    align-items: center;
-    gap: 5px;
+    display: flex; align-items: center; gap: 5px;
     font-family: var(--kp-mono);
     font-size: 10px;
     color: var(--kp-muted);
@@ -1887,9 +2183,33 @@ const WIDGET_STYLES = `
     font-weight: 400;
   }
 
-  .kp-quote-timer .material-symbols-outlined { font-size: 12px; }
-  .kp-quote-timer.urgent { color: #fb923c; }
-  .kp-quote-timer.expired { color: var(--kp-red); }
+  .kp-quote-timer .material-symbols-outlined { font-size: 12px; }
+  .kp-quote-timer.urgent  { color: #fb923c; }
+  .kp-quote-timer.expired { color: var(--kp-red); }
+
+  /* ── WalletConnect mobile ───────────────────────────────────────────────── */
+
+  .kp-mobile-connect-status {
+    display: flex; align-items: center; gap: 12px;
+    background: var(--kp-accent-dim);
+    border: 1px solid rgba(99,102,241,0.2);
+    border-radius: 12px;
+    padding: 14px 16px;
+    margin-bottom: 4px;
+  }
+
+  .kp-mobile-status-icon { width: 28px; height: 28px; display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
+  .kp-mobile-status-text { flex: 1; }
+  .kp-mobile-status-title { font-size: 13px; font-weight: 600; color: var(--kp-text); margin-bottom: 2px; }
+  .kp-mobile-status-desc  { font-family: var(--kp-mono); font-size: 11px; color: var(--kp-muted); }
+
+  .kp-wallet-option:active {
+    transform: scale(0.98);
+    background: var(--kp-accent-dim);
+    border-color: var(--kp-border-active);
+  }
+
+
 
   @media (max-width: 480px) {
     .kwespay-overlay {
@@ -1928,66 +2248,25 @@ const WIDGET_STYLES = `
     }
   }
 
-
-.kp-mobile-connect-status {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  background: var(--kp-accent-dim);
-  border: 1px solid rgba(99,102,241,0.2);
-  border-radius: 12px;
-  padding: 14px 16px;
-  margin-bottom: 4px;
-}
-
-.kp-mobile-status-icon {
-  width: 28px; height: 28px;
-  display: flex; align-items: center; justify-content: center;
-  flex-shrink: 0;
-}
-
-.kp-mobile-status-text { flex: 1; }
-
-.kp-mobile-status-title {
-  font-size: 13px;
-  font-weight: 600;
-  color: var(--kp-text);
-  margin-bottom: 2px;
-}
-
-.kp-mobile-status-desc {
-  font-family: var(--kp-mono);
-  font-size: 11px;
-  color: var(--kp-muted);
-}
-
-.kp-wallet-option:active {
-  transform: scale(0.98);
-  background: var(--kp-accent-dim);
-  border-color: var(--kp-border-active);
-}
-
-
   @keyframes kpSheetUp {
     from { transform: translateY(100%); opacity: 0.8; }
-    to   { transform: translateY(0); opacity: 1; }
+    to   { transform: translateY(0);    opacity: 1; }
   }
 
   @keyframes kpSheetDown {
-    from { transform: translateY(0); opacity: 1; }
+    from { transform: translateY(0);    opacity: 1; }
     to   { transform: translateY(100%); opacity: 0; }
   }
 `;
 
 function getStepTemplates(fiatAmount, currency) {
   return `
+    <!-- Step 0: Initialising -->
     <div class="step active" id="kwespay-step0">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot"></div>
           <span class="kp-topbar-name">KwesPay Checkout</span>
         </div>
-        
       </div>
       <div class="loading-container" style="flex:1">
         <div class="spinner-wrapper">
@@ -2006,10 +2285,10 @@ function getStepTemplates(fiatAmount, currency) {
       </div>
     </div>
 
+    <!-- Step 0.5: API key invalid / network error on init -->
     <div class="step" id="kwespay-step0-invalid">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot" style="background:var(--kp-red);box-shadow:none;animation:none"></div>
           <span class="kp-topbar-name">KwesPay Checkout</span>
         </div>
       </div>
@@ -2025,13 +2304,12 @@ function getStepTemplates(fiatAmount, currency) {
       </div>
     </div>
 
+    <!-- Step 1: Select Network -->
     <div class="step" id="kwespay-step1">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot"></div>
           <span class="kp-topbar-name">KwesPay Checkout</span>
         </div>
-       
       </div>
       <div class="kp-amount-block">
         <div class="kp-amount-label">Total due</div>
@@ -2059,21 +2337,19 @@ function getStepTemplates(fiatAmount, currency) {
       </div>
     </div>
 
+    <!-- Step 2: Select Token -->
     <div class="step" id="kwespay-step2">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
           <button class="kp-back-btn" id="kwespay-back2">
             <span class="material-symbols-outlined">arrow_back</span>
           </button>
-          <div class="kp-topbar-dot"></div>
           <span class="kp-topbar-name">KwesPay Checkout</span>
         </div>
-       
       </div>
       <div class="kp-amount-block">
         <div class="kp-amount-label">Total due</div>
         <div class="kp-amount-value">${fiatAmount} ${currency}</div>
-        <div class="kp-amount-hint">Select a token — exact amount shown at review</div>
       </div>
       <div class="progress-section">
         <div class="progress-info">
@@ -2102,16 +2378,15 @@ function getStepTemplates(fiatAmount, currency) {
       </div>
     </div>
 
+    <!-- Step 3: Review & Pay -->
     <div class="step" id="kwespay-step3">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
           <button class="kp-back-btn" id="kwespay-back3">
             <span class="material-symbols-outlined">arrow_back</span>
           </button>
-          <div class="kp-topbar-dot"></div>
           <span class="kp-topbar-name">KwesPay Checkout</span>
         </div>
-        
       </div>
       <div class="progress-section">
         <div class="progress-info">
@@ -2133,37 +2408,35 @@ function getStepTemplates(fiatAmount, currency) {
             <span id="kwespay-quoteTimerText">—</span>
           </div>
         </div>
-
         <div class="kp-detail-block">
           <div class="kp-detail-row">
-            <span class="kp-detail-key">wallet</span>
+            <span class="kp-detail-key">Wallet</span>
             <span class="kp-detail-val" id="kwespay-connectedWalletAddress">—</span>
           </div>
           <div class="kp-detail-row">
-            <span class="kp-detail-key">network</span>
+            <span class="kp-detail-key">Network</span>
             <span class="kp-detail-val" id="kwespay-summaryNetwork">—</span>
           </div>
           <div class="kp-detail-row">
-            <span class="kp-detail-key">token</span>
+            <span class="kp-detail-key">Token</span>
             <span class="kp-detail-val accent" id="kwespay-summaryToken">—</span>
           </div>
         </div>
-
         <div class="kp-fee-block">
           <div class="kp-fee-header">
             <span class="material-symbols-outlined">receipt_long</span>
             <span class="kp-fee-header-text">Fee Breakdown</span>
           </div>
           <div class="kp-detail-row">
-            <span class="kp-detail-key">payment amount</span>
+            <span class="kp-detail-key">Payment amount</span>
             <span class="kp-detail-val" id="kwespay-feePaymentAmount">—</span>
           </div>
           <div class="kp-detail-row">
-            <span class="kp-detail-key">platform fee (0.25%)</span>
+            <span class="kp-detail-key">Platform fee (0.25%)</span>
             <span class="kp-detail-val" id="kwespay-feePlatformFee">—</span>
           </div>
           <div class="kp-detail-row">
-            <span class="kp-detail-key">vendor receives</span>
+            <span class="kp-detail-key">Vendor receives</span>
             <span class="kp-detail-val green" id="kwespay-feeVendorAmount">—</span>
           </div>
         </div>
@@ -2174,14 +2447,18 @@ function getStepTemplates(fiatAmount, currency) {
       </div>
     </div>
 
+    <!-- Step 4: Processing / Confirming / Success (mutating sub-views) -->
     <div class="step" id="kwespay-step4">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot"></div>
-          <span class="kp-topbar-name">KwesPay Checkout</span>
+          <div class="kp-topbar-dot" id="kwespay-step4-dot"></div>
+          <span class="kp-topbar-name" id="kwespay-step4-title">KwesPay Checkout</span>
         </div>
+        
       </div>
-      <div class="loading-container" style="flex:1">
+
+      <!-- Sub-view: processing (wallet approval + on-chain) -->
+      <div id="kwespay-view-processing" class="loading-container" style="flex:1">
         <div class="spinner-wrapper">
           <div class="spinner-ring"></div>
           <div class="spinner-ring-2"></div>
@@ -2199,62 +2476,92 @@ function getStepTemplates(fiatAmount, currency) {
           </div>
         </div>
       </div>
-    </div>
 
-    <div class="step" id="kwespay-step5">
-      <div class="kp-topbar">
-        <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot" style="background:var(--kp-green);box-shadow:0 0 8px rgba(16,185,129,0.4);animation:none"></div>
-          <span class="kp-topbar-name">Payment Complete</span>
-        </div>
-        <div class="kp-topbar-secure">
-          <span class="material-symbols-outlined" style="color:var(--kp-green)">check_circle</span>
-          CONFIRMED
+      <!-- Sub-view: confirming (on-chain done, polling backend) -->
+      <div id="kwespay-view-confirming" class="loading-container" style="flex:1;display:none">
+        <div class="spinner-wrapper">
+          <div class="spinner-ring kp-spin-soft"></div>
+          <div class="spinner-ring-2 kp-spin-soft"></div>
+          <div class="spinner-icon kp-spinner-icon-green">
+            <span class="material-symbols-outlined" style="color:var(--kp-green)">cloud_sync</span>
+          </div>
         </div>
+        <h2 class="headline">Confirming Payment</h2>
+        <p class="body-text" id="kwespay-confirmingText">Waiting for network confirmation.</p>
       </div>
-      <div class="loading-container" style="flex:1">
-        <div class="success-icon">
-          <span class="material-symbols-outlined">check_circle</span>
+
+      <!-- Sub-view: success receipt -->
+      <div id="kwespay-view-success" style="display:none;flex-direction:column;flex:1;overflow:hidden">
+
+        <!-- Thin green confirmed bar -->
+        <div class="kp-confirmed-bar">
+          <span class="material-symbols-outlined" style="font-size:13px;color:var(--kp-green)">check_circle</span>
+          <span>Payment confirmed on-chain</span>
         </div>
-        <h2 class="headline">Payment Successful</h2>
-        <p class="body-text">Your transaction has been confirmed on-chain.</p>
-        <div class="tx-details">
-          <div class="tx-row">
-            <span class="tx-label">tx hash</span>
-            <div class="tx-hash-row">
-              <span class="tx-value" id="kwespay-txHash">—</span>
-              <a class="explorer-link" id="kwespay-explorerLink" target="_blank" rel="noopener noreferrer">
-                <span class="material-symbols-outlined">open_in_new</span>
-              </a>
-            </div>
-          </div>
-          <div class="tx-row">
-            <span class="tx-label">amount paid</span>
-            <span class="tx-value" id="kwespay-txFiatAmount">${fiatAmount} ${currency}</span>
+
+        <!-- Scrollable receipt body -->
+        <div class="loading-container" style="flex:1;padding-bottom:0;justify-content:flex-start;padding-top:20px;overflow-y:auto">
+          <div class="success-icon">
+            <span class="material-symbols-outlined">check_circle</span>
           </div>
-          <div class="tx-row">
-            <span class="tx-label">crypto amount</span>
-            <span class="tx-value" id="kwespay-txCryptoAmount">—</span>
+          <h2 class="headline">Payment Successful</h2>
+          <p class="body-text">Your transaction has been confirmed on-chain.</p>
+
+          <div class="tx-details">
+            <div class="tx-row">
+              <span class="tx-label">Tx hash</span>
+              <div class="tx-hash-row">
+                <span class="tx-value" id="kwespay-txHash">—</span>
+                <a class="explorer-link" id="kwespay-explorerLink" target="_blank" rel="noopener noreferrer">
+                  <span class="material-symbols-outlined">open_in_new</span>
+                </a>
+              </div>
+            </div>
+            <div class="tx-row">
+              <span class="tx-label">Reference</span>
+              <span class="tx-value" id="kwespay-txRef">—</span>
+            </div>
+            <div class="tx-row">
+              <span class="tx-label">Amount paid</span>
+              <span class="tx-value" id="kwespay-txFiatAmount">${fiatAmount} ${currency}</span>
+            </div>
+            <div class="tx-row">
+              <span class="tx-label">Crypto amount</span>
+              <span class="tx-value" id="kwespay-txCryptoAmount">—</span>
+            </div>
+            <div class="tx-row">
+              <span class="tx-label">Network</span>
+              <span class="tx-value" id="kwespay-txNetwork">—</span>
+            </div>
+            <div class="tx-row">
+              <span class="tx-label">Time</span>
+              <span class="tx-value" id="kwespay-txTime">—</span>
+            </div>
           </div>
-          <div class="tx-row">
-            <span class="tx-label">network</span>
-            <span class="tx-value" id="kwespay-txNetwork">—</span>
+        </div>
+
+        <!-- Countdown + Done button -->
+        <div class="bottom-action" style="padding-top:10px">
+          <!-- Countdown bar -->
+          <div class="kp-countdown-track">
+            <div class="kp-countdown-bar" id="kwespay-receiptCountdownBar"></div>
           </div>
+          <p class="kp-countdown-label" id="kwespay-receiptCountdown">Closing in 10s</p>
+          <button class="action-btn" id="kwespay-closeSuccessBtn" style="margin-top:8px">Done</button>
+        </div>
+
+        <div class="kp-footer">
+          <span class="material-symbols-outlined kp-footer-lock" style="font-size:12px">lock</span>
+          <span class="kp-footer-text">Secured by <span>KwesPay</span> &middot; On-chain verified</span>
         </div>
-      </div>
-      <div class="bottom-action">
-        <button class="action-btn" id="kwespay-closeSuccessBtn">Done</button>
-      </div>
-      <div class="kp-footer">
-        <span class="material-symbols-outlined kp-footer-lock" style="font-size:12px">lock</span>
-        <span class="kp-footer-text">Secured by <span>KwesPay</span> &middot; On-chain verified</span>
       </div>
     </div>
 
-    <div class="step" id="kwespay-step6">
+    <!-- Step 5: Error / Failed -->
+    <div class="step" id="kwespay-step5">
       <div class="kp-topbar">
         <div class="kp-topbar-brand">
-          <div class="kp-topbar-dot" style="background:var(--kp-red);box-shadow:none;animation:none"></div>
+          <div class="kp-topbar-dot" style="background:var(--kp-red);box-shadow:0 0 8px rgba(244,63,94,0.35);animation:none"></div>
           <span class="kp-topbar-name">Payment Failed</span>
         </div>
       </div>
@@ -2264,6 +2571,12 @@ function getStepTemplates(fiatAmount, currency) {
         </div>
         <h2 class="headline" id="kwespay-errorTitle">Something went wrong</h2>
         <p class="body-text" id="kwespay-errorMessage">An error occurred while processing your payment.</p>
+
+        <!-- Hint strip — gives context without overwhelming the user -->
+        <div class="kp-error-hint">
+          <span class="material-symbols-outlined" style="font-size:14px;color:var(--kp-muted)">info</span>
+          <span>Your funds have not been charged. You can retry safely.</span>
+        </div>
       </div>
       <div class="bottom-action">
         <button class="action-btn" id="kwespay-retryPayment">Try Again</button>
@@ -2310,27 +2623,29 @@ const DomMethods = {
     overlay.className = "kwespay-overlay";
     overlay.id = "kwespay-widget-overlay";
 
+    const container = document.createElement("div");
+    container.className = "kwespay-container";
+    container.id = "kwespay-widget-container";
+
     const closeBtn = document.createElement("button");
     closeBtn.className = "kwespay-close-btn";
     closeBtn.innerHTML = "×";
     closeBtn.onclick = () => this.close();
-    overlay.appendChild(closeBtn);
+    container.appendChild(closeBtn);
 
-    const container = document.createElement("div");
-    container.className = "kwespay-container";
-    container.id = "kwespay-widget-container";
-    container.innerHTML = getStepTemplates(
-      this.config.amount,
+    const stepsWrapper = document.createElement("div");
+    stepsWrapper.className = "kwespay-steps-wrapper";
+    stepsWrapper.innerHTML = getStepTemplates(
+      this._displayAmount,
       this.config.currency
     );
+    container.appendChild(stepsWrapper);
 
     overlay.appendChild(container);
     document.body.appendChild(overlay);
 
     this._setupEventListeners();
     this._setupSwipeToClose(container);
-
-    // Clicking outside the container does NOT close the widget (intentional)
   },
 
   _setupSwipeToClose(container) {
@@ -2501,8 +2816,11 @@ const NavMethods = {
       targetStep = document.getElementById(`kwespay-step-${stepNumber}`);
     else targetStep = document.getElementById(`kwespay-step${stepNumber}`);
 
-    if (targetStep) targetStep.classList.add("active");
-    else console.warn(`[KwesPayWidget] Step not found: ${stepNumber}`);
+    if (targetStep) {
+      targetStep.classList.add("active");
+    } else {
+      console.warn(`[KwesPayWidget] Step not found: ${stepNumber}`);
+    }
   },
 
   _removeCustomStep(id) {
@@ -2512,13 +2830,16 @@ const NavMethods = {
   _showError(title, message) {
     const titleEl = document.getElementById("kwespay-errorTitle");
     const msgEl = document.getElementById("kwespay-errorMessage");
-    if (titleEl) titleEl.textContent = title;
-    if (msgEl) msgEl.textContent = message;
-    this._goToStep(6);
+    if (titleEl) titleEl.textContent = title ?? "Something went wrong";
+    if (msgEl)
+      msgEl.textContent =
+        message ?? "An unexpected error occurred. Please try again.";
+    this._goToStep(5);
   },
 
   _reset() {
     this._clearQuoteTimer();
+    this._stopReceiptCountdown();
     this._removeCustomStep("kwespay-step-wallet-picker");
     this._removeCustomStep("kwespay-step-wc");
     this.state.selectedNetwork = null;
@@ -2586,23 +2907,13 @@ const NetworkMethods = {
       const listItem = document.createElement("div");
       listItem.className = "list-item";
       listItem.innerHTML = `
-        <div class="item-icon"><img src="${network.logo}" alt="${
-        network.name
-      }" /></div>
+        <div class="item-icon"><img src="${network.logo}" alt="${network.name}" /></div>
         <div class="item-info">
           <div class="item-name-row">
             <p class="item-name">${network.name}</p>
-            ${
-              network.type === "testnet"
-                ? '<span class="item-badge badge-testnet">Testnet</span>'
-                : ""
-            }
+            
           </div>
-          <p class="item-desc">${
-            network.type === "mainnet"
-              ? "Mainnet · Production"
-              : "Testnet · Development"
-          }</p>
+       
         </div>
         <span class="material-symbols-outlined item-chevron">chevron_right</span>
       `;
@@ -2741,7 +3052,7 @@ const WalletMethods = {
           <button class="kp-back-btn" id="kwespay-picker-back">
             <span class="material-symbols-outlined">arrow_back</span>
           </button>
-          <div class="kp-topbar-dot"></div>
+      
           <span class="kp-topbar-name">Connect Wallet</span>
         </div>
       </div>
@@ -2911,7 +3222,7 @@ const WalletMethods = {
           <button class="kp-back-btn" id="kwespay-wc-back">
             <span class="material-symbols-outlined">arrow_back</span>
           </button>
-          <div class="kp-topbar-dot"></div>
+      
           <span class="kp-topbar-name">Scan QR Code</span>
         </div>
       </div>
@@ -2951,7 +3262,7 @@ const WalletMethods = {
           <button class="kp-back-btn" id="kwespay-wc-back">
             <span class="material-symbols-outlined">arrow_back</span>
           </button>
-          <div class="kp-topbar-dot"></div>
+      
           <span class="kp-topbar-name">Connect Wallet</span>
         </div>
       </div>
@@ -3101,8 +3412,6 @@ const WalletMethods = {
   },
 };
 
-const PLATFORM_FEE_BPS = 25;
-
 function formatUnits(rawBigInt, decimals) {
   const divisor = BigInt(10 ** decimals);
   const whole = rawBigInt / divisor;
@@ -3130,6 +3439,31 @@ function formatUnits(rawBigInt, decimals) {
   return `0.${fracFull.slice(0, firstSig) + sigSlice}`;
 }
 
+function _validateQuoteDecimals(
+  amountBaseUnits,
+  fiatAmount,
+  decimals,
+  usdPrice
+) {
+  try {
+    if (!usdPrice || usdPrice <= 0) return { ok: true };
+    const humanAmount = Number(BigInt(amountBaseUnits)) / 10 ** decimals;
+    const impliedUsd = humanAmount * usdPrice;
+    const ratio = impliedUsd / fiatAmount;
+    if (ratio < 0.5 || ratio > 10) {
+      return {
+        ok: false,
+        reason: `Amount sanity check failed: got ${humanAmount} (≈$${impliedUsd.toFixed(
+          6
+        )}) for $${fiatAmount} fiat.`,
+      };
+    }
+    return { ok: true };
+  } catch {
+    return { ok: true };
+  }
+}
+
 const QuoteMethods = {
   async _loadReviewStep() {
     this._clearQuoteTimer();
@@ -3142,45 +3476,63 @@ const QuoteMethods = {
     const proceedBtn = document.getElementById("kwespay-proceedToPayment");
 
     if (cryptoLine) {
-      cryptoLine.textContent = "loading…";
+      cryptoLine.textContent = "loading...";
       cryptoLine.classList.add("loading");
     }
     if (timerEl) timerEl.style.display = "none";
     if (proceedBtn) proceedBtn.disabled = true;
 
     try {
-      const payload = await this.paymentService.getQuote({
-        vendorId: this.config.vendorId,
+      const quote = await this.paymentService.getQuote({
+        vendorIdentifier: this.config.vendorId,
         cryptoCurrency: this.state.selectedToken,
         fiatAmount: this.config.amount,
         fiatCurrency: this.config.currency,
         network: this.state.selectedNetwork,
-        payerWalletAddress: this.walletService.getAddress(),
       });
 
-      this.state.currentPayload = payload;
-
-      const decimals = this.state.selectedTokenConfig?.decimals ?? 6;
-      const amountBig = BigInt(payload.amountBaseUnits);
-      const feeNum = (Number(amountBig) * PLATFORM_FEE_BPS) / 10000;
-      const feeBig = BigInt(Math.max(1, Math.round(feeNum)));
-      const vendorBig = amountBig - feeBig;
+      const decimals = this.state.selectedTokenConfig?.decimals ?? 18;
       const sym = this.state.selectedToken;
-      const fmt = (n) => `${formatUnits(n, decimals)} ${sym}`;
+
+      const check = _validateQuoteDecimals(
+        quote.amountBaseUnits,
+        this.config.amount,
+        decimals,
+        quote.usdPriceSnapshot
+      );
+      if (!check.ok) {
+        console.error("[KwesPay] Quote sanity check failed:", check.reason);
+        throw new Error(
+          `Quote returned an implausible amount for ${sym}. Please contact support.`
+        );
+      }
+
+      this.state.currentPayload = {
+        ...quote,
+        vendorIdentifier: this.config.vendorId,
+        fiatAmount: this.config.amount,
+        fiatCurrency: this.config.currency,
+      };
+
+      const fmt = (n) =>
+        formatCryptoAmount(parseFloat(formatUnits(n, decimals)), sym);
+
+      const amountBig = BigInt(quote.amountBaseUnits);
+      const totalBig = BigInt(quote.totalBaseUnits);
+      const feeBig = totalBig - amountBig;
 
       if (cryptoLine) {
-        cryptoLine.textContent = fmt(amountBig);
+        cryptoLine.textContent = fmt(totalBig);
         cryptoLine.classList.remove("loading");
       }
-      if (feeAmount) feeAmount.textContent = fmt(amountBig);
+      if (feeAmount) feeAmount.textContent = fmt(totalBig);
       if (feePlatform) feePlatform.textContent = fmt(feeBig);
-      if (feeVendor)
-        feeVendor.textContent = fmt(vendorBig < 0n ? 0n : vendorBig);
+      if (feeVendor) feeVendor.textContent = fmt(amountBig);
       if (proceedBtn) proceedBtn.disabled = false;
 
-      this._startQuoteTimer(payload.expiresAt);
+      this._startQuoteTimer(quote.expiresAt);
     } catch (err) {
-      console.error("[KwesPayWidget] Quote fetch failed:", err.message);
+      console.error("[KwesPay] Quote fetch failed:", err.message);
       if (cryptoLine) {
         cryptoLine.textContent = "Could not load please try again.";
         cryptoLine.classList.remove("loading");
@@ -3200,7 +3552,8 @@ const QuoteMethods = {
       const secs = Math.ceil(remaining / 1000);
       const mins = Math.floor(secs / 60);
       const s = secs % 60;
-      timerText.textContent = `Price locks in ${mins}:${String(s).padStart(
+
+      timerText.textContent = `Quote expires in ${mins}:${String(s).padStart(
         2,
         "0"
       )}`;
@@ -3210,7 +3563,7 @@ const QuoteMethods = {
         (secs <= 0 ? " expired" : "");
 
       if (secs <= 0) {
-        timerText.textContent = "Refreshing your rate…";
+        timerText.textContent = "Refreshing your rate...";
         const proceedBtn = document.getElementById("kwespay-proceedToPayment");
         if (proceedBtn) proceedBtn.disabled = true;
         this._clearQuoteTimer();
@@ -3230,6 +3583,8 @@ const QuoteMethods = {
   },
 };
 
+const RECEIPT_DWELL_MS = 10_000;
+
 const PaymentMethods = {
   async _handlePaymentProcessing() {
     if (!this.state.currentPayload) {
@@ -3243,6 +3598,7 @@ const PaymentMethods = {
     try {
       this._clearQuoteTimer();
       this._goToStep(4);
+      this._setProcessingView("processing");
 
       const setStatus = (title, text) => {
         const titleEl = document.getElementById("kwespay-processingTitle");
@@ -3253,27 +3609,34 @@ const PaymentMethods = {
 
       const isWC = this.walletService.connectionType === "walletconnect";
       const isMobile = this.walletService.isMobile();
-      const strictMobile = isWC && isMobile; // mobile WC path — no network switching, no RPC shortcuts
+      const strictMobile = isWC && isMobile;
       const provider = this.walletService.getProvider();
       const targetChainId = this.state.selectedChainId;
 
-      if (!provider) throw new Error("No wallet provider");
-
+      if (!provider) {
+        throw Object.assign(
+          new Error(
+            "No wallet provider available. Please reconnect your wallet."
+          ),
+          {
+            code: "NO_PROVIDER",
+          }
+        );
+      }
 
-      const alive = await this.walletService.isSessionAlive();
+      const alive = await this.walletService
+        .isSessionAlive()
+        .catch(() => false);
       if (!alive) {
-        console.error(
-          "[KwesPay] Session liveness check failed — session appears stale"
-        );
-        await this.walletService.disconnect();
-        const err = new Error(
-          "Your wallet session expired. Please reconnect your wallet."
+        await this.walletService.disconnect().catch(() => {});
+        throw Object.assign(
+          new Error(
+            "Your wallet session expired. Please reconnect your wallet."
+          ),
+          { code: "SESSION_EXPIRED" }
         );
-        err.code = "SESSION_EXPIRED";
-        throw err;
       }
 
-     
       if (isMobile) {
         document
           .getElementById("kwespay-mobileTransactionInstruction")
@@ -3281,17 +3644,20 @@ const PaymentMethods = {
       }
 
       if (strictMobile) {
-
         await this._assertMobileChain(provider, targetChainId);
       } else {
-        const rawChain = await provider.request({ method: "eth_chainId" });
+        let rawChain;
+        try {
+          rawChain = await provider.request({ method: "eth_chainId" });
+        } catch {
+          throw Object.assign(
+            new Error(
+              "Could not read the current network from your wallet. Please try again."
+            ),
+            { code: "NETWORK_ERROR" }
+          );
+        }
         const currentChainId = parseInt(rawChain, 16);
-
-        console.log("[KwesPay] Desktop chain check —", {
-          currentChainId,
-          targetChainId,
-        });
-
         if (currentChainId !== targetChainId) {
           setStatus(
             "Switching network…",
@@ -3304,11 +3670,9 @@ const PaymentMethods = {
             this.state.selectedToken,
             this.state.selectedTokenConfig.decimals
           );
-          console.log("[KwesPay] Network switched");
         }
       }
 
-   
       if (strictMobile) {
         setStatus(
           "Opening your wallet…",
@@ -3323,56 +3687,111 @@ const PaymentMethods = {
         );
       }
 
-      const receipt = await this.paymentService.createPayment({
-        payload: this.state.currentPayload,
-        walletProvider: provider,
-        onStatusUpdate: setStatus,
-      });
+      let receipt;
+      try {
+        receipt = await this.paymentService.createPayment({
+          payload: this.state.currentPayload,
+          walletProvider: provider,
+          onStatusUpdate: setStatus,
+        });
+      } catch (payErr) {
+        const msg =
+          payErr?.message ?? "Payment submission failed. Please try again.";
+        throw Object.assign(new Error(msg), {
+          code: payErr?.code ?? "CONTRACT_ERROR",
+          original: payErr,
+        });
+      }
+
+      if (!receipt?.hash) {
+        throw Object.assign(
+          new Error(
+            "Transaction was submitted but no hash was returned. Check your wallet for status."
+          ),
+          { code: "MISSING_HASH" }
+        );
+      }
 
-  
       document
         .getElementById("kwespay-mobileTransactionInstruction")
         ?.style.setProperty("display", "none");
 
-     
-      const decimals = this.state.selectedTokenConfig?.decimals ?? 6;
-      const amountBig = BigInt(this.state.currentPayload.amountBaseUnits);
-      const cryptoDisplay = `${formatUnits(amountBig, decimals)} ${
-        this.state.selectedToken
-      }`;
+      this._setProcessingView("confirming");
 
-      document.getElementById("kwespay-txHash").textContent = truncateHash(
-        receipt.hash
-      );
-      document.getElementById(
-        "kwespay-txFiatAmount"
-      ).textContent = `${this.config.amount} ${this.config.currency}`;
-      document.getElementById("kwespay-txCryptoAmount").textContent =
-        cryptoDisplay;
-      document.getElementById("kwespay-txNetwork").textContent =
-        this.state.selectedNetworkName;
-      document.getElementById("kwespay-explorerLink").href =
-        NETWORK_CONFIGS[this.state.selectedNetwork].explorer + receipt.hash;
-
-      this._goToStep(5);
-
-      dispatchWidgetEvent("paymentSuccess", {
+      const onChainPayload = {
         transactionReference: receipt.transactionReference,
         paymentIdBytes32: receipt.paymentIdBytes32,
         transactionHash: receipt.hash,
+        transactionStatus: "pending",
         fiatAmount: this.config.amount,
         currency: this.config.currency,
         token: this.state.selectedToken,
         network: this.state.selectedNetwork,
+      };
+
+      dispatchWidgetEvent("paymentSuccess", onChainPayload);
+      this.config.onPaymentSuccess?.(onChainPayload);
+
+      const confirmed = await this._awaitBackendConfirmation(receipt);
+
+      const decimals = this.state.selectedTokenConfig?.decimals ?? 18;
+      const sym = this.state.selectedToken;
+      const payload = this.state.currentPayload;
+      const totalBig = BigInt(payload.totalBaseUnits);
+      const cryptoDisplay = formatCryptoAmount(
+        parseFloat(formatUnits(totalBig, decimals)),
+        sym
+      );
+      const now = new Date();
+      const timeString = now.toLocaleTimeString([], {
+        hour: "2-digit",
+        minute: "2-digit",
       });
-    } catch (error) {
-      console.error(
-        "[KwesPay] Payment error —",
-        error.code ?? "UNKNOWN",
-        ":",
-        error.message
+      const dateString = now.toLocaleDateString([], {
+        month: "short",
+        day: "numeric",
+        year: "numeric",
+      });
+
+      const setEl = (id, val) => {
+        const el = document.getElementById(id);
+        if (el) el.textContent = val;
+      };
+
+      setEl("kwespay-txHash", truncateHash(receipt.hash));
+      setEl(
+        "kwespay-txFiatAmount",
+        `${this.config.amount} ${this.config.currency}`
       );
+      setEl("kwespay-txCryptoAmount", cryptoDisplay);
+      setEl("kwespay-txNetwork", this.state.selectedNetworkName);
+      setEl("kwespay-txRef", receipt.transactionReference ?? "—");
+      setEl("kwespay-txTime", `${dateString} · ${timeString}`);
+
+      const explorerLink = document.getElementById("kwespay-explorerLink");
+      if (explorerLink) {
+        explorerLink.href =
+          (NETWORK_CONFIGS[this.state.selectedNetwork]?.explorer ?? "") +
+          receipt.txHash;
+      }
+
+      this._setProcessingView("success");
+      this._startReceiptCountdown(RECEIPT_DWELL_MS);
+
+      const finalStatus = confirmed?.transactionStatus ?? "completed";
+      const finalPayload = {
+        transactionReference: receipt.transactionReference,
+        paymentIdBytes32: receipt.paymentIdBytes32,
+        transactionHash: receipt.hash,
+        transactionStatus: finalStatus,
+        fiatAmount: this.config.amount,
+        currency: this.config.currency,
+        token: this.state.selectedToken,
+        network: this.state.selectedNetwork,
+      };
 
+      this._finalisePayment(finalPayload, false);
+    } catch (error) {
       document
         .getElementById("kwespay-mobileTransactionInstruction")
         ?.style.setProperty("display", "none");
@@ -3381,71 +3800,171 @@ const PaymentMethods = {
       let title = "Payment Failed";
       let message = getErrorMessage(error, { token: this.state.selectedToken });
 
-      if (error.code === "SESSION_EXPIRED") {
-        title = "Session Expired";
-        message = error.message;
-      } else if (error.code === "WRONG_NETWORK") {
-        title = "Wrong Network";
-        message = error.message;
-      } else if (errorType === "USER_REJECTED") {
-        title = "Transaction Cancelled";
-        message = "You rejected the transaction in your wallet.";
-      } else if (errorType === "INSUFFICIENT_BALANCE") {
-        title = "Insufficient Balance";
+      switch (error.code) {
+        case "SESSION_EXPIRED":
+          title = "Session Expired";
+          message = error.message;
+          break;
+        case "NO_PROVIDER":
+          title = "Wallet Disconnected";
+          message = error.message;
+          break;
+        case "NETWORK_ERROR":
+          title = "Network Error";
+          message = error.message;
+          break;
+        case "WRONG_NETWORK":
+          title = "Wrong Network";
+          message = error.message;
+          break;
+        case "MISSING_HASH":
+          title = "Unknown Transaction Status";
+          message = error.message;
+          break;
+        default:
+          if (errorType === "USER_REJECTED") {
+            title = "Transaction Cancelled";
+            message = "You rejected the transaction in your wallet.";
+          } else if (errorType === "INSUFFICIENT_BALANCE") {
+            title = "Insufficient Balance";
+          } else if (!message) {
+            message =
+              "An unexpected error occurred. Please try again or contact support.";
+          }
       }
 
+      console.error("[KwesPayWidget] Payment error:", {
+        title,
+        message,
+        code: error.code,
+        error,
+      });
+
       this._showError(title, message);
-      dispatchWidgetEvent("paymentError", { error: message, errorType });
+      this._failPayment(message, errorType);
     }
   },
 
-  /**
-   * Confirm the wallet is on the target chain before sending a transaction.
-   * Retries up to 3 times with 1s delay to handle WC relay propagation lag.
-   * Throws WRONG_NETWORK if the chain never matches.
-   *
-   * MOBILE WC ONLY — never call this on desktop/injected.
-   */
+  _setProcessingView(view) {
+    ["processing", "confirming", "success"].forEach((v) => {
+      const el = document.getElementById(`kwespay-view-${v}`);
+      if (!el) return;
+      el.style.display = v === view ? (v === "success" ? "flex" : "") : "none";
+    });
+
+    const dot = document.getElementById("kwespay-step4-dot");
+    const title = document.getElementById("kwespay-step4-title");
+    const secure = document.getElementById("kwespay-step4-secure");
+
+    if (view === "success") {
+      if (dot) {
+        dot.style.background = "var(--kp-green)";
+        dot.style.boxShadow = "0 0 8px rgba(16,185,129,0.4)";
+        dot.style.animation = "none";
+      }
+      if (title) title.textContent = "Payment Complete";
+      if (secure) secure.style.display = "flex";
+    } else {
+      if (dot) {
+        dot.style.background = "var(--kp-accent)";
+        dot.style.boxShadow = "0 0 8px var(--kp-accent-glow)";
+        dot.style.animation = "";
+      }
+      if (title) title.textContent = "KwesPay Checkout";
+      if (secure) secure.style.display = "none";
+    }
+  },
+
+  _startReceiptCountdown(totalMs) {
+    this._stopReceiptCountdown();
+
+    const totalSec = Math.round(totalMs / 1000);
+    let remaining = totalSec;
+
+    const countdownEl = document.getElementById("kwespay-receiptCountdown");
+    const barEl = document.getElementById("kwespay-receiptCountdownBar");
+
+    const update = () => {
+      if (countdownEl) {
+        countdownEl.textContent =
+          remaining > 0 ? `Closing in ${remaining}s` : "Closing…";
+      }
+      if (barEl) {
+        const pct = (remaining / totalSec) * 100;
+        barEl.style.width = `${pct}%`;
+        barEl.style.background =
+          remaining <= 3 ? "var(--kp-green)" : "var(--kp-accent)";
+      }
+    };
+
+    update();
+
+    this._receiptCountdownInterval = setInterval(() => {
+      remaining -= 1;
+      update();
+      if (remaining <= 0) {
+        this._stopReceiptCountdown();
+        this.close();
+      }
+    }, 1000);
+  },
+
+  _stopReceiptCountdown() {
+    if (this._receiptCountdownInterval) {
+      clearInterval(this._receiptCountdownInterval);
+      this._receiptCountdownInterval = null;
+    }
+  },
+
+  _awaitBackendConfirmation(receipt) {
+    return this.paymentService
+      .pollTransactionStatus(receipt.transactionReference, {
+        intervalMs: 4000,
+        maxAttempts: 15,
+        onStatus: (status) => {
+          const el = document.getElementById("kwespay-confirmingText");
+          if (el) el.textContent = `Network status: ${status}…`;
+        },
+      })
+      .catch((err) => {
+        dispatchWidgetEvent("paymentUnconfirmed", {
+          transactionReference: receipt.transactionReference,
+          transactionHash: receipt.hash,
+          reason: err.message,
+        });
+        this.config.onPaymentUnconfirmed?.({
+          transactionReference: receipt.transactionReference,
+          transactionHash: receipt.hash,
+          reason: err.message,
+        });
+        return { transactionStatus: "unconfirmed" };
+      });
+  },
+
   async _assertMobileChain(provider, targetChainId) {
     const MAX_ATTEMPTS = 3;
     const DELAY_MS = 1000;
 
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
       let currentChainId = null;
-
       try {
         const raw = await provider.request({ method: "eth_chainId" });
         currentChainId = parseInt(raw, 16);
-      } catch (err) {
-        console.error(
-          `[KwesPay] eth_chainId RPC failed (attempt ${attempt}/${MAX_ATTEMPTS}):`,
-          err.message
-        );
-      }
-
-      console.log(
-        `[KwesPay] Chain check attempt ${attempt}/${MAX_ATTEMPTS} —`,
-        { currentChainId, targetChainId }
-      );
-
-      if (currentChainId === targetChainId) {
-        console.log("[KwesPay] Chain confirmed ✅", currentChainId);
-        return;
-      }
+      } catch {}
 
-      if (attempt < MAX_ATTEMPTS) {
+      if (currentChainId === targetChainId) return;
+      if (attempt < MAX_ATTEMPTS)
         await new Promise((r) => setTimeout(r, DELAY_MS));
-      }
     }
 
-    const err = new Error(
-      `Please switch to ${this.state.selectedNetworkName} in your wallet and try again.`
+    throw Object.assign(
+      new Error(
+        `Please switch to ${this.state.selectedNetworkName} in your wallet and try again.`
+      ),
+      { code: "WRONG_NETWORK" }
     );
-    err.code = "WRONG_NETWORK";
-    throw err;
   },
 
-
   async _switchNetworkSafe(
     chainId,
     networkName,
@@ -3453,9 +3972,7 @@ const PaymentMethods = {
     tokenSymbol,
     tokenDecimals
   ) {
-    const switchNetwork = this.walletService.switchNetwork;
     const provider = this.walletService.getProvider();
-
     if (!provider) throw new Error("[WalletService] No provider connected");
 
     const toHex = (val) => {
@@ -3480,15 +3997,10 @@ const PaymentMethods = {
         await provider.request({ method: "eth_chainId" })
       );
       if (currentHex && currentHex === targetHex) return;
-    } catch (err) {
-      console.warn(
-        "[KwesPay] Could not read chainId before switch:",
-        err.message
-      );
-    }
+    } catch {}
 
     try {
-      await switchNetwork(
+      await this.walletService.switchNetwork(
         chainId,
         networkName,
         rpcUrl,
@@ -3496,15 +4008,9 @@ const PaymentMethods = {
         tokenDecimals
       );
     } catch (err) {
-      if (err.code === 4001) throw err; // user rejected
-      // Some wallets throw even on success — continue to verify below
-      console.warn(
-        "[KwesPay] switchNetwork threw (verifying anyway):",
-        err.message
-      );
+      if (err.code === 4001) throw err;
     }
 
-    // Poll until confirmed or 15s timeout
     const POLL_MS = 500;
     const TIMEOUT_MS = 15_000;
     const started = Date.now();
@@ -3515,17 +4021,8 @@ const PaymentMethods = {
         const currentHex = toHex(
           await provider.request({ method: "eth_chainId" })
         );
-        if (currentHex && currentHex === targetHex) {
-          console.log(
-            `[KwesPay] Network switch confirmed after ${
-              Date.now() - started
-            }ms ✅`
-          );
-          return;
-        }
-      } catch (err) {
-        console.warn("[KwesPay] Poll eth_chainId error:", err.message);
-      }
+        if (currentHex && currentHex === targetHex) return;
+      } catch {}
     }
 
     throw new Error(
@@ -3543,6 +4040,14 @@ function resolveAcceptedTokens(input) {
   return null;
 }
 
+function formatFiatDisplay(amount) {
+  const num = parseFloat(amount);
+  if (isNaN(num)) return "0.00";
+  return num % 1 === 0
+    ? num.toString()
+    : parseFloat(num.toPrecision(10)).toString();
+}
+
 class KwesPayWidget {
   constructor(config) {
     if (!config.apiKey) throw new Error("[KwesPayWidget] apiKey is required");
@@ -3558,6 +4063,10 @@ class KwesPayWidget {
       currency: config.currency || DEFAULT_CONFIG.currency,
       graphqlEndpoint: DEFAULT_CONFIG.graphqlEndpoint,
       acceptedTokens: resolveAcceptedTokens(config.acceptedTokens),
+      onPaymentSuccess: config.onPaymentSuccess ?? null,
+      onPaymentConfirmed: config.onPaymentConfirmed ?? null,
+      onPaymentUnconfirmed: config.onPaymentUnconfirmed ?? null,
+      onPaymentError: config.onPaymentError ?? null,
     };
 
     if (!Object.values(SUPPORTED_CURRENCIES).includes(this.config.currency)) {
@@ -3590,21 +4099,61 @@ class KwesPayWidget {
       wcUri: null,
     };
 
+    this._paymentResolve = null;
+    this._paymentReject = null;
+    this._finalised = false;
+    this._receiptCountdownInterval = null;
+
     this._init();
   }
 
-  async open() {
+  get _displayAmount() {
+    return formatFiatDisplay(this.config.amount);
+  }
+
+  open() {
+    this._finalised = false;
+    this._paymentPromise = new Promise((resolve, reject) => {
+      this._paymentResolve = resolve;
+      this._paymentReject = reject;
+    });
+
     const overlay = document.getElementById("kwespay-widget-overlay");
     const container = document.getElementById("kwespay-widget-container");
-    if (!overlay || !container) return;
-
-    container.classList.remove("closing");
-    overlay.classList.add("open");
-    document.body.classList.add("kwespay-open");
-    this.state.isOpen = true;
+    if (overlay && container) {
+      container.classList.remove("closing");
+      overlay.classList.add("open");
+      document.body.classList.add("kwespay-open");
+      this.state.isOpen = true;
+    }
 
-    await this._validateAPIKey();
+    this._validateAPIKey();
     dispatchWidgetEvent("widgetOpened", {});
+
+    return this._paymentPromise;
+  }
+
+  _finalisePayment(payload, autoClose = true) {
+    if (this._finalised) return;
+    this._finalised = true;
+
+    dispatchWidgetEvent("paymentConfirmed", payload);
+    this.config.onPaymentConfirmed?.(payload);
+
+    this._paymentResolve?.(payload);
+
+    if (autoClose) {
+      this.close();
+    }
+  }
+
+  _failPayment(message, errorType) {
+    const errorPayload = { error: message, errorType };
+    dispatchWidgetEvent("paymentError", errorPayload);
+    this.config.onPaymentError?.(errorPayload);
+
+    const err = Object.assign(new Error(message), { code: errorType });
+    this._paymentReject?.(err);
   }
 
   close() {
@@ -3612,28 +4161,29 @@ class KwesPayWidget {
     const container = document.getElementById("kwespay-widget-container");
     if (!overlay || !container) return;
 
+    this._stopReceiptCountdown();
     this._clearQuoteTimer();
-    const closedAfterSuccess = this.state.currentStep === 5;
+
+    const closedAfterSuccess = this.state.currentStep === 4;
     const mobile = window.innerWidth <= 480;
 
-    if (mobile) {
-      container.classList.add("closing");
-      setTimeout(() => {
-        container.classList.remove("closing");
-        overlay.classList.remove("open");
-        document.body.classList.remove("kwespay-open");
-        this.state.isOpen = false;
-        dispatchWidgetEvent("widgetClosed", {
-          completedPayment: closedAfterSuccess,
-        });
-      }, 300);
-    } else {
+    const finish = () => {
       overlay.classList.remove("open");
       document.body.classList.remove("kwespay-open");
       this.state.isOpen = false;
       dispatchWidgetEvent("widgetClosed", {
         completedPayment: closedAfterSuccess,
       });
+    };
+
+    if (mobile) {
+      container.classList.add("closing");
+      setTimeout(() => {
+        container.classList.remove("closing");
+        finish();
+      }, 300);
+    } else {
+      finish();
     }
   }
 
@@ -3651,12 +4201,13 @@ class KwesPayWidget {
     ) {
       this.config.currency = newCurrency;
     }
+    const display = `${this._displayAmount} ${this.config.currency}`;
     document
       .querySelectorAll(
         '[id*="paymentAmount"], [id*="summaryFiatAmount"], [id*="txFiatAmount"], [id*="reviewFiatAmount"]'
       )
       .forEach((el) => {
-        el.textContent = `${this.config.amount} ${this.config.currency}`;
+        el.textContent = display;
       });
     dispatchWidgetEvent("amountUpdated", {
       amount: this.config.amount,
@@ -3669,11 +4220,21 @@ class KwesPayWidget {
   }
 
   destroy() {
+    this._stopReceiptCountdown();
     this._clearQuoteTimer();
     document.body.classList.remove("kwespay-open");
     this.walletService?.disconnect();
     document.getElementById("kwespay-widget-overlay")?.remove();
     document.getElementById("kwespay-widget-styles")?.remove();
+
+    if (!this._finalised) {
+      this._paymentReject?.(
+        Object.assign(new Error("Widget destroyed"), {
+          code: "WIDGET_DESTROYED",
+        })
+      );
+    }
+
     this.state = null;
     this.config = null;
     this.walletService = null;
@@ -3693,9 +4254,103 @@ Object.assign(
   PaymentMethods
 );
 
+// Keyed by `${apiKey}::${vendorId}` so a page with multiple vendors/keys
+// each get their own widget instance, but a single vendor reuses one.
+
+const _instances = new Map();
+
+function _cacheKey(apiKey, vendorId) {
+  return `${apiKey}::${vendorId}`;
+}
+
+// kwespay()
+
+/**
+ * Open the KwesPay checkout widget and await the result.
+ *
+ * Handles the full lifecycle — construction, caching, amount updates,
+ * open, and cleanup — so callers need nothing else.
+ *
+ * @param {object} config
+ * @param {string}   config.apiKey           Your KwesPay public API key.
+ * @param {string}   config.vendorId         Your vendor / merchant UUID.
+ * @param {number}   config.amount           Fiat amount to charge (e.g. 49.99).
+ * @param {string}  [config.currency]        ISO currency code (default: "USD").
+ * @param {string[] | "stablecoins"} [config.acceptedTokens]
+ *                                           Restrict accepted crypto tokens.
+ *
+ * @returns {Promise<PaymentResult>}
+ *   Resolves when the payment is confirmed on-chain.
+ *   Rejects with an Error whose `.code` is one of:
+ *     "USER_CANCELLED"   — user closed the widget without paying
+ *     "USER_REJECTED"    — user rejected the wallet transaction
+ *     "SESSION_EXPIRED"  — wallet session timed out mid-payment
+ *     "WIDGET_DESTROYED" — widget.destroy() was called externally
+ *     "UNKNOWN"          — unexpected error (check err.message)
+ *
+ * @example
+ * // Minimal usage — everything else is handled internally
+ * try {
+ *   const result = await kwespay({
+ *     apiKey:   "pk_...",
+ *     vendorId: "uuid",
+ *     amount:   total,
+ *     currency: "USD",
+ *   });
+ *   console.log("Paid:", result.transactionHash);
+ * } catch (err) {
+ *   if (err.code !== "USER_CANCELLED") console.error(err);
+ * }
+ */
+async function kwespay(config) {
+  const { apiKey, vendorId, amount, currency, acceptedTokens } = config;
+
+  if (!apiKey) throw new Error("[kwespay] apiKey is required");
+  if (!vendorId) throw new Error("[kwespay] vendorId is required");
+  if (!amount || parseFloat(amount) <= 0)
+    throw new Error("[kwespay] A valid amount is required");
+
+  const key = _cacheKey(apiKey, vendorId);
+
+  // Reuse existing instance or create a fresh one
+  let widget = _instances.get(key);
+
+  if (!widget) {
+    widget = new KwesPayWidget({
+      apiKey,
+      vendorId,
+      amount,
+      currency,
+      acceptedTokens,
+    });
+    _instances.set(key, widget);
+  } else {
+    // Sync amount/currency in case they changed since last call
+    widget.updateAmount(amount, currency);
+  }
+
+  try {
+    // open() returns a Promise that resolves/rejects when the payment settles.
+    const result = await widget.open();
+    return result;
+  } finally {
+    // Always evict after a settled payment or cancellation so the next call
+    // starts fresh (new quote, clean state). The DOM is cleaned up by close(),
+    // which open() calls internally on success; we just clear our cache ref.
+    _instances.delete(key);
+  }
+}
+
 /**
- * KwesPay Widget - Main entry point
- * @module @kwespay/widget
+ * @typedef {object} PaymentResult
+ * @property {string} transactionHash       On-chain tx hash.
+ * @property {string} transactionReference  KwesPay internal payment reference.
+ * @property {string} paymentIdBytes32      On-chain payment ID (bytes32).
+ * @property {string} transactionStatus     "completed" | "unconfirmed"
+ * @property {number} fiatAmount            Charged fiat amount.
+ * @property {string} currency              ISO currency code.
+ * @property {string} token                 Crypto token used (e.g. "USDC").
+ * @property {string} network               Chain used (e.g. "polygon").
  */
 
-export { KwesPayWidget as default };
+export { KwesPayWidget, KwesPayWidget as default, kwespay };