refactor(billing): improve promo code usage creation logic and enhance subscription renewal handling in CloudPayments

Author: Dobrunia

src/billing/cloudpayments.ts

@@ -210,6 +210,17 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
+    /**
+     * Validates recurrent.amount for the first subscription payment when promo is applied.
+     *
+     * CloudPayments flows:
+     * 1. First charge via widget — body.Data is present, checksum may include promo.id and
+     *    cloudPayments.recurrent.amount. Discount applies only to body.Amount (first charge).
+     *    recurrent.amount must stay equal to full plan.monthlyCharge so later renewals bill full price.
+     * 2. Monthly renewals — body.Data is absent, getDataFromRequest() resolves workspace by
+     *    SubscriptionId only, data.promo is undefined, this block is skipped, and amount must
+     *    equal plan.monthlyCharge (see isRightAmount above).
+     */
     if (
       data.promo &&
       recurrentPaymentSettings?.amount !== undefined &&
@@ -358,22 +369,12 @@ export default class CloudPaymentsWebhooks {
     if (data.promo && !data.isCardLinkOperation) {
       try {
         const promoCodeService = new PromoCodeService(req.context.factories);
-        const promoPricing = await promoCodeService.getPricingForPromoCodeId(
-          data.promo.id,
-          data.userId,
-          data.workspaceId,
-          tariffPlan
-        );
 
         await promoCodeService.createUsage({
-          promoCode: promoPricing.promoCode,
+          promoCodeId: data.promo.id,
           userId: data.userId,
           workspaceId: workspace._id,
-          planId: tariffPlan._id,
-          benefitType: promoPricing.benefitType,
-          originalAmount: promoPricing.originalAmount,
-          finalAmount: promoPricing.finalAmount,
-          discountAmount: promoPricing.discountAmount,
+          plan: tariffPlan,
           utm: data.promo.utm,
         });
       } catch (error) {
@@ -838,8 +839,8 @@ status: ${body.Status}`
     const body: CheckRequest | PayRequest | FailRequest = req.body;
 
     /**
-     * If Data is not presented in body means there is a recurring payment
-     * Data field is presented only in one-time payment requests or subscription initial request
+     * If Data is absent, this is a subscription renewal (or check/pay identified by SubscriptionId).
+     * Renewals do not carry promo: discount was applied only on the first widget payment.
      */
     if (body.Data) {
       const parsedData = JSON.parse(body.Data || '{}') as WebhookData;

src/models/promoCodeUsagesFactory.ts

@@ -3,6 +3,18 @@ import PromoCodeUsageModel from './promoCodeUsage';
 import { Collection, Db, ObjectId } from 'mongodb';
 import { PromoCodeUsageDBScheme } from '@hawk.so/types';
 
+/**
+ * Input for creating promo usage with MongoDB driver ObjectId instances.
+ */
+export type PromoCodeUsageCreateInput = Omit<
+  PromoCodeUsageDBScheme,
+  '_id' | 'promoCodeId' | 'workspaceId' | 'planId'
+> & {
+  promoCodeId: ObjectId;
+  workspaceId: ObjectId;
+  planId?: ObjectId;
+};
+
 /**
  * Promo code usages factory to work with promoCodeUsages collection.
  */
@@ -74,14 +86,14 @@ export default class PromoCodeUsagesFactory extends AbstractModelFactory<PromoCo
    *
    * @param usageData - promo code usage data
    */
-  public async create(usageData: Omit<PromoCodeUsageDBScheme, '_id'>): Promise<PromoCodeUsageModel> {
+  public async create(usageData: PromoCodeUsageCreateInput): Promise<PromoCodeUsageModel> {
     const usage = {
       _id: new ObjectId(),
       ...usageData,
     };
 
-    await this.collection.insertOne(usage);
+    await this.collection.insertOne(usage as PromoCodeUsageDBScheme);
 
-    return new PromoCodeUsageModel(usage);
+    return new PromoCodeUsageModel(usage as PromoCodeUsageDBScheme);
   }
 }

src/services/promoCodeService.ts

@@ -322,37 +322,38 @@ export default class PromoCodeService {
   /**
    * Creates usage after successful payment.
    *
+   * Re-validates promo by id, resolves pricing for the selected plan, and stores usage.
    * Unique indexes on promoCodeId + userId/workspaceId enforce one usage per user/workspace.
-   * Usage is recorded after plan change in CloudPayments /pay.
    *
    * @param params - usage creation params
    * @returns created promo usage
    */
   public async createUsage(params: {
-    promoCode: PromoCodeModel;
+    promoCodeId: string;
     userId: string;
     workspaceId: ObjectId;
-    planId?: ObjectId;
-    benefitType: PromoCodeBenefitType;
-    originalAmount?: number;
-    finalAmount?: number;
-    discountAmount?: number;
+    plan: PlanModel;
     utm?: PromoCodeUtm;
   }): Promise<PromoCodeUsageModel> {
-    await this.validateUsageLimits(params.promoCode, params.userId, params.workspaceId);
+    const promoPricing = await this.getPricingForPromoCodeId(
+      params.promoCodeId,
+      params.userId,
+      params.workspaceId.toString(),
+      params.plan
+    );
 
     const utm = sanitizeUtmParams(params.utm);
 
     try {
       return await this.factories.promoCodeUsagesFactory.create({
-        promoCodeId: params.promoCode._id,
+        promoCodeId: promoPricing.promoCode._id,
         userId: params.userId,
         workspaceId: params.workspaceId,
-        planId: params.planId,
-        benefitType: params.benefitType,
-        originalAmount: params.originalAmount,
-        finalAmount: params.finalAmount,
-        discountAmount: params.discountAmount,
+        planId: params.plan._id,
+        benefitType: promoPricing.benefitType,
+        originalAmount: promoPricing.originalAmount,
+        finalAmount: promoPricing.finalAmount,
+        discountAmount: promoPricing.discountAmount,
         appliedAt: new Date(),
         ...(utm ? { utm } : {}),
       });

test/billing/cloudpayments.test.ts

@@ -592,6 +592,36 @@ describe('CloudPaymentsWebhooks', () => {
       expect(res.json).toHaveBeenCalledWith({ code: CheckCodes.SUCCESS });
     });
 
+    it('should accept full plan amount on subscription renewal check without promo in Data', async () => {
+      const webhooks = new CloudPaymentsWebhooks() as any;
+      const workspaceId = new ObjectId().toString();
+      const userId = new ObjectId().toString();
+      const plan = createPlan(1000);
+      const { context, workspace } = createWebhookContext({
+        workspaceId,
+        userId,
+        plan,
+        subscriptionId: 'subscription-id',
+      });
+
+      context.factories.workspacesFactory.findBySubscriptionId = jest.fn().mockResolvedValue(workspace);
+
+      const res = createMockResponse();
+
+      await webhooks.check({
+        context,
+        body: {
+          ...createCheckBody(1010, '1000', ''),
+          SubscriptionId: 'subscription-id',
+          AccountId: userId,
+          Data: undefined,
+        },
+      }, res);
+
+      expect(context.factories.workspacesFactory.findBySubscriptionId).toHaveBeenCalledWith('subscription-id');
+      expect(res.json).toHaveBeenCalledWith({ code: CheckCodes.SUCCESS });
+    });
+
     it('should reject wrong amount when promo is not applied', async () => {
       const webhooks = new CloudPaymentsWebhooks() as any;
       const workspaceId = new ObjectId().toString();
@@ -689,11 +719,9 @@ describe('CloudPaymentsWebhooks', () => {
 
       expect(changePlan).toHaveBeenCalledWith(plan._id);
       expect(createUsage).toHaveBeenCalledWith(expect.objectContaining({
+        promoCodeId: promoCode._id.toString(),
         userId,
-        benefitType: 'percent_discount',
-        originalAmount: 1000,
-        finalAmount: 750,
-        discountAmount: 250,
+        plan: expect.objectContaining({ _id: plan._id }),
       }));
       expect(publish).toHaveBeenCalled();
       expect(sendNotification).toHaveBeenCalledWith(

test/services/promoCodeService.test.ts

@@ -269,36 +269,58 @@ describe('PromoCodeService', () => {
   });
 
   describe('createUsage()', () => {
+    it('should resolve pricing by promo id and create usage record', async () => {
+      const plan = createPlan({ monthlyCharge: 1000 });
+      const promoCode = createPromoCode({
+        type: 'percent_discount',
+        percent: 25,
+      });
+      const service = createService(promoCode, { plan });
+
+      const usage = await service.createUsage({
+        promoCodeId: promoCode._id.toString(),
+        userId: new ObjectId().toString(),
+        workspaceId: new ObjectId(),
+        plan,
+      });
+
+      expect(usage).toMatchObject({ _id: expect.any(ObjectId) });
+    });
+
     it('should map duplicate usage creation to limit exceeded error', async () => {
+      const plan = createPlan({ monthlyCharge: 1000 });
       const promoCode = createPromoCode({
         type: 'fixed_price',
         amount: 100,
       });
       const service = new PromoCodeService({
+        promoCodesFactory: {
+          findOne: jest.fn().mockResolvedValue(promoCode),
+        },
         promoCodeUsagesFactory: {
           countByPromoCodeId: jest.fn().mockResolvedValue(0),
           findByPromoCodeAndUser: jest.fn().mockResolvedValue(null),
           findByPromoCodeAndWorkspace: jest.fn().mockResolvedValue(null),
           create: jest.fn().mockRejectedValue({ code: 11000 }),
         },
+        plansFactory: {
+          findById: jest.fn().mockResolvedValue(plan),
+        },
       } as any);
 
       await expectPromoError(
         service.createUsage({
-          promoCode,
+          promoCodeId: promoCode._id.toString(),
           userId: new ObjectId().toString(),
           workspaceId: new ObjectId(),
-          planId: new ObjectId(),
-          benefitType: 'fixed_price',
-          originalAmount: 1000,
-          finalAmount: 100,
-          discountAmount: 900,
+          plan,
         }),
         PromoCodeErrorCode.LimitExceeded
       );
     });
 
     it('should reject second createUsage when insert returns duplicate key', async () => {
+      const plan = createPlan({ monthlyCharge: 1000 });
       const promoCode = createPromoCode({
         type: 'fixed_price',
         amount: 100,
@@ -307,22 +329,24 @@ describe('PromoCodeService', () => {
         .mockResolvedValueOnce({ _id: new ObjectId() })
         .mockRejectedValueOnce({ code: 11000 });
       const service = new PromoCodeService({
+        promoCodesFactory: {
+          findOne: jest.fn().mockResolvedValue(promoCode),
+        },
         promoCodeUsagesFactory: {
           countByPromoCodeId: jest.fn().mockResolvedValue(0),
           findByPromoCodeAndUser: jest.fn().mockResolvedValue(null),
           findByPromoCodeAndWorkspace: jest.fn().mockResolvedValue(null),
           create,
         },
+        plansFactory: {
+          findById: jest.fn().mockResolvedValue(plan),
+        },
       } as any);
       const usageParams = {
-        promoCode,
+        promoCodeId: promoCode._id.toString(),
         userId: new ObjectId().toString(),
         workspaceId: new ObjectId(),
-        planId: new ObjectId(),
-        benefitType: 'fixed_price' as const,
-        originalAmount: 1000,
-        finalAmount: 100,
-        discountAmount: 900,
+        plan,
       };
 
       await service.createUsage(usageParams);