feat(billing): enhance promo validation and payment processing logic in CloudPayments integration

Author: Dobrunia

src/billing/cloudpayments.ts

@@ -164,11 +164,10 @@ export default class CloudPaymentsWebhooks {
     let promoPricing;
 
     /**
-     * Record promo usage before applying paid benefits.
+     * Revalidate promo before accepting payment.
      *
-     * /pay runs after CloudPayments has accepted the charge, but workspace plan
-     * must not be changed if promo usage cannot be stored. Otherwise a transient
-     * DB/limit error would grant a discounted plan without consuming the promo.
+     * Amount check uses server-side pricing; usage is recorded later in /pay
+     * after workspace plan is updated successfully.
      */
     if (data.promo && !data.isCardLinkOperation) {
       try {
@@ -211,6 +210,21 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
+    if (
+      data.promo &&
+      recurrentPaymentSettings?.amount !== undefined &&
+      +recurrentPaymentSettings.amount !== plan.monthlyCharge
+    ) {
+      this.sendError(
+        res,
+        CheckCodes.WRONG_AMOUNT,
+        '[Billing / Check] Recurrent amount must equal full plan price when promo is applied',
+        body
+      );
+
+      return;
+    }
+
     /**
      * Create business operation about creation of subscription
      */
@@ -308,36 +322,6 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
-    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,
-          userId: data.userId,
-          workspaceId: workspace._id,
-          planId: tariffPlan._id,
-          benefitType: promoPricing.benefitType,
-          originalAmount: promoPricing.originalAmount,
-          finalAmount: promoPricing.finalAmount,
-          discountAmount: promoPricing.discountAmount,
-          utm: data.promo.utm,
-        });
-      } catch (e) {
-        const error = e as Error;
-
-        this.sendError(res, PayCodes.SUCCESS, `[Billing / Pay] Failed to record promo usage: ${error.toString()}`, body);
-
-        return;
-      }
-    }
-
     try {
       await businessOperation.setStatus(BusinessOperationStatus.Confirmed);
 
@@ -371,6 +355,32 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
+    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,
+          userId: data.userId,
+          workspaceId: workspace._id,
+          planId: tariffPlan._id,
+          benefitType: promoPricing.benefitType,
+          originalAmount: promoPricing.originalAmount,
+          finalAmount: promoPricing.finalAmount,
+          discountAmount: promoPricing.discountAmount,
+          utm: data.promo.utm,
+        });
+      } catch (error) {
+        console.error('[Billing / Pay] Failed to record promo usage after plan change', error);
+      }
+    }
+
     // let accountId = workspace.accountId;
 
     /*

src/resolvers/billingNew.ts

@@ -17,7 +17,7 @@ import { TelegramBotURLs } from '../utils/telegram';
 import PromoCodeService, { PromoCodeError, PromoCodeErrorCode, PromoCodePreviewResult, buildPaymentPromoData } from '../services/promoCodeService';
 import { publish } from '../rabbitmq';
 import type { PaymentPromoData } from '../billing/types/paymentData';
-import { validateUtmParams } from '../utils/utm/utm';
+import { sanitizeUtmParams } from '../utils/utm/utm';
 
 /**
  * The amount we will debit to confirm the subscription.
@@ -108,7 +108,7 @@ async function previewOrApplyPromoCode(
     input.value,
     userId,
     workspace,
-    validateUtmParams(input.utm)
+    sanitizeUtmParams(input.utm)
   );
 
   await notifyLimiterToUnblockWorkspace(workspace._id.toString());
@@ -171,6 +171,7 @@ export default {
     ): Promise<{
       invoiceId: string;
       plan: { id: string; name: string; monthlyCharge: number };
+      chargeAmount: number;
       isCardLinkOperation: boolean;
       currency: string;
       checksum: string;
@@ -185,7 +186,7 @@ export default {
       };
     }> {
       const { workspaceId, tariffPlanId, shouldSaveCard, promoCode } = input;
-      const promoUtm = validateUtmParams(input.promoUtm);
+      const promoUtm = sanitizeUtmParams(input.promoUtm);
 
       if (!workspaceId || !tariffPlanId || !user?.id) {
         throw new UserInputError('No workspaceId, tariffPlanId or user id provided');
@@ -294,8 +295,9 @@ debug: ${Boolean(workspace.isDebug)}`
         plan: {
           id: plan._id.toString(),
           name: plan.name,
-          monthlyCharge: paymentAmount,
+          monthlyCharge: plan.monthlyCharge,
         },
+        chargeAmount: isCardLinkOperation ? AMOUNT_FOR_CARD_VALIDATION : paymentAmount,
         isCardLinkOperation,
         currency: 'RUB',
         checksum,
@@ -472,6 +474,7 @@ debug: ${Boolean(workspace.isDebug)}`
           recurrent: {
             interval,
             period: 1,
+            amount: plan.monthlyCharge,
           },
         };
 
@@ -481,7 +484,6 @@ debug: ${Boolean(workspace.isDebug)}`
          */
         if (!isTariffPlanExpired) {
           jsonData.cloudPayments.recurrent.startDate = dueDate.toDateString();
-          jsonData.cloudPayments.recurrent.amount = planPaymentAmount;
         }
       }
 

src/services/promoCodeService.ts

@@ -10,6 +10,7 @@ import WorkspaceModel from '../models/workspace';
 import { ContextFactories } from '../types/graphql';
 import type { Utm } from '@hawk.so/types';
 import type { PaymentPromoData } from '../billing/types/paymentData';
+import { sanitizeUtmParams } from '../utils/utm/utm';
 
 const PROMO_CODE_REGEXP = /^[A-Z0-9_-]+$/;
 const DEFAULT_MIN_FINAL_PRICE = 1;
@@ -347,9 +348,11 @@ function validateBenefitStructure(benefit: PromoCodeBenefit): void {
  * @returns promo reference for payment checksum
  */
 export function buildPaymentPromoData(promoCodeId: string, utm?: Utm): PaymentPromoData {
+  const sanitizedUtm = sanitizeUtmParams(utm);
+
   return {
     id: promoCodeId,
-    ...(utm && Object.keys(utm).length > 0 ? { utm } : {}),
+    ...(sanitizedUtm ? { utm: sanitizedUtm } : {}),
   };
 }
 
@@ -502,53 +505,41 @@ export default class PromoCodeService {
       throw new PromoCodeError(PromoCodeErrorCode.Invalid, 'Grant plan is unavailable');
     }
 
+    const now = new Date();
+
+    try {
+      await workspace.updatePlanHistory(workspace.tariffPlanId.toString(), now, userId);
+      await workspace.updateLastChargeDate(now);
+      await workspace.changePlan(plan._id);
+    } catch (error) {
+      if (error instanceof PromoCodeError) {
+        throw error;
+      }
+
+      throw new PromoCodeError(PromoCodeErrorCode.ApplyFailed, 'Grant plan apply failed');
+    }
+
     try {
-      const now = new Date();
-
-      /**
-       * Reserve usage before granting the plan.
-       *
-       * This makes promo usage a precondition for the benefit: if limits are exhausted
-       * or the insert fails, workspace state is not changed.
-       */
-      const usage = await this.createUsage({
+      await this.createUsage({
         promoCode,
         userId,
         workspaceId: workspace._id,
         planId: plan._id,
         benefitType: promoCode.benefit.type,
         utm,
       });
-
-      try {
-        await workspace.updatePlanHistory(workspace.tariffPlanId.toString(), now, userId);
-        await workspace.updateLastChargeDate(now);
-        await workspace.changePlan(plan._id);
-      } catch (error) {
-        try {
-          await this.factories.promoCodeUsagesFactory.deleteById(usage._id);
-        } catch (rollbackError) {
-          console.error('Failed to rollback promo usage after grant_plan apply failure', rollbackError);
-        }
-
-        throw error;
-      }
-
-      return plan;
     } catch (error) {
-      if (error instanceof PromoCodeError) {
-        throw error;
-      }
-
-      throw new PromoCodeError(PromoCodeErrorCode.ApplyFailed, 'Grant plan apply failed');
+      console.error('[PromoCode] Failed to record promo usage after grant_plan apply', error);
     }
+
+    return plan;
   }
 
   /**
    * Creates usage after successful payment or before immediate grant_plan apply.
    *
-   * Unique indexes on promoCodeId + userId/workspaceId make this method the durable
-   * reservation point. Callers should grant the promo benefit only after it succeeds.
+   * Unique indexes on promoCodeId + userId/workspaceId enforce one usage per user/workspace.
+   * Usage is recorded after plan change in CloudPayments /pay and grant_plan apply.
    *
    * @param params - usage creation params
    * @returns created promo usage
@@ -566,6 +557,8 @@ export default class PromoCodeService {
   }): Promise<PromoCodeUsageModel> {
     await this.validateUsageLimits(params.promoCode, params.userId, params.workspaceId);
 
+    const utm = sanitizeUtmParams(params.utm);
+
     try {
       return await this.factories.promoCodeUsagesFactory.create({
         promoCodeId: params.promoCode._id,
@@ -577,7 +570,7 @@ export default class PromoCodeService {
         finalAmount: params.finalAmount,
         discountAmount: params.discountAmount,
         appliedAt: new Date(),
-        ...(params.utm && Object.keys(params.utm).length > 0 ? { utm: params.utm } : {}),
+        ...(utm ? { utm } : {}),
       });
     } catch (error) {
       if ((error as { code?: number }).code === 11000) {

src/typeDefs/billing.ts

@@ -49,7 +49,7 @@ type ComposePaymentPlanInfo {
   name: String!
 
   """
-  Monthly charge for plan
+  Monthly charge for plan (full tariff price)
   """
   monthlyCharge: Int!
 }
@@ -386,6 +386,11 @@ type ComposePaymentResponse {
   """
   plan: ComposePaymentPlanInfo!
 
+  """
+  Amount to charge for this payment (may differ from plan.monthlyCharge when promo is applied)
+  """
+  chargeAmount: Int!
+
   """
   True if only card linking validation payment is expected
   """

src/utils/utm/utm.ts

@@ -62,3 +62,18 @@ export function validateUtmParams(utm: unknown): Utm | undefined {
 
   return result;
 }
+
+/**
+ * Returns sanitized UTM params ready for storage, or undefined when nothing valid remains.
+ *
+ * @param utm - raw UTM parameters
+ */
+export function sanitizeUtmParams(utm: unknown): Utm | undefined {
+  const validated = validateUtmParams(utm);
+
+  if (!validated || Object.keys(validated).length === 0) {
+    return undefined;
+  }
+
+  return validated;
+}