payment-kit 1.24.4 → 1.25.0

package/api/src/routes/connect/setup.ts

@@ -4,11 +4,12 @@ import dayjs from '../../libs/dayjs';
 import logger from '../../libs/logger';
 import { isDelegationSufficientForPayment } from '../../libs/payment';
 import { getSubscriptionTrialSetup } from '../../libs/subscription';
-import { getFastCheckoutAmount } from '../../libs/session';
+import { getFastCheckoutAmount, getSubscriptionCreateSetup, type SlippageOptions } from '../../libs/session';
 import { getTxMetadata } from '../../libs/util';
+import { normalizeSlippageConfigFromMetadata } from '../../libs/slippage';
 import { invoiceQueue } from '../../queues/invoice';
 import { addSubscriptionJob } from '../../queues/subscription';
-import type { TLineItemExpanded } from '../../store/models';
+import { Price } from '../../store/models';
 import {
   ensureSetupIntent,
   executeOcapTransactions,
@@ -43,7 +44,9 @@ export default {
 
     const claimsList: any[] = [];
     const now = dayjs().unix();
-    const items = checkoutSession.line_items as TLineItemExpanded[];
+    // Expand line_items to include full price and upsell_price objects
+    // This is critical for getSubscriptionCreateSetup to correctly use upsell_price when calculating authorization amount
+    const items = await Price.expand(checkoutSession.line_items);
     const { trialEnd, trialInDays } = getSubscriptionTrialSetup(
       checkoutSession.subscription_data as any,
       paymentCurrency.id
@@ -52,19 +55,36 @@ export default {
     const trialing = trialInDays > 0 || trialEnd > now;
     const billingThreshold = Number(checkoutSession.subscription_data?.billing_threshold_amount || 0);
     const minStakeAmount = Number(checkoutSession.subscription_data?.min_stake_amount || 0);
-    const fastCheckoutAmount = await getFastCheckoutAmount({
-      items,
-      mode: checkoutSession.mode,
-      currencyId: paymentCurrency.id,
-      trialing,
-    });
+
+    // Calculate required amount considering slippage_config for dynamic pricing
+    // Priority: subscription.slippage_config > checkoutSession.metadata.slippage
+    const slippageConfig =
+      subscription?.slippage_config || normalizeSlippageConfigFromMetadata(checkoutSession.metadata);
+    let requiredAmount: string;
+    if (slippageConfig?.min_acceptable_rate) {
+      // Use slippage_config for precise calculation
+      const slippageOptions: SlippageOptions = {
+        percent: slippageConfig.percent ?? 0.5,
+        minAcceptableRate: slippageConfig.min_acceptable_rate,
+        currencyDecimal: paymentCurrency.decimal,
+      };
+      const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, trialInDays, trialEnd, slippageOptions);
+      requiredAmount = setup.amount.setup;
+    } else {
+      requiredAmount = await getFastCheckoutAmount({
+        items,
+        mode: checkoutSession.mode,
+        currencyId: paymentCurrency.id,
+        trialing,
+      });
+    }
 
     if (paymentMethod.type === 'arcblock') {
       const delegation = await isDelegationSufficientForPayment({
         paymentMethod,
         paymentCurrency,
         userDid,
-        amount: fastCheckoutAmount,
+        amount: requiredAmount,
       });
       // if we can complete purchase without any wallet interaction
       if (delegation.sufficient === false) {
@@ -80,6 +100,7 @@ export default {
             trialing,
             billingThreshold: Math.max(minStakeAmount, billingThreshold),
             items,
+            slippageConfig: subscription?.slippage_config || undefined,
           }),
         });
       }
@@ -116,6 +137,7 @@ export default {
           trialing,
           billingThreshold,
           items,
+          slippageConfig: subscription?.slippage_config || undefined,
         }),
       });
 

package/api/src/routes/connect/shared.ts

@@ -21,6 +21,7 @@ import {
   getSubscriptionCreateSetup,
   isDonationCheckoutSession,
   getSubscriptionLineItems,
+  SlippageOptions,
 } from '../../libs/session';
 import { getDiscountRecordsForCheckout } from '../../libs/discount/coupon';
 import {
@@ -40,6 +41,7 @@ import { PaymentCurrency } from '../../store/models/payment-currency';
 import { PaymentIntent } from '../../store/models/payment-intent';
 import { PaymentMethod } from '../../store/models/payment-method';
 import { Price } from '../../store/models/price';
+import { PriceQuote } from '../../store/models/price-quote';
 import { SetupIntent } from '../../store/models/setup-intent';
 import { Subscription } from '../../store/models/subscription';
 import { ensureInvoiceAndItems } from '../../libs/invoice';
@@ -200,7 +202,7 @@ export async function ensurePaymentIntent(
     throw new Error(`Payment method ${paymentMethod.type} should not be here`);
   }
 
-  checkoutSession.line_items = await Price.expand(checkoutSession.line_items);
+  checkoutSession.line_items = await Price.expand(checkoutSession.line_items, { upsell: true });
 
   return {
     checkoutSession,
@@ -262,7 +264,7 @@ export async function ensureSetupIntent(checkoutSessionId: string, skipInvoice?:
     throw new Error(`Payment method ${paymentMethod.type} should not be here`);
   }
 
-  checkoutSession.line_items = await Price.expand(checkoutSession.line_items);
+  checkoutSession.line_items = await Price.expand(checkoutSession.line_items, { upsell: true });
 
   let invoice;
   if (subscription && !skipInvoice) {
@@ -421,6 +423,9 @@ export async function ensureInvoiceForCheckout({
           );
         }
 
+        // Final Freeze: Quotes in 'used' or 'payment_failed' status can be retried directly
+        // No status reset needed - quote price is immutable once created
+
         return {
           invoice,
           items: await InvoiceItem.findAll({ where: { invoice_id: existingInvoice } }),
@@ -462,7 +467,61 @@ export async function ensureInvoiceForCheckout({
   const trialInDays = Number(checkoutSession.subscription_data?.trial_period_days || 0);
   const trialEnd = Number(checkoutSession.subscription_data?.trial_end || 0);
   const now = dayjs().unix();
-  const invoiceItems = lineItems || (await Price.expand(checkoutSession.line_items, { product: true }));
+  let invoiceItems = lineItems || (await Price.expand(checkoutSession.line_items, { product: true, upsell: true }));
+
+  // For items with quote_id, fetch full quote info and attach to line item metadata
+  // This ensures invoice line items have complete quote info for display
+  const itemsWithQuoteIds = invoiceItems.filter((item) => (item as any).quote_id);
+
+  if (itemsWithQuoteIds.length > 0) {
+    const quoteIds = itemsWithQuoteIds.map((item) => (item as any).quote_id).filter(Boolean);
+    const quotes = await PriceQuote.findAll({
+      where: { id: quoteIds },
+    });
+
+    const quotesById = new Map(quotes.map((q) => [q.id, q]));
+
+    // Fill custom_amount and metadata.quote from quotes
+    invoiceItems = invoiceItems.map((item) => {
+      const quoteId = (item as any).quote_id;
+      if (quoteId) {
+        const quote = quotesById.get(quoteId);
+        if (quote) {
+          return {
+            ...item,
+            quote_id: quote.id, // Add quote_id directly to line item for invoice item creation
+            custom_amount: item.custom_amount || quote.quoted_amount,
+            metadata: {
+              ...((item as any).metadata || {}),
+              quote_id: quote.id, // Also in metadata for audit trail
+              quote: {
+                id: quote.id,
+                base_currency: quote.base_currency,
+                base_amount: quote.base_amount,
+                quoted_amount: quote.quoted_amount,
+                target_currency_id: quote.target_currency_id,
+                rate_currency_symbol: quote.rate_currency_symbol,
+                exchange_rate: quote.exchange_rate,
+                rate_provider_name: quote.rate_provider_name,
+                rate_provider_id: quote.rate_provider_id,
+                rate_timestamp_ms: quote.rate_timestamp_ms,
+                slippage_percent: quote.slippage_percent ?? (quote.metadata as any)?.slippage?.percent ?? 0.5,
+                quantity: item.quantity,
+                status: quote.status,
+              },
+            },
+          };
+        }
+      }
+      return item;
+    });
+
+    logger.info('Enriched line items with quote metadata for invoice creation', {
+      checkoutSessionId: checkoutSession.id,
+      itemCount: itemsWithQuoteIds.length,
+      foundQuotes: quotesById.size,
+    });
+  }
 
   // Get discount records for this checkout session
   let discountInfo: { appliedDiscounts: string[]; discountBreakdown: Array<{ amount: string; discount: string }> } = {
@@ -562,6 +621,23 @@ export async function ensureInvoiceForCheckout({
     await subscription.update({ latest_invoice_id: invoice.id });
   }
 
+  // Update quotes with invoice_id for audit trail
+  // Find quote_ids from invoice items and update the quotes
+  const quoteIdsFromItems = items
+    .map((item) => item.metadata?.quote_id)
+    .filter((id): id is string => typeof id === 'string' && id.length > 0);
+
+  if (quoteIdsFromItems.length > 0) {
+    await PriceQuote.update(
+      { invoice_id: invoice.id },
+      { where: { id: quoteIdsFromItems } }
+    );
+    logger.info('Updated quotes with invoice_id', {
+      invoiceId: invoice.id,
+      quoteIds: quoteIdsFromItems,
+    });
+  }
+
   return { invoice, items };
 }
 
@@ -578,7 +654,7 @@ export async function ensureInvoicesForSubscriptions({
     return { invoices: [] };
   }
 
-  const lineItems = await Price.expand(checkoutSession.line_items, { product: true });
+  const lineItems = await Price.expand(checkoutSession.line_items, { product: true, upsell: true });
 
   const primarySubscription = (subscriptions.find((x) => x.metadata.is_primary_subscription) ||
     subscriptions[0]) as Subscription;
@@ -607,7 +683,7 @@ export async function ensureInvoicesForSubscriptions({
   return { invoices: createdInvoices as Invoice[] };
 }
 
-export async function ensureInvoiceForCollect(invoiceId: string) {
+export async function ensureInvoiceForCollect(invoiceId: string, options?: { allowCreatePI?: boolean }) {
   const invoice = await Invoice.findByPk(invoiceId);
   if (!invoice) {
     throw new Error(`Invoice ${invoiceId} not found`);
@@ -623,11 +699,41 @@ export async function ensureInvoiceForCollect(invoiceId: string) {
   }
 
   if (!invoice.payment_intent_id) {
-    await invoiceQueue.pushAndWait({
-      id: invoice.id,
-      job: { invoiceId: invoice.id, retryOnError: false, justCreate: true },
-    });
-    await invoice.reload();
+    // For open invoices, use invoiceQueue to create PI
+    if (invoice.status === 'open') {
+      await invoiceQueue.pushAndWait({
+        id: invoice.id,
+        job: { invoiceId: invoice.id, retryOnError: false, justCreate: true },
+      });
+      await invoice.reload();
+    }
+
+    // For uncollectible invoices with allowCreatePI flag, create PI directly
+    if (invoice.status === 'uncollectible' && options?.allowCreatePI) {
+      const customer = await Customer.findByPk(invoice.customer_id);
+      const paymentIntent = await PaymentIntent.create({
+        livemode: !!invoice.livemode,
+        amount: invoice.amount_remaining,
+        amount_received: '0',
+        amount_capturable: '0',
+        customer_id: invoice.customer_id,
+        description: 'Manual payment for uncollectible invoice',
+        currency_id: invoice.currency_id,
+        payment_method_id: invoice.default_payment_method_id,
+        invoice_id: invoice.id,
+        status: 'requires_action',
+        capture_method: 'manual',
+        confirmation_method: 'manual',
+        payment_method_types: [],
+        receipt_email: customer?.email || invoice.customer_email,
+        statement_descriptor: invoice.statement_descriptor,
+      });
+      await invoice.update({ payment_intent_id: paymentIntent.id });
+      logger.info('Created PI for uncollectible invoice via allowCreatePI', {
+        invoiceId: invoice.id,
+        paymentIntentId: paymentIntent.id,
+      });
+    }
   }
 
   const paymentIntent = await PaymentIntent.findByPk(invoice.payment_intent_id);
@@ -754,6 +860,7 @@ export async function getDelegationTxClaim({
   trialing = false,
   billingThreshold = 0,
   requiredStake = true,
+  slippageConfig,
 }: {
   userDid: string;
   userPk: string;
@@ -767,8 +874,33 @@ export async function getDelegationTxClaim({
   billingThreshold?: number;
   requiredStake?: boolean;
   requiredAmount?: string;
+  slippageConfig?: {
+    mode?: 'percent' | 'rate';
+    percent?: number;
+    min_acceptable_rate?: string;
+    base_currency?: string;
+  };
 }) {
-  const amount = await getFastCheckoutAmount({ items, mode, currencyId: paymentCurrency.id });
+  // Calculate authorization amount
+  // When slippage_config with min_acceptable_rate is provided, use it for precise calculation
+  let amount: string;
+  if (slippageConfig?.min_acceptable_rate) {
+    const slippageOptions: SlippageOptions = {
+      percent: slippageConfig.percent ?? 0.5,
+      minAcceptableRate: slippageConfig.min_acceptable_rate,
+      currencyDecimal: paymentCurrency.decimal,
+    };
+    const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, 0, 0, slippageOptions);
+    amount = setup.amount.setup;
+    logger.info('getDelegationTxClaim: Using slippage_config for authorization calculation', {
+      mode,
+      slippageConfig,
+      authorizationAmount: amount,
+    });
+  } else {
+    amount = await getFastCheckoutAmount({ items, mode, currencyId: paymentCurrency.id });
+  }
+
   const address = toDelegateAddress(userDid, wallet.address);
   const tokenLimits = await getTokenLimitsForDelegation(items, paymentMethod, paymentCurrency, address, amount);
   let tokenRequirements = await getTokenRequirements({
@@ -939,7 +1071,14 @@ export async function getStakeTxClaim({
       ),
     };
 
-    const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, 0, 0);
+    // Build slippage options with min_acceptable_rate for precise authorization calculation
+    const slippageConfig = subscription.slippage_config;
+    const slippageOptions = {
+      percent: slippageConfig?.percent ?? 0.5,
+      minAcceptableRate: slippageConfig?.min_acceptable_rate,
+      currencyDecimal: paymentCurrency.decimal,
+    };
+    const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, 0, 0, slippageOptions);
 
     return {
       type: 'StakeTx',
@@ -1030,7 +1169,14 @@ export async function getOverdraftProtectionStakeTxClaim({
       ),
     };
 
-    const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, 0, 0);
+    // Build slippage options with min_acceptable_rate for precise authorization calculation
+    const slippageConfig = subscription.slippage_config;
+    const slippageOptions = {
+      percent: slippageConfig?.percent ?? 0.5,
+      minAcceptableRate: slippageConfig?.min_acceptable_rate,
+      currencyDecimal: paymentCurrency.decimal,
+    };
+    const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, 0, 0, slippageOptions);
 
     return {
       type: 'StakeTx',

package/api/src/routes/connect/subscribe.ts

@@ -5,11 +5,13 @@ import dayjs from '../../libs/dayjs';
 import logger from '../../libs/logger';
 import { isDelegationSufficientForPayment, checkTokenBalance } from '../../libs/payment';
 import { getSubscriptionTrialSetup } from '../../libs/subscription';
-import { getFastCheckoutAmount } from '../../libs/session';
+import { getFastCheckoutAmount, getSubscriptionCreateSetup, type SlippageOptions } from '../../libs/session';
 import { getTxMetadata } from '../../libs/util';
+import { normalizeSlippageConfigFromMetadata } from '../../libs/slippage';
 import { invoiceQueue } from '../../queues/invoice';
 import { addSubscriptionJob } from '../../queues/subscription';
 import type { Invoice, Subscription, TLineItemExpanded } from '../../store/models';
+import { Price } from '../../store/models';
 import {
   ensureInvoicesForSubscriptions,
   ensurePaymentIntent,
@@ -65,7 +67,9 @@ export default {
     }
 
     const now = dayjs().unix();
-    const items = checkoutSession.line_items as TLineItemExpanded[];
+    // Expand line_items to include full price and upsell_price objects
+    // This is critical for getSubscriptionCreateSetup to correctly use upsell_price when calculating authorization amount
+    const items = await Price.expand(checkoutSession.line_items);
     const { trialEnd, trialInDays } = getSubscriptionTrialSetup(
       checkoutSession.subscription_data as any,
       paymentCurrency.id
@@ -73,12 +77,29 @@ export default {
     const trialing = trialInDays > 0 || trialEnd > now;
     const billingThreshold = Number(checkoutSession.subscription_data?.billing_threshold_amount || 0);
     const minStakeAmount = Number(checkoutSession.subscription_data?.min_stake_amount || 0);
-    const fastCheckoutAmount = await getFastCheckoutAmount({
-      items,
-      mode: checkoutSession.mode,
-      currencyId: paymentCurrency.id,
-      trialing,
-    });
+
+    // Calculate required amount considering slippage_config for dynamic pricing
+    // Priority: primarySubscription.slippage_config > checkoutSession.metadata.slippage
+    const slippageConfig =
+      primarySubscription?.slippage_config || normalizeSlippageConfigFromMetadata(checkoutSession.metadata);
+    let requiredAmount: string;
+    if (slippageConfig?.min_acceptable_rate) {
+      // Use slippage_config for precise calculation
+      const slippageOptions: SlippageOptions = {
+        percent: slippageConfig.percent ?? 0.5,
+        minAcceptableRate: slippageConfig.min_acceptable_rate,
+        currencyDecimal: paymentCurrency.decimal,
+      };
+      const setup = getSubscriptionCreateSetup(items, paymentCurrency.id, trialInDays, trialEnd, slippageOptions);
+      requiredAmount = setup.amount.setup;
+    } else {
+      requiredAmount = await getFastCheckoutAmount({
+        items,
+        mode: checkoutSession.mode,
+        currencyId: paymentCurrency.id,
+        trialing,
+      });
+    }
     const claimsList: any[] = [];
 
     const allSubscriptionIds = subscriptions.map((sub) => sub.id);
@@ -88,7 +109,7 @@ export default {
         paymentMethod,
         paymentCurrency,
         userDid,
-        amount: fastCheckoutAmount,
+        amount: requiredAmount,
       });
 
       // if we can complete purchase without any wallet interaction
@@ -111,6 +132,7 @@ export default {
             billingThreshold: Math.max(minStakeAmount, billingThreshold),
             items,
             requiredStake,
+            slippageConfig: primarySubscription?.slippage_config || undefined,
           }),
         });
       }
@@ -157,6 +179,7 @@ export default {
           trialing,
           billingThreshold,
           items,
+          slippageConfig: primarySubscription?.slippage_config || undefined,
         }),
       });
 

package/api/src/routes/credit-grants.ts

@@ -9,6 +9,7 @@ import logger from '../libs/logger';
 import { authenticate } from '../libs/security';
 import {
   AutoRechargeConfig,
+  ChainType,
   CreditGrant,
   Customer,
   Invoice,
@@ -26,6 +27,9 @@ import { blocklet } from '../libs/auth';
 import { formatMetadata } from '../libs/util';
 import { getPriceUintAmountByCurrency } from '../libs/price';
 import { checkTokenBalance } from '../libs/payment';
+import { getExchangeRateService } from '../libs/exchange-rate/service';
+import { getExchangeRateSymbol, hasTokenAddress } from '../libs/exchange-rate/token-address-mapping';
+import { isRateBelowMinAcceptableRate } from '../libs/slippage';
 import { trimDecimals } from '../libs/math-utils';
 import { systemMaxPendingAmount } from '../libs/env';
 
@@ -546,11 +550,106 @@ router.get('/verify-availability', authMine, async (req, res) => {
       }
     }
 
+    // 7. Check dynamic pricing constraints
+    const isDynamicPricing = config.price.pricing_type === 'dynamic';
+    let exchangeRateInfo: { rate: string; timestamp_ms: number; degraded?: boolean } | null = null;
+    let slippageCheck: { passed: boolean; reason?: string } | null = null;
+    let canCoverPending = true;
+
+    if (isDynamicPricing) {
+      // 7a. Check if exchange rate is available
+      const methodType = config.paymentMethod.type as ChainType;
+      if (!hasTokenAddress(config.rechargeCurrency.symbol, methodType)) {
+        return res.json({
+          can_continue: false,
+          reason: 'exchange_rate_not_supported',
+          is_dynamic_pricing: true,
+        });
+      }
+
+      // 7b. Get current exchange rate
+      try {
+        const exchangeRateService = getExchangeRateService();
+        const rateSymbol = getExchangeRateSymbol(config.rechargeCurrency.symbol, methodType);
+        const rateResult = await exchangeRateService.getRate(rateSymbol);
+        exchangeRateInfo = {
+          rate: rateResult.rate,
+          timestamp_ms: rateResult.timestamp_ms,
+          degraded: rateResult.degraded,
+        };
+      } catch (err: any) {
+        logger.warn('Failed to fetch exchange rate for auto-recharge check', {
+          error: err.message,
+          symbol: config.rechargeCurrency.symbol,
+        });
+        return res.json({
+          can_continue: false,
+          reason: 'exchange_rate_fetch_failed',
+          is_dynamic_pricing: true,
+          error: err.message,
+        });
+      }
+
+      // 7c. Check slippage if config exists
+      if (config.slippage_config?.min_acceptable_rate && exchangeRateInfo) {
+        const rateBelowMin = isRateBelowMinAcceptableRate(
+          exchangeRateInfo.rate,
+          config.slippage_config.min_acceptable_rate
+        );
+        slippageCheck = {
+          passed: !rateBelowMin,
+          reason: rateBelowMin ? 'rate_below_min_acceptable' : undefined,
+        };
+
+        if (rateBelowMin) {
+          return res.json({
+            can_continue: false,
+            reason: 'slippage_exceeded',
+            is_dynamic_pricing: true,
+            exchange_rate: exchangeRateInfo,
+            slippage_check: slippageCheck,
+            slippage_config: {
+              min_acceptable_rate: config.slippage_config.min_acceptable_rate,
+              percent: config.slippage_config.percent,
+            },
+          });
+        }
+      }
+
+      // 7d. For dynamic pricing, check if single recharge can cover pending amount
+      if (pendingAmountBN.gt(new BN(0))) {
+        // Calculate credit amount from single recharge
+        const creditConfig = config.price.metadata?.credit_config as { credit_amount?: string | number } | undefined;
+        const creditAmount = creditConfig?.credit_amount
+          ? new BN(String(creditConfig.credit_amount)).mul(new BN(config.quantity ?? 1))
+          : new BN(0);
+
+        // Convert pending amount to credit currency for comparison
+        canCoverPending = creditAmount.gte(pendingAmountBN);
+
+        if (!canCoverPending) {
+          return res.json({
+            can_continue: false,
+            reason: 'cannot_cover_pending_single_recharge',
+            is_dynamic_pricing: true,
+            exchange_rate: exchangeRateInfo,
+            slippage_check: slippageCheck,
+            pending_amount: pendingAmount,
+            single_recharge_credit: creditAmount.toString(),
+          });
+        }
+      }
+    }
+
     return res.json({
       can_continue: true,
       payment_account_sufficient: true,
       payment_account_balance: balanceResult?.token?.balance || '0',
       pending_amount: pendingAmount,
+      is_dynamic_pricing: isDynamicPricing,
+      ...(exchangeRateInfo && { exchange_rate: exchangeRateInfo }),
+      ...(slippageCheck && { slippage_check: slippageCheck }),
+      can_cover_pending: canCoverPending,
     });
   } catch (err: any) {
     logger.error('check auto recharge failed', {