payment-kit 1.20.13 → 1.20.15

package/api/src/queues/vendors/fulfillment.ts

@@ -7,7 +7,7 @@ import { updateVendorFulfillmentStatus } from './fulfillment-coordinator';
 
 type VendorFulfillmentJob = {
   checkoutSessionId: string;
-  paymentIntentId: string;
+  invoiceId: string;
   vendorId: string;
   vendorConfig: any;
   retryOnError?: boolean;
@@ -19,7 +19,7 @@ export const handleVendorFulfillment = async (job: VendorFulfillmentJob) => {
     jobKeys: Object.keys(job),
   });
 
-  const { checkoutSessionId, paymentIntentId, vendorId, vendorConfig } = job;
+  const { checkoutSessionId, invoiceId, vendorId, vendorConfig } = job;
 
   try {
     const checkoutSession = await CheckoutSession.findByPk(checkoutSessionId);
@@ -31,7 +31,7 @@ export const handleVendorFulfillment = async (job: VendorFulfillmentJob) => {
       checkoutSessionId,
       amount_total: checkoutSession.amount_total,
       customer_id: checkoutSession.customer_id || '',
-      payment_intent_id: checkoutSession.payment_intent_id || '',
+      invoiceId,
       currency_id: checkoutSession.currency_id,
       customer_did: checkoutSession.customer_did || '',
     };
@@ -43,7 +43,7 @@ export const handleVendorFulfillment = async (job: VendorFulfillmentJob) => {
       status: fulfillmentResult.status,
     });
 
-    await updateVendorFulfillmentStatus(checkoutSessionId, paymentIntentId, vendorId, 'sent', {
+    await updateVendorFulfillmentStatus(checkoutSessionId, invoiceId, vendorId, 'sent', {
       orderId: fulfillmentResult.orderId,
       commissionAmount: fulfillmentResult.commissionAmount,
       serviceUrl: fulfillmentResult.serviceUrl,
@@ -55,7 +55,7 @@ export const handleVendorFulfillment = async (job: VendorFulfillmentJob) => {
       error,
     });
 
-    await updateVendorFulfillmentStatus(checkoutSessionId, paymentIntentId, vendorId, 'failed', {
+    await updateVendorFulfillmentStatus(checkoutSessionId, invoiceId, vendorId, 'failed', {
       lastError: error.message,
     });
 

package/api/src/queues/vendors/return-processor.ts

@@ -157,7 +157,6 @@ async function callVendorReturn(
     const returnResult = await vendorAdapter.requestReturn({
       orderId: vendor.order_id,
       reason: 'Subscription canceled',
-      paymentIntentId: checkoutSession.payment_intent_id || '',
       customParams: {
         checkoutSessionId: checkoutSession.id,
         subscriptionId: checkoutSession.subscription_id,

package/api/src/queues/vendors/status-check.ts

@@ -83,7 +83,7 @@ export const handleVendorStatusCheck = async (job: VendorStatusCheckJob) => {
         id: `fulfillment-coordinator-${checkoutSessionId}-${vendorId}`,
         job: {
           checkoutSessionId,
-          paymentIntentId: checkoutSession?.payment_intent_id || '',
+          invoiceId: checkoutSession?.invoice_id || '',
           triggeredBy: 'vendor-status-check-timeout',
         },
       });
@@ -158,7 +158,7 @@ export const handleVendorStatusCheck = async (job: VendorStatusCheckJob) => {
       id: `fulfillment-coordinator-${checkoutSessionId}-${vendorId}`,
       job: {
         checkoutSessionId,
-        paymentIntentId: checkoutSession?.payment_intent_id || '',
+        invoiceId: checkoutSession?.invoice_id || '',
         triggeredBy: 'vendor-status-check',
       },
     });

package/api/src/routes/checkout-sessions.ts

@@ -668,7 +668,9 @@ const getBeneficiaryName = async (beneficiary: PaymentBeneficiary) => {
   return beneficiary.name || (await getUserOrAppInfo(beneficiary.address || ''))?.name || beneficiary.address;
 };
 
-export async function getCrossSellItem(checkoutSession: CheckoutSession) {
+export async function getCrossSellItem(
+  checkoutSession: CheckoutSession
+): Promise<{ error?: string } | (TPriceExpanded & { product: any; error?: string })> {
   // FIXME: perhaps we can support cross sell even if the current session have multiple items
   if (checkoutSession.line_items.length > 1) {
     return { error: 'Cross sell not supported for checkoutSession with multiple line items' };
@@ -2334,8 +2336,12 @@ router.put('/:id/expire', auth, ensureCheckoutSessionOpen, async (req, res) => {
 router.get('/:id/cross-sell', user, ensureCheckoutSessionOpen, async (req, res) => {
   try {
     const checkoutSession = req.doc as CheckoutSession;
+    const skipError = req.query.skipError === 'true';
     const result = await getCrossSellItem(checkoutSession);
-    // @ts-ignore
+
+    if (skipError && result.error) {
+      return res.status(200).json(result);
+    }
     return res.status(result.error ? 400 : 200).json(result);
   } catch (err) {
     logger.error(err);
@@ -2633,6 +2639,10 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       return res.status(400).json({ error: 'Coupon no longer valid' });
     }
 
+    const now = dayjs().unix();
+    const trialSetup = getSubscriptionTrialSetup(checkoutSession.subscription_data as any, currency.id);
+    const isTrialing = trialSetup.trialInDays > 0 || trialSetup.trialEnd > now;
+
     // Apply discount with new currency
     const discountResult = await applyDiscountsToLineItems({
       lineItems: expandedItems,
@@ -2640,6 +2650,9 @@ router.post('/:id/recalculate-promotion', user, ensureCheckoutSessionOpen, async
       couponId,
       customerId: customer.id,
       currency,
+      billingContext: {
+        trialing: isTrialing,
+      },
     });
 
     // Check if discount can still be applied with the new currency

package/api/src/routes/coupons.ts

@@ -373,6 +373,13 @@ router.put('/:id', auth, async (req, res) => {
     return res.status(404).json({ error: 'Coupon not found' });
   }
 
+  if (req.body.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
+  }
+
   if (coupon.locked) {
     const allowedUpdates = pick(value, ['name', 'metadata', 'description']);
     if (Object.keys(allowedUpdates).length === 0) {

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

@@ -11,6 +11,7 @@ import { CreditGrant, Customer, PaymentCurrency, Price, Subscription } from '../
 import { createCreditGrant } from '../libs/credit-grant';
 import { getMeterPriceIdsFromSubscription } from '../libs/subscription';
 import { blocklet } from '../libs/auth';
+import { formatMetadata } from '../libs/util';
 
 const router = Router();
 const auth = authenticate<CreditGrant>({ component: true, roles: ['owner', 'admin'] });
@@ -264,7 +265,13 @@ router.put('/:id', auth, async (req, res) => {
   if (error) {
     return res.status(400).json({ error: `Credit grant update request invalid: ${error.message}` });
   }
-  await creditGrant.update({ metadata: req.body.metadata });
+  if (req.body.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
+  }
+  await creditGrant.update({ metadata: formatMetadata(req.body.metadata) });
   return res.json({ success: true });
 });
 

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

@@ -3,9 +3,18 @@ import Joi from 'joi';
 
 import { Op } from 'sequelize';
 import { createListParamSchema, getOrder, getWhereFromKvQuery } from '../libs/api';
+import { mergePaginate, type DataSource } from '../libs/pagination';
 import logger from '../libs/logger';
 import { authenticate } from '../libs/security';
-import { CreditTransaction, Customer, CreditGrant, Meter, Subscription, PaymentCurrency } from '../store/models';
+import {
+  CreditTransaction,
+  Customer,
+  CreditGrant,
+  Meter,
+  MeterEvent,
+  Subscription,
+  PaymentCurrency,
+} from '../store/models';
 
 const router = Router();
 const authMine = authenticate<CreditTransaction>({ component: true, roles: ['owner', 'admin'], mine: true });
@@ -27,6 +36,7 @@ const listSchema = createListParamSchema<{
   start?: number;
   end?: number;
   source?: string;
+  include_grants?: boolean;
 }>({
   customer_id: Joi.string().empty(''),
   subscription_id: Joi.string().empty(''),
@@ -35,11 +45,13 @@ const listSchema = createListParamSchema<{
   start: Joi.number().integer().optional(),
   end: Joi.number().integer().optional(),
   source: Joi.string().empty(''),
+  include_grants: Joi.boolean().optional(),
 });
 
 router.get('/', authMine, async (req, res) => {
   try {
     const { page, pageSize, ...query } = await listSchema.validateAsync(req.query, { stripUnknown: true });
+    const includeGrants = !!query.include_grants;
     const where = getWhereFromKvQuery(query.q);
 
     if (query.meter_id) {
@@ -73,6 +85,124 @@ router.get('/', authMine, async (req, res) => {
       };
     }
 
+    if (query.start && query.end) {
+      where.created_at = {
+        [Op.between]: [new Date(query.start * 1000), new Date(query.end * 1000)],
+      };
+    }
+
+    if (includeGrants) {
+      if (!query.customer_id) {
+        return res.status(400).json({
+          error: 'customer_id is required when include_grants=true',
+        });
+      }
+
+      const orderDirection = query.o === 'asc' ? 'ASC' : 'DESC';
+
+      const transactionSource: DataSource<any> = {
+        async count() {
+          const count = await CreditTransaction.count({ where });
+          return count;
+        },
+        async fetch(limit, offset) {
+          const rows = await CreditTransaction.findAll({
+            where,
+            limit,
+            offset,
+            order: [['created_at', orderDirection]],
+            include: [
+              { model: Customer, as: 'customer', attributes: ['id', 'name', 'email', 'did'] },
+              { model: Meter, as: 'meter' },
+              { model: Subscription, as: 'subscription', attributes: ['id', 'description', 'status'], required: false },
+              { model: CreditGrant, as: 'creditGrant', attributes: ['id', 'name', 'currency_id'] },
+              { model: MeterEvent, as: 'meterEvent', attributes: ['id', 'source_data'], required: false },
+            ],
+          });
+          // Transform transactions
+          return rows.map((item: any) => ({
+            ...item.toJSON(),
+            activity_type: 'transaction',
+          }));
+        },
+        meta: { type: 'database' },
+      };
+
+      // Grant where conditions
+      const grantWhere: any = {
+        customer_id: query.customer_id,
+        status: ['granted', 'depleted'],
+      };
+      if (query.start) {
+        grantWhere.created_at = {
+          [Op.gte]: new Date(query.start * 1000),
+        };
+      }
+      if (typeof query.livemode === 'boolean') grantWhere.livemode = query.livemode;
+
+      const grantSource: DataSource<any> = {
+        async count() {
+          const { count } = await CreditGrant.findAndCountAll({ where: grantWhere });
+          return count;
+        },
+        async fetch(limit, offset) {
+          const { rows } = await CreditGrant.findAndCountAll({
+            where: grantWhere,
+            limit,
+            offset,
+            order: [['created_at', orderDirection]],
+            include: [
+              { model: Customer, as: 'customer', attributes: ['id', 'name', 'email', 'did'] },
+              {
+                model: PaymentCurrency,
+                as: 'paymentCurrency',
+                attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
+              },
+            ],
+          });
+          // Transform grants
+          return rows.map((item: any) => ({
+            ...item.toJSON(),
+            activity_type: 'grant',
+          }));
+        },
+        meta: { type: 'database' },
+      };
+
+      // Define sort function
+      const sortFn = (a: any, b: any) => {
+        const aDate = new Date(a.created_at).getTime();
+        const bDate = new Date(b.created_at).getTime();
+        return query.o === 'asc' ? aDate - bDate : bDate - aDate;
+      };
+
+      // Use mergePaginate
+      const result = await mergePaginate([transactionSource, grantSource], { page, pageSize }, sortFn);
+
+      // Load payment currencies for final result
+      const paymentCurrencies = await PaymentCurrency.findAll({
+        attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
+        where: { type: 'credit' },
+      });
+
+      const enhancedData = result.data.map((item) => ({
+        ...item,
+        paymentCurrency: paymentCurrencies.find(
+          (x) => x.id === (item.activity_type === 'grant' ? item.currency_id : item.creditGrant?.currency_id)
+        ),
+      }));
+
+      return res.json({
+        count: result.total,
+        list: enhancedData,
+        paging: result.paging,
+        meta: {
+          unified_cash_flow: true,
+          includes: ['transaction', 'grant'],
+        },
+      });
+    }
+
     const { rows: list, count } = await CreditTransaction.findAndCountAll({
       where,
       order: getOrder(query, [['created_at', query.o === 'asc' ? 'ASC' : 'DESC']]),
@@ -97,27 +227,37 @@ router.get('/', authMine, async (req, res) => {
         {
           model: CreditGrant,
           as: 'creditGrant',
-          attributes: ['id', 'name'],
+          attributes: ['id', 'name', 'currency_id'],
+        },
+        {
+          model: MeterEvent,
+          as: 'meterEvent',
+          attributes: ['id', 'source_data'], // Get source_data from related MeterEvent
+          required: false,
         },
       ],
     });
 
     const paymentCurrencies = await PaymentCurrency.findAll({
       attributes: ['id', 'symbol', 'decimal', 'maximum_precision'],
-      where: {
-        type: 'credit',
-      },
+      where: { type: 'credit' },
     });
 
-    const result = list.map((item) => {
-      return {
-        ...item.toJSON(),
-        // @ts-ignore
-        paymentCurrency: paymentCurrencies.find((x) => x.id === item.meter?.currency_id),
-      };
-    });
+    const result = list.map((item) => ({
+      ...item.toJSON(),
+      activity_type: 'transaction',
+      paymentCurrency: paymentCurrencies.find((x) => x.id === (item as any).creditGrant?.currency_id),
+    }));
 
-    return res.json({ count, list: result, paging: { page, pageSize } });
+    return res.json({
+      count,
+      list: result,
+      paging: { page, pageSize },
+      meta: {
+        unified_cash_flow: false,
+        includes: ['transaction'],
+      },
+    });
   } catch (err) {
     logger.error('Error listing credit transactions', err);
     return res.status(400).json({ error: err.message });

package/api/src/routes/invoices.ts

@@ -23,7 +23,15 @@ import { Price } from '../store/models/price';
 import { Product } from '../store/models/product';
 import { Subscription } from '../store/models/subscription';
 import { getReturnStakeInvoices, getStakingInvoices, retryUncollectibleInvoices } from '../libs/invoice';
-import { CheckoutSession, PaymentLink, TInvoiceExpanded, Discount, Coupon, PromotionCode } from '../store/models';
+import {
+  CheckoutSession,
+  PaymentLink,
+  TInvoiceExpanded,
+  Discount,
+  Coupon,
+  PromotionCode,
+  CreditGrant,
+} from '../store/models';
 import { mergePaginate, defaultTimeOrderBy, getCachedOrFetch, DataSource } from '../libs/pagination';
 import logger from '../libs/logger';
 import { returnOverdraftProtectionQueue, returnStakeQueue } from '../queues/subscription';
@@ -678,6 +686,30 @@ router.get('/:id', authPortal, async (req, res) => {
         }
       }
 
+      let relatedCreditGrants: any[] = [];
+      try {
+        relatedCreditGrants = await CreditGrant.findAll({
+          where: {
+            customer_id: doc.customer_id,
+            'metadata.invoice_id': doc.id,
+          } as any,
+          include: [
+            {
+              model: PaymentCurrency,
+              as: 'paymentCurrency',
+              attributes: ['id', 'symbol', 'decimal', 'name', 'type'],
+            },
+          ],
+          order: [['created_at', 'DESC']],
+        });
+      } catch (error) {
+        logger.error('Failed to fetch related credit grants', {
+          error,
+          invoiceId: doc.id,
+          customerId: doc.customer_id,
+        });
+      }
+
       if (doc.metadata?.invoice_id || doc.metadata?.prev_invoice_id) {
         const relatedInvoice = await Invoice.findByPk(doc.metadata.invoice_id || doc.metadata.prev_invoice_id, {
           attributes: ['id', 'number', 'status', 'billing_reason'],
@@ -686,6 +718,7 @@ router.get('/:id', authPortal, async (req, res) => {
           ...json,
           discountDetails,
           relatedInvoice,
+          relatedCreditGrants,
           paymentLink,
           checkoutSession,
         });
@@ -693,6 +726,7 @@ router.get('/:id', authPortal, async (req, res) => {
       return res.json({
         ...json,
         discountDetails,
+        relatedCreditGrants,
         paymentLink,
         checkoutSession,
       });

package/api/src/routes/meter-events.ts

@@ -14,6 +14,32 @@ const router = Router();
 const auth = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'] });
 const authMine = authenticate<MeterEvent>({ component: true, roles: ['owner', 'admin'], mine: true });
 
+const SourceDataSchema = Joi.alternatives()
+  .try(
+    Joi.object().pattern(Joi.string().max(40), Joi.string().max(256).allow('')).min(0),
+    Joi.array()
+      .items(
+        Joi.object({
+          key: Joi.string().max(40).required(),
+          label: Joi.alternatives()
+            .try(
+              Joi.string().max(100),
+              Joi.object({
+                zh: Joi.string().max(100).optional(),
+                en: Joi.string().max(100).optional(),
+              })
+            )
+            .required(),
+          value: Joi.string().max(256).allow('').optional(),
+          type: Joi.string().valid('text', 'image', 'url').optional(),
+          url: Joi.string().uri().optional(),
+          group: Joi.string().max(40).optional(),
+        })
+      )
+      .min(0)
+  )
+  .optional();
+
 const meterEventSchema = Joi.object({
   event_name: Joi.string().max(128).required(),
   payload: Joi.object({
@@ -24,6 +50,7 @@ const meterEventSchema = Joi.object({
   timestamp: Joi.number().integer().optional(),
   identifier: Joi.string().max(255).required(),
   metadata: MetadataSchema,
+  source_data: SourceDataSchema,
 });
 
 const listSchema = createListParamSchema<{
@@ -72,12 +99,12 @@ router.get('/', authMine, async (req, res) => {
     }
 
     if (query.start || query.end) {
-      where.created_at = {};
+      where.timestamp = {};
       if (query.start) {
-        where.created_at[Op.gte] = new Date(query.start * 1000);
+        where.timestamp[Op.gte] = Number(query.start);
       }
       if (query.end) {
-        where.created_at[Op.lte] = new Date(query.end * 1000);
+        where.timestamp[Op.lte] = Number(query.end);
       }
     }
 
@@ -259,6 +286,7 @@ router.post('/', auth, async (req, res) => {
       credit_pending: fromTokenToUnit(value, paymentCurrency.decimal).toString(),
       created_via: req.user?.via || 'api',
       metadata: formatMetadata(req.body.metadata),
+      source_data: req.body.source_data,
       timestamp,
     };
 

package/api/src/routes/meters.ts

@@ -156,6 +156,10 @@ router.put('/:id', auth, async (req, res) => {
     };
 
     if (req.body.metadata) {
+      const { error: metadataError } = MetadataSchema.validate(req.body.metadata);
+      if (metadataError) {
+        return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+      }
       updateData.metadata = formatMetadata(req.body.metadata);
     }
 

package/api/src/routes/payment-currencies.ts

@@ -19,6 +19,7 @@ import { depositVaultQueue } from '../queues/payment';
 import { checkDepositVaultAmount } from '../libs/payment';
 import { getTokenSummaryByDid } from '../integrations/arcblock/stake';
 import { createPaymentLink } from './payment-links';
+import { MetadataSchema } from '../libs/api';
 
 const router = Router();
 
@@ -311,7 +312,7 @@ const updateCurrencySchema = Joi.object({
   name: Joi.string().empty('').max(32).optional(),
   description: Joi.string().empty('').max(255).optional(),
   logo: Joi.string().empty('').optional(),
-  metadata: Joi.object().optional(),
+  metadata: MetadataSchema,
   symbol: Joi.string().empty('').optional(),
 }).unknown(true);
 router.put('/:id', auth, async (req, res) => {

package/api/src/routes/promotion-codes.ts

@@ -8,7 +8,7 @@ import { createIdGenerator, formatMetadata } from '../libs/util';
 import { authenticate } from '../libs/security';
 import { PromotionCode, Coupon, PaymentCurrency } from '../store/models';
 import { getRedemptionData } from '../libs/discount/redemption';
-import { createListParamSchema } from '../libs/api';
+import { createListParamSchema, MetadataSchema } from '../libs/api';
 import logger from '../libs/logger';
 
 const router = Router();
@@ -249,7 +249,7 @@ router.put('/:id', authAdmin, async (req, res) => {
         minimum_amount: Joi.number().positive().optional(),
         minimum_amount_currency: Joi.string().optional(),
       }).optional(),
-      metadata: Joi.object().optional(),
+      metadata: MetadataSchema,
     });
 
     const { error, value } = schema.validate(req.body, {

package/api/src/routes/subscription-items.ts

@@ -139,6 +139,10 @@ router.put('/:id', auth, async (req, res) => {
   }
 
   if (updates.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(updates.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
     updates.metadata = formatMetadata(updates.metadata);
   }
 

package/api/src/routes/vendor.ts

@@ -355,9 +355,12 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
     };
   }
 
+  // FIXME: will remove payment_status @pengfei
+  const paymentStatus = doc.status === 'complete' ? 'paid' : 'unpaid';
+
   if (doc.status !== 'complete') {
     return {
-      payment_status: doc.payment_status,
+      payment_status: paymentStatus,
       session_status: doc.status,
       error: 'CheckoutSession not complete',
       vendors: [],
@@ -365,7 +368,7 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
   }
   if (!doc.vendor_info) {
     return {
-      payment_status: doc.payment_status,
+      payment_status: paymentStatus,
       session_status: doc.status,
       error: 'Vendor info not found',
       vendors: [],
@@ -373,7 +376,13 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
   }
 
   const vendors = doc.vendor_info.map((item) => {
-    return getVendorStatusByVendorId(item.vendor_id, item.order_id, isDetail);
+    return getVendorStatusByVendorId(item.vendor_id, item.order_id, isDetail).then((status) => {
+      return {
+        error_message: item.error_message,
+        status: item.status,
+        ...status,
+      };
+    });
   });
 
   const subscriptionId = doc.subscription_id;
@@ -390,7 +399,7 @@ async function getVendorStatus(sessionId: string, isDetail = false) {
   }
 
   return {
-    payment_status: doc.payment_status,
+    payment_status: paymentStatus,
     session_status: doc.status,
     subscriptionUrl: shortSubscriptionUrl,
     vendors: await Promise.all(vendors),

package/api/src/routes/webhook-endpoints.ts

@@ -100,6 +100,10 @@ router.put('/:id', auth, async (req, res) => {
     'enabled_events',
   ]);
   if (updates.metadata) {
+    const { error: metadataError } = MetadataSchema.validate(updates.metadata);
+    if (metadataError) {
+      return res.status(400).json({ error: `metadata invalid: ${metadataError.message}` });
+    }
     updates.metadata = formatMetadata(updates.metadata);
   }
 

package/api/src/store/migrations/20250919-add-source-data.ts

@@ -0,0 +1,20 @@
+import { DataTypes } from 'sequelize';
+import { Migration, safeApplyColumnChanges } from '../migrate';
+
+export const up: Migration = async ({ context }) => {
+  await safeApplyColumnChanges(context, {
+    meter_events: [
+      {
+        name: 'source_data',
+        field: {
+          type: DataTypes.JSON,
+          allowNull: true,
+        },
+      },
+    ],
+  });
+};
+
+export const down: Migration = async ({ context }) => {
+  await context.removeColumn('meter_events', 'source_data');
+};

package/api/src/store/models/checkout-session.ts

@@ -623,6 +623,29 @@ export class CheckoutSession extends Model<InferAttributes<CheckoutSession>, Inf
       return null;
     }
   }
+
+  public static async findByInvoiceId(invoiceId: string): Promise<CheckoutSession | null> {
+    try {
+      const invoice = await Invoice.findByPk(invoiceId);
+      if (!invoice) {
+        return null;
+      }
+
+      if (invoice.checkout_session_id) {
+        return await CheckoutSession.findByPk(invoice.checkout_session_id);
+      }
+
+      if (!invoice.subscription_id) {
+        return null;
+      }
+
+      // Find original CheckoutSession through subscription
+      const checkoutSession = await CheckoutSession.findBySubscriptionId(invoice.subscription_id);
+      return checkoutSession;
+    } catch (error: any) {
+      return null;
+    }
+  }
 }
 
 export type TCheckoutSession = InferAttributes<CheckoutSession>;