payment-kit 1.24.4 → 1.25.0

package/api/src/libs/session.ts

@@ -1,6 +1,7 @@
+/* eslint-disable no-nested-ternary */
 import { env } from '@blocklet/sdk/lib/config';
 import type { TransactionInput } from '@ocap/client';
-import { BN, fromTokenToUnit } from '@ocap/util';
+import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
 import cloneDeep from 'lodash/cloneDeep';
 import isEqual from 'lodash/isEqual';
 import pAll from 'p-all';
@@ -15,10 +16,10 @@ import {
   Invoice,
   PaymentCurrency,
   PaymentMethod,
+  PriceQuote,
   SetupIntent,
   Subscription,
   SubscriptionItem,
-  TPriceExpanded,
   type CheckoutSession,
   type TLineItemExpanded,
   type TPaymentCurrency,
@@ -26,10 +27,21 @@ import {
 } from '../store/models';
 import { Price, Price as TPrice } from '../store/models/price';
 import type { Product } from '../store/models/product';
-import type { PaymentBeneficiary, PriceRecurring, SubscriptionBillingThresholds } from '../store/models/types';
+import type {
+  ChainType,
+  PaymentBeneficiary,
+  PriceRecurring,
+  SubscriptionBillingThresholds,
+} from '../store/models/types';
 import { wallet } from './auth';
 import logger from './logger';
 import { applyDiscountsToLineItems } from './discount/discount';
+import { getQuoteService, QuoteResponse } from './quote-service';
+import { getExchangeRateService } from './exchange-rate';
+import { getExchangeRateSymbol } from './exchange-rate/token-address-mapping';
+import { trimDecimals } from './math-utils';
+import { normalizeSlippageConfigFromMetadata } from './slippage';
+import { getSubscriptionItemPrice } from './credit-utils';
 
 export function getStatementDescriptor(items: any[]) {
   for (const item of items) {
@@ -102,34 +114,70 @@ export async function getCheckoutAmount(
     }
   }
 
-  const subtotal = processedItems
-    .reduce((acc, x) => {
-      if (x.custom_amount) {
-        return acc.add(new BN(x.custom_amount));
-      }
+  // Use async reduce to support quote_id fallback
+  const subtotal = await processedItems
+    .reduce(
+      async (accPromise, x) => {
+        const acc = await accPromise;
 
-      const price = x.upsell_price || x.price;
-      const unitPrice = getPriceUintAmountByCurrency(price, currencyId);
-      if (price.custom_unit_amount) {
-        if (unitPrice) {
-          return acc.add(new BN(unitPrice).mul(new BN(x.quantity)));
+        // Priority 1: Use custom_amount if available
+        if (x.custom_amount) {
+          return acc.add(new BN(x.custom_amount));
+        }
+
+        // Priority 2: If has quote_id but no custom_amount, fetch from Quote table
+        if ((x as any).quote_id) {
+          try {
+            const quote = await PriceQuote.findByPk((x as any).quote_id);
+            if (quote) {
+              logger.info('Using quoted_amount from quote_id for checkout amount calculation', {
+                priceId: x.price.id,
+                quoteId: (x as any).quote_id,
+                quotedAmount: quote.quoted_amount,
+              });
+              return acc.add(new BN(quote.quoted_amount));
+            }
+
+            // Quote not found - log warning and fall through to price calculation
+            logger.warn('Quote not found for quote_id in line_item', {
+              priceId: x.price.id,
+              quoteId: (x as any).quote_id,
+            });
+          } catch (error) {
+            logger.error('Failed to fetch quote for quote_id', {
+              priceId: x.price.id,
+              quoteId: (x as any).quote_id,
+              error: (error as Error).message,
+            });
+          }
         }
-      }
 
-      if (price?.type === 'recurring') {
-        renew = renew.add(new BN(unitPrice).mul(new BN(x.quantity)));
+        // Priority 3: Calculate from price (fixed pricing or quote query failed)
+        const price = x.upsell_price || x.price;
+        const unitPrice = getPriceUintAmountByCurrency(price, currencyId);
 
-        if (trialing) {
-          return acc;
+        if (price.custom_unit_amount) {
+          if (unitPrice) {
+            return acc.add(new BN(unitPrice).mul(new BN(x.quantity)));
+          }
         }
-        if (price?.recurring?.usage_type === 'metered') {
-          return acc;
+
+        if (price?.type === 'recurring') {
+          renew = renew.add(new BN(unitPrice).mul(new BN(x.quantity)));
+
+          if (trialing) {
+            return acc;
+          }
+          if (price?.recurring?.usage_type === 'metered') {
+            return acc;
+          }
         }
-      }
 
-      return acc.add(new BN(unitPrice).mul(new BN(x.quantity)));
-    }, new BN(0))
-    .toString();
+        return acc.add(new BN(unitPrice).mul(new BN(x.quantity)));
+      },
+      Promise.resolve(new BN(0))
+    )
+    .then((bn) => bn.toString());
 
   // Calculate total discount amount from processed line items
   let totalDiscountAmount = new BN(0);
@@ -220,7 +268,11 @@ export function getSupportedPaymentMethods(
 
 export function getSupportedPaymentCurrencies(items: TLineItemExpanded[]) {
   const currencies = items.reduce((acc: string[], x: any) => {
-    return acc.concat(getPriceCurrencyOptions(x.price).map((c: any) => c.currency_id));
+    const price = x.upsell_price || x.price;
+    if (!price) {
+      return acc;
+    }
+    return acc.concat(getPriceCurrencyOptions(price).map((c: any) => c.currency_id));
   }, []);
   return Array.from(new Set(currencies));
 }
@@ -462,21 +514,89 @@ export function formatSubscriptionProduct(items: TLineItemExpanded[], maxLength
   return names.length > maxLength ? `${names.slice(0, maxLength).join(', ')} ...` : names.join(', ');
 }
 
+/**
+ * Slippage configuration for subscription authorization calculation
+ */
+export type SlippageOptions = {
+  /** Slippage percentage (e.g., 0.5 for 0.5%, 5 for 5%). Used when minAcceptableRate is not provided. */
+  percent?: number;
+  /** Minimum acceptable exchange rate (USD per token). When provided, used for precise authorization calculation. */
+  minAcceptableRate?: string;
+  /** Token decimal places. Required when minAcceptableRate is provided. */
+  currencyDecimal?: number;
+};
+
+const DEFAULT_SLIPPAGE_PERCENT = 0.5;
+const USD_DECIMALS = 8;
+
 /**
  * Setup subscription creation parameters
+ * @param items - Line items for the subscription
+ * @param currencyId - Payment currency ID
+ * @param trialInDays - Trial period in days (optional)
+ * @param trialEnd - Trial end timestamp (optional)
+ * @param slippageOptions - Slippage configuration for dynamic pricing authorization
  */
 export function getSubscriptionCreateSetup(
   items: TLineItemExpanded[],
   currencyId: string,
   trialInDays = 0,
-  trialEnd = 0
+  trialEnd = 0,
+  slippageOptions?: SlippageOptions | number
 ) {
+  // Normalize slippage options (support legacy number parameter for backward compatibility)
+  const options: SlippageOptions =
+    typeof slippageOptions === 'number'
+      ? { percent: slippageOptions }
+      : slippageOptions || { percent: DEFAULT_SLIPPAGE_PERCENT };
+
   let setup = new BN(0);
+  let hasDynamicPricing = false;
+  let totalBaseAmountBN = new BN(0); // Track total USD base amount for dynamic pricing items
+
+  // Debug log to verify items have correct upsell_price
+  logger.debug('getSubscriptionCreateSetup: items check', {
+    itemCount: items.length,
+    items: items.map((x) => ({
+      price_id: x.price?.id,
+      upsell_price_id: x.upsell_price?.id,
+      has_upsell: !!x.upsell_price,
+      selected_price_id: getSubscriptionItemPrice(x)?.id,
+      price_base_amount: x.price?.base_amount,
+      upsell_base_amount: x.upsell_price?.base_amount,
+    })),
+  });
 
   items.forEach((x) => {
-    const price = x.upsell_price || x.price;
-    const unit = getPriceUintAmountByCurrency(price, currencyId);
-    const amount = new BN(unit).mul(new BN(x.quantity));
+    const price = getSubscriptionItemPrice(x);
+
+    // Priority: use custom_amount if available (for dynamic pricing with pre-calculated amount)
+    // This allows callers to pass in the actual quoted amount from Quote system
+    let amount: BN;
+    if ((x as any).custom_amount) {
+      amount = new BN((x as any).custom_amount);
+    } else {
+      const unit = getPriceUintAmountByCurrency(price, currencyId);
+      amount = new BN(unit).mul(new BN(x.quantity));
+    }
+
+    // Check if this price uses dynamic pricing
+    if (price.pricing_type === 'dynamic') {
+      hasDynamicPricing = true;
+      // Accumulate base amount for dynamic pricing items (stored in 10^8 scale)
+      if (price.base_amount) {
+        const itemBaseAmount = fromTokenToUnit(price.base_amount, USD_DECIMALS);
+        const contribution = itemBaseAmount.mul(new BN(x.quantity));
+        totalBaseAmountBN = totalBaseAmountBN.add(contribution);
+        logger.debug('getSubscriptionCreateSetup: processing dynamic pricing item', {
+          priceId: price.id,
+          baseAmount: price.base_amount,
+          quantity: x.quantity,
+          contributionUSD: fromUnitToToken(contribution.toString(), USD_DECIMALS),
+        });
+      }
+    }
+
     if (price.type === 'recurring') {
       if (price.recurring?.usage_type === 'licensed') {
         setup = setup.add(amount);
@@ -487,9 +607,54 @@ export function getSubscriptionCreateSetup(
     }
   });
 
+  // Apply slippage protection for subscriptions with dynamic pricing
+  if (hasDynamicPricing && setup.gt(new BN(0))) {
+    const { percent, minAcceptableRate, currencyDecimal } = options;
+
+    // Priority: minAcceptableRate > percent
+    // When minAcceptableRate is provided, calculate: authorization = base_amount / min_acceptable_rate
+    // This is more accurate as it uses the exact rate threshold configured by user
+    if (
+      minAcceptableRate &&
+      Number(minAcceptableRate) > 0 &&
+      currencyDecimal !== undefined &&
+      totalBaseAmountBN.gt(new BN(0))
+    ) {
+      // Calculate authorization using min_acceptable_rate
+      // Formula: authorization_token = ceil(base_amount_usd / min_acceptable_rate)
+      const minRateBN = fromTokenToUnit(minAcceptableRate, USD_DECIMALS);
+      if (minRateBN.gt(new BN(0))) {
+        const numerator = totalBaseAmountBN.mul(new BN(10).pow(new BN(currencyDecimal)));
+        // Ceiling division: ceil(a/b) = (a + b - 1) / b
+        setup = numerator.add(minRateBN).sub(new BN(1)).div(minRateBN);
+        logger.info('Applied subscription authorization with min_acceptable_rate', {
+          hasDynamicPricing,
+          authorizationAmountRaw: setup.toString(),
+          authorizationAmountDisplay: fromUnitToToken(setup.toString(), currencyDecimal),
+          minAcceptableRate,
+          totalBaseAmountUSD: fromUnitToToken(totalBaseAmountBN.toString(), USD_DECIMALS),
+          currencyDecimal,
+        });
+      }
+    } else {
+      // Fallback: Apply slippage percent multiplier
+      // Authorization amount = base * (1 + percent/100)
+      const normalizedSlippage = Number.isFinite(percent) && percent! >= 0 ? percent! : DEFAULT_SLIPPAGE_PERCENT;
+      // Convert slippage percent to multiplier: 0.5% -> 1005/1000, 5% -> 1050/1000
+      const SLIPPAGE_MULTIPLIER = new BN(Math.round(1000 + normalizedSlippage * 10));
+      const SLIPPAGE_DIVISOR = new BN(1000);
+      setup = setup.mul(SLIPPAGE_MULTIPLIER).div(SLIPPAGE_DIVISOR);
+      logger.info('Applied subscription authorization slippage protection', {
+        hasDynamicPricing,
+        authorizationAmount: setup.toString(),
+        slippageRate: `${normalizedSlippage}%`,
+      });
+    }
+  }
+
   const now = dayjs().unix();
-  const item = items.find((x) => (x.upsell_price || x.price).type === 'recurring');
-  const recurring = (item?.upsell_price || item?.price)?.recurring as PriceRecurring;
+  const item = items.find((x) => getSubscriptionItemPrice(x)?.type === 'recurring');
+  const recurring = (item ? getSubscriptionItemPrice(item)?.recurring : undefined) as PriceRecurring;
   const cycle = getRecurringPeriod(recurring);
 
   let trialStartAt = 0;
@@ -760,11 +925,49 @@ async function createOrUpdateSubscription(params: {
 
   const { trialInDays = 0, trialEnd = 0 } = trialConfig;
   const { method: paymentMethod, currency: paymentCurrency } = paymentSettings;
+  const normalizePercent = (value: any) => {
+    const normalized = typeof value === 'string' ? Number(value) : value;
+    if (!Number.isFinite(normalized) || normalized < 0) {
+      return DEFAULT_SLIPPAGE_PERCENT;
+    }
+    return normalized;
+  };
+  const buildSlippageConfig = () => {
+    const fromMeta = metadata?.slippage;
+    if (fromMeta && typeof fromMeta === 'object') {
+      const mode: 'percent' | 'rate' = fromMeta.mode === 'rate' ? 'rate' : 'percent';
+      const percent = normalizePercent(fromMeta.percent);
+      const minRate = typeof fromMeta.min_acceptable_rate === 'string' ? fromMeta.min_acceptable_rate : undefined;
+      const baseCurrency = typeof fromMeta.base_currency === 'string' ? fromMeta.base_currency : undefined;
+      const updatedAtMs = Number.isFinite(Number(fromMeta.updated_at_ms)) ? Number(fromMeta.updated_at_ms) : undefined;
+      return {
+        mode,
+        percent,
+        // Always include min_acceptable_rate if available (for both percent and rate modes)
+        ...(minRate ? { min_acceptable_rate: minRate } : {}),
+        ...(baseCurrency ? { base_currency: baseCurrency } : {}),
+        ...(updatedAtMs ? { updated_at_ms: updatedAtMs } : {}),
+      };
+    }
+    const fromSessionMeta = normalizeSlippageConfigFromMetadata(checkoutSession.metadata, DEFAULT_SLIPPAGE_PERCENT);
+    if (fromSessionMeta) {
+      return fromSessionMeta;
+    }
+    const percent = normalizePercent((checkoutSession as any).slippage_percent);
+    return { mode: 'percent' as const, percent };
+  };
+  const slippageConfig = buildSlippageConfig();
 
   try {
     const itemsSubscriptionData = mergeSubscriptionDataFromLineItems(lineItems);
     let subscription = null;
-    const setup = getSubscriptionCreateSetup(lineItems, paymentCurrency.id, trialInDays, trialEnd);
+    // Build slippage options with min_acceptable_rate for precise authorization calculation
+    const slippageOptions: SlippageOptions = {
+      percent: slippageConfig.percent,
+      minAcceptableRate: slippageConfig.min_acceptable_rate,
+      currencyDecimal: paymentCurrency.decimal,
+    };
+    const setup = getSubscriptionCreateSetup(lineItems, paymentCurrency.id, trialInDays, trialEnd, slippageOptions);
 
     if (existingSubscriptionId) {
       subscription = await Subscription.findByPk(existingSubscriptionId);
@@ -793,6 +996,7 @@ async function createOrUpdateSubscription(params: {
         trial_start: setup.trial.start,
         pending_invoice_item_interval: setup.recurring,
         pending_setup_intent: setupIntent?.id,
+        slippage_config: slippageConfig,
       });
 
       logger.info('Subscription updated', {
@@ -861,6 +1065,7 @@ async function createOrUpdateSubscription(params: {
         default_payment_method_id: paymentMethod.id,
         cancel_at_period_end: false,
         collection_method: 'charge_automatically',
+        slippage_config: slippageConfig,
         description: subscriptionData.description || formatSubscriptionProduct(lineItems),
         proration_behavior: subscriptionData.proration_behavior || 'none',
         payment_behavior: 'default_incomplete',
@@ -1024,13 +1229,8 @@ export async function getSubscriptionLineItems(
   return subItems;
 }
 
-export function isCreditMetered(price: TPrice | TPriceExpanded) {
-  return price.type === 'recurring' && price.recurring?.usage_type === 'metered' && !!price.recurring?.meter_id;
-}
-
-export function isCreditMeteredLineItems(lineItems: TLineItemExpanded[]) {
-  return lineItems.every((item) => item.price && isCreditMetered(item.price));
-}
+// Re-exported from credit-utils.ts to maintain backward compatibility
+export { isCreditMetered, isCreditMeteredLineItems } from './credit-utils';
 
 export function validateStripePaymentAmounts(amount: string, currency: PaymentCurrency) {
   const minAmountInUnits = fromTokenToUnit(0.5, currency.decimal);
@@ -1053,6 +1253,24 @@ export async function validatePaymentAmounts(
   const oneTimeItems = getOneTimeLineItems(lineItems);
   const recurringItems = getRecurringLineItems(lineItems);
 
+  // Check for mixed pricing types (fixed + dynamic)
+  const hasDynamicPricing = lineItems.some((item) => {
+    const price = item.upsell_price || item.price;
+    return (price as any)?.pricing_type === 'dynamic';
+  });
+
+  const hasFixedPricing = lineItems.some((item) => {
+    const price = item.upsell_price || item.price;
+    return !(price as any)?.pricing_type || (price as any)?.pricing_type === 'fixed';
+  });
+
+  if (hasDynamicPricing && hasFixedPricing) {
+    return {
+      valid: false,
+      error: 'Cannot mix fixed pricing and dynamic pricing in the same checkout session',
+    };
+  }
+
   const minAmountInUnits = fromTokenToUnit(0.5, currency.decimal);
 
   // Case 1: All one-time items - validate total payment amount
@@ -1254,3 +1472,432 @@ export async function getCheckoutSessionAmounts(checkoutSession: CheckoutSession
     discounts,
   };
 }
+
+const QUOTE_LOCK_DURATION_SECONDS = 180;
+function calculateTotalBaseAmount(baseAmount: string, quantity: number): string {
+  const baseAmountBN = fromTokenToUnit(trimDecimals(baseAmount, USD_DECIMALS), USD_DECIMALS);
+  const quantityBN = new BN(quantity);
+  const totalBaseAmountBN = baseAmountBN.mul(quantityBN);
+  return fromUnitToToken(totalBaseAmountBN.toString(), USD_DECIMALS);
+}
+
+/**
+ * Enrich checkout session with dynamic pricing quotes
+ * For each dynamic price, create or reuse a quote and attach quote info to line items
+ *
+ * @param options.skipGeneration - If true, only fetch existing quotes via quote_id, don't generate new ones
+ */
+export async function enrichCheckoutSessionWithQuotes(
+  checkoutSession: CheckoutSession,
+  lineItems: TLineItemExpanded[],
+  currencyId: string,
+  options: { skipGeneration?: boolean; forceRefresh?: boolean } = {}
+): Promise<{
+  lineItems: TLineItemExpanded[];
+  quotes: Record<
+    string,
+    {
+      quote_id: string;
+      expires_at: number;
+      quoted_amount: string;
+      exchange_rate?: string;
+      rate_provider_name?: string;
+      rate_provider_id?: string;
+    }
+  >;
+  rateUnavailable?: boolean;
+  rateError?: string;
+  regenerated?: boolean;
+  refreshed?: boolean;
+}> {
+  const { skipGeneration = false, forceRefresh = false } = options;
+  const quoteService = getQuoteService();
+
+  // Filter out items with missing price (data integrity issue)
+  const invalidItems = lineItems.filter((item) => !item.price);
+  if (invalidItems.length > 0) {
+    logger.error('Line items with missing price detected - possible data integrity issue', {
+      sessionId: checkoutSession.id,
+      invalidPriceIds: invalidItems.map((item) => item.price_id),
+      totalItems: lineItems.length,
+      invalidCount: invalidItems.length,
+    });
+  }
+  // Only process items with valid price
+  const validLineItems = lineItems.filter((item) => item.price);
+  if (validLineItems.length === 0) {
+    logger.warn('No valid line items with price found', { sessionId: checkoutSession.id });
+    return { lineItems, quotes: {}, refreshed: false };
+  }
+
+  const quotes: Record<
+    string,
+    {
+      quote_id: string;
+      expires_at: number;
+      quoted_amount: string;
+      exchange_rate: string;
+      rate_provider_name: string;
+      rate_provider_id: string;
+    }
+  > = {};
+
+  // First, check if line_items already have quote_id references
+  // If so, fetch quote data from PriceQuote table and check if expired
+  const lineItemsWithQuoteIds = validLineItems.filter((item) => (item as any).quote_id);
+  const now = Math.floor(Date.now() / 1000);
+  const quoteLockedAt = checkoutSession.metadata?.quote_locked_at;
+  const lockStart =
+    typeof quoteLockedAt === 'number'
+      ? quoteLockedAt
+      : typeof quoteLockedAt === 'string'
+        ? Number(quoteLockedAt)
+        : null;
+  const lockActive = Number.isFinite(lockStart) && now - (lockStart as number) < QUOTE_LOCK_DURATION_SECONDS;
+  const slippagePercentValue =
+    (checkoutSession.metadata as any)?.slippage?.percent ?? (checkoutSession as any).slippage_percent;
+  const slippagePercentValueNumber = Number(slippagePercentValue);
+  const slippagePercent = Number.isFinite(slippagePercentValueNumber) ? slippagePercentValueNumber : 0.5;
+  const quotesById = new Map<string, PriceQuote>();
+  const refreshQuoteIds = new Set<string>();
+  let hasExpiredQuotes = false;
+  let hasStaleQuotes = false;
+  let hasMissingQuotes = false;
+  let regenerated = false;
+  let createdNewQuotes = false;
+  const applyQuoteToItem = (item: TLineItemExpanded, quote: PriceQuote) => {
+    (item as any).custom_amount = quote.quoted_amount;
+    (item as any).quoted_amount = quote.quoted_amount;
+    (item as any).quote_id = quote.id;
+    (item as any).exchange_rate = quote.exchange_rate;
+    (item as any).rate_provider_name = quote.rate_provider_name;
+    (item as any).rate_provider_id = quote.rate_provider_id;
+    (item as any).rate_timestamp_ms = quote.rate_timestamp_ms;
+    (item as any).expires_at = quote.expires_at;
+    // Store the currency ID this quote was created for - essential for frontend validation
+    (item as any).quote_currency_id = quote.target_currency_id;
+
+    const quoteKey = `${item.price?.id || item.price_id}_${currencyId}`;
+    quotes[quoteKey] = {
+      quote_id: quote.id,
+      expires_at: quote.expires_at,
+      quoted_amount: quote.quoted_amount,
+      exchange_rate: quote.exchange_rate,
+      rate_provider_name: quote.rate_provider_name,
+      rate_provider_id: quote.rate_provider_id,
+    };
+  };
+
+  if (lineItemsWithQuoteIds.length > 0) {
+    const quoteIds = Array.from(new Set(lineItemsWithQuoteIds.map((item) => (item as any).quote_id).filter(Boolean)));
+    const existingQuotes = await PriceQuote.findAll({
+      where: { id: quoteIds },
+    });
+
+    existingQuotes.forEach((quote) => {
+      quotesById.set(quote.id, quote);
+    });
+    if (existingQuotes.length !== quoteIds.length) {
+      hasMissingQuotes = true;
+      logger.warn('Some quote references are missing from database', {
+        sessionId: checkoutSession.id,
+        totalQuoteIds: quoteIds.length,
+        foundQuotes: existingQuotes.length,
+      });
+    }
+
+    lineItemsWithQuoteIds.forEach((item) => {
+      const quoteId = (item as any).quote_id;
+      const quote = quotesById.get(quoteId);
+      if (!quote) {
+        if (!skipGeneration) {
+          refreshQuoteIds.add(quoteId);
+        }
+        return;
+      }
+
+      const isPaid = quote.status === 'paid';
+      const isUsed = quote.status === 'used';
+      if (isPaid || (isUsed && (lockActive || skipGeneration))) {
+        applyQuoteToItem(item, quote);
+        return;
+      }
+      if (isUsed && !lockActive && !skipGeneration) {
+        hasExpiredQuotes = true;
+        refreshQuoteIds.add(quoteId);
+        logger.info('Detected used quote with expired lock, will refresh', {
+          sessionId: checkoutSession.id,
+          quoteId,
+          status: quote.status,
+        });
+        return;
+      }
+
+      if (forceRefresh && !skipGeneration) {
+        if (!lockActive) {
+          refreshQuoteIds.add(quoteId);
+          logger.info('Force refresh quote for checkout session', {
+            sessionId: checkoutSession.id,
+            quoteId,
+          });
+        } else {
+          logger.info('Skip force refresh due to active quote lock', {
+            sessionId: checkoutSession.id,
+            quoteId,
+          });
+        }
+        return;
+      }
+
+      const price = (item.upsell_price || item.price) as any;
+      if (
+        !skipGeneration &&
+        !lockActive &&
+        quote.status !== 'paid' &&
+        price?.pricing_type === 'dynamic' &&
+        price?.base_amount
+      ) {
+        const expectedBaseAmount = calculateTotalBaseAmount(price.base_amount, Number(item.quantity || 0));
+        const expectedTrimmed = trimDecimals(expectedBaseAmount, USD_DECIMALS);
+        const quoteTrimmed = trimDecimals(quote.base_amount || '0', USD_DECIMALS);
+        if (quoteTrimmed !== expectedTrimmed) {
+          hasStaleQuotes = true;
+          refreshQuoteIds.add(quoteId);
+          logger.info('Detected quote base_amount mismatch, will refresh quote', {
+            sessionId: checkoutSession.id,
+            quoteId,
+            priceId: item.price_id || item.price?.id,
+            expectedBaseAmount: expectedTrimmed,
+            quoteBaseAmount: quoteTrimmed,
+            quantity: item.quantity,
+          });
+          return;
+        }
+      }
+
+      const isExpired = quote.status !== 'paid' && (quote.expires_at < now || quote.status === 'expired');
+      if (!skipGeneration && !lockActive && isExpired) {
+        hasExpiredQuotes = true;
+        refreshQuoteIds.add(quoteId);
+        logger.info('Detected expired quote', {
+          sessionId: checkoutSession.id,
+          expiredQuoteId: quote.id,
+          expiresAt: new Date(quote.expires_at * 1000).toISOString(),
+          now: new Date(now * 1000).toISOString(),
+        });
+        return;
+      }
+
+      const isInactive = quote.status !== 'active' && quote.status !== 'paid';
+      if (!skipGeneration && !lockActive && isInactive) {
+        hasExpiredQuotes = true;
+        refreshQuoteIds.add(quoteId);
+        logger.info('Detected inactive quote, will refresh', {
+          sessionId: checkoutSession.id,
+          quoteId: quote.id,
+          status: quote.status,
+        });
+        return;
+      }
+
+      // Use existing quotes (either not expired, or skipGeneration)
+      applyQuoteToItem(item, quote);
+    });
+
+    logger.info('Processed existing quotes from database', {
+      sessionId: checkoutSession.id,
+      totalQuoteIds: lineItemsWithQuoteIds.length,
+      foundQuotes: quotesById.size,
+      hasExpiredQuotes,
+      hasStaleQuotes,
+      hasMissingQuotes,
+      skipGeneration,
+      refreshQuotes: refreshQuoteIds.size,
+    });
+
+    if (skipGeneration || refreshQuoteIds.size === 0) {
+      return { lineItems, quotes, refreshed: false };
+    }
+  }
+
+  // Find all dynamic pricing items that need new quotes or refresh
+  const dynamicItems = validLineItems.filter((item) => {
+    const price = getSubscriptionItemPrice(item);
+    return (
+      price?.pricing_type === 'dynamic' && ((item as any).quote_id ? refreshQuoteIds.has((item as any).quote_id) : true)
+    );
+  });
+
+  // If no dynamic items need new quotes, return early
+  if (dynamicItems.length === 0) {
+    return { lineItems, quotes, refreshed: false };
+  }
+
+  // If skipGeneration is enabled, don't generate new quotes for items without quote_id
+  // This is used for submitted/completed checkout sessions where we only want to use existing quotes
+  if (skipGeneration) {
+    logger.info('Skipping quote generation for dynamic items (skipGeneration enabled)', {
+      sessionId: checkoutSession.id,
+      dynamicItemsWithoutQuotes: dynamicItems.length,
+    });
+    return { lineItems, quotes, refreshed: false };
+  }
+
+  // Fetch exchange rate once for all dynamic items (they all use the same target currency)
+  const currency = (await PaymentCurrency.findByPk(currencyId, {
+    include: [{ model: PaymentMethod, as: 'payment_method' }],
+  })) as PaymentCurrency & { payment_method: PaymentMethod };
+  if (!currency) {
+    throw new Error(`Currency ${currencyId} not found`);
+  }
+
+  if (currency.payment_method?.type === 'stripe') {
+    return { lineItems, quotes, refreshed: false };
+  }
+
+  const exchangeRateService = getExchangeRateService();
+
+  // Try to get exchange rate, but don't block checkout if unavailable
+  let rateResult;
+  try {
+    // For ArcBlock payment method, always use ABT for exchange rate
+    // For other methods, use the currency's symbol
+    const rateSymbol = getExchangeRateSymbol(currency.symbol, currency.payment_method?.type as ChainType);
+    rateResult = await exchangeRateService.getRate(rateSymbol);
+  } catch (error: any) {
+    logger.warn('Exchange rate unavailable for checkout session', {
+      checkoutSessionId: checkoutSession.id,
+      currencyId,
+      currencySymbol: currency.symbol,
+      error: error.message,
+    });
+
+    // Return without quotes, frontend will show warning
+    return {
+      lineItems,
+      quotes: {},
+      rateUnavailable: true,
+      rateError: error.message || 'Exchange rate service unavailable',
+      refreshed: false,
+    };
+  }
+
+  logger.info('Fetched exchange rate for batch quote creation', {
+    currencyId,
+    currencySymbol: currency.symbol,
+    rate: rateResult.rate,
+    provider: rateResult.provider_name,
+    dynamicItemsCount: dynamicItems.length,
+  });
+
+  // Create or refresh quotes for dynamic items using the same exchange rate
+  const quoteResults = await Promise.all(
+    dynamicItems.map(async (item) => {
+      // Use upsell_price if available, otherwise use price
+      const price = getSubscriptionItemPrice(item);
+      const { quantity } = item;
+
+      try {
+        const quoteId = (item as any).quote_id;
+        let quoteResponse: QuoteResponse;
+
+        const existingQuote = quoteId ? quotesById.get(quoteId) : null;
+        const shouldCreateNewQuote = !existingQuote || (existingQuote.status === 'used' && !lockActive);
+        if (!shouldCreateNewQuote && quoteId && existingQuote) {
+          quoteResponse = await quoteService.refreshQuoteWithRate({
+            quote_id: quoteId,
+            price_id: price?.id,
+            session_id: checkoutSession.id,
+            target_currency_id: currencyId,
+            quantity,
+            rateResult,
+            slippage_percent: slippagePercent,
+          });
+        } else {
+          quoteResponse = await quoteService.createQuoteWithRate({
+            price_id: price?.id,
+            session_id: checkoutSession.id,
+            target_currency_id: currencyId,
+            quantity,
+            rateResult,
+            slippage_percent: slippagePercent,
+          });
+          createdNewQuotes = true;
+        }
+
+        return {
+          item,
+          quoteResponse,
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error('Failed to create quote for dynamic price', {
+          priceId: price.id,
+          checkoutSessionId: checkoutSession.id,
+          currencyId,
+          errorMessage,
+          errorName: (error as any)?.name,
+        });
+        throw error;
+      }
+    })
+  );
+
+  // Build quote map for quick lookup
+  const quoteByPriceId = new Map<string, (typeof quoteResults)[0]>();
+  quoteResults.forEach((result) => {
+    const priceId = result.item.price?.id || result.item.price_id;
+    if (priceId) {
+      quoteByPriceId.set(priceId, result);
+    }
+  });
+
+  // Extract quote info helper
+  const extractQuoteInfo = (quoteResponse: QuoteResponse) => ({
+    quote_id: quoteResponse.quote.id,
+    expires_at: quoteResponse.expires_at,
+    quoted_amount: quoteResponse.computed_unit_amount,
+    exchange_rate: quoteResponse.quote.exchange_rate,
+    rate_provider_name: quoteResponse.quote.rate_provider_name,
+    rate_provider_id: quoteResponse.quote.rate_provider_id,
+    rate_timestamp_ms: quoteResponse.quote.rate_timestamp_ms,
+  });
+
+  // Build quotes object
+  quoteResults.forEach((result) => {
+    const priceId = result.item.price?.id || result.item.price_id;
+    if (priceId) {
+      const quoteKey = `${priceId}_${currencyId}`;
+      quotes[quoteKey] = extractQuoteInfo(result.quoteResponse);
+    }
+  });
+
+  regenerated = createdNewQuotes;
+  const refreshed = refreshQuoteIds.size > 0 || createdNewQuotes;
+
+  // Enrich line items with quote information
+  const enrichedLineItems = lineItems.map((item) => {
+    // Skip items with missing price
+    if (!item.price) {
+      return item;
+    }
+    const quoteInfo = quoteByPriceId.get(item.price.id);
+    if (!quoteInfo) {
+      return item;
+    }
+
+    const quoteData = extractQuoteInfo(quoteInfo.quoteResponse);
+    return {
+      ...item,
+      ...quoteData,
+      custom_amount: quoteInfo.quoteResponse.computed_unit_amount,
+    };
+  });
+
+  return {
+    lineItems: enrichedLineItems,
+    quotes,
+    regenerated,
+    refreshed,
+  };
+}