refactor(billing): enhance CloudPayments webhook handling and improve documentation for payment processing and subscription renewals

Author: Dobrunia

src/billing/cloudpayments.ts

@@ -102,9 +102,15 @@ export default class CloudPaymentsWebhooks {
   }
 
   /**
-   * Route to confirm the correctness of a user's payment
+   * Route to confirm that CloudPayments may process the payment.
    * https://developers.cloudpayments.ru/#check
    *
+   * This route handles both the first widget payment and later subscription charges.
+   * The first widget payment sends signed Data with billing intent and optional promo.
+   * Later recurrent charges may arrive without Data; in that case we resolve the
+   * workspace and current plan by SubscriptionId and validate the amount against
+   * the full plan price.
+   *
    * @param req - cloudpayments request with payment details
    * @param res - check result code
    */
@@ -642,9 +648,15 @@ subscription id: ${body.SubscriptionId}`;
   }
 
   /**
-   * Route is executed if the status of the recurring payment subscription has been changed.
+   * Route executed when a CloudPayments subscription status changes.
    * https://developers.cloudpayments.ru/#recurrent
    *
+   * This notification is about the subscription entity, not a replacement for
+   * /check or /pay transaction notifications. CloudPayments identifies which
+   * charge number this is via SuccessfulTransactionsNumber and sends the
+   * subscription Id; our transaction handlers use that Id to find the workspace.
+   * Promo data is not expected here and is not applied to subscription renewals.
+   *
    * @param req - cloudpayments request with subscription details
    * @param res - result code
    */
@@ -830,7 +842,17 @@ status: ${body.Status}`
   }
 
   /**
-   * Parses request body and returns data from it
+   * Parses CloudPayments request body into the signed billing intent.
+   *
+   * First widget payments include Data.checksum generated by composePayment; the
+   * checksum is the only trusted source for workspaceId, tariffPlanId, userId,
+   * shouldSaveCard, and promo id. Unsigned widget Data fields must not override it.
+   *
+   * Recurrent subscription renewals usually do not include Data. For those
+   * requests CloudPayments sends SubscriptionId and AccountId, so we restore the
+   * workspace and current plan by SubscriptionId. Because there is no signed promo
+   * in this path, data.promo is intentionally absent: promo discounts are applied
+   * only to the first widget payment, while renewals are charged at full plan price.
    *
    * @param req - request with necessary data
    */

src/billing/types/paymentData.ts

@@ -20,7 +20,8 @@ interface RecurrentPaymentSettings {
   startDate?: string;
 
   /**
-   * Recurring payment amount.
+   * Recurring payment amount for automatic subscription renewals.
+   * Keep it equal to the full plan price even when the first widget charge uses a promo.
    */
   amount?: number;
 }
@@ -38,8 +39,9 @@ interface CloudPaymentsSettings {
 }
 
 /**
- * Promo reference attached to payment request.
+ * Promo reference attached to the signed first payment request.
  * Amounts are resolved on the server by promo id during check/pay.
+ * Recurrent renewals are restored by SubscriptionId and do not carry promo data.
  */
 export interface PaymentPromoData {
   /**

test/billing/cloudpayments.test.ts

@@ -166,7 +166,7 @@ function createCheckBody(transactionId: number, amount: string, data: string) {
   };
 }
 
-function createPayBody(transactionId: number, amount: string, data: string, overrides: Record<string, unknown> = {}) {
+function createPayBody(transactionId: number, amount: string, data?: string, overrides: Record<string, unknown> = {}) {
   return {
     TransactionId: transactionId,
     Amount: amount,
@@ -758,6 +758,37 @@ describe('CloudPaymentsWebhooks', () => {
       expect(res.json).toHaveBeenCalledWith({ code: PayCodes.SUCCESS });
     });
 
+    it('should complete subscription renewal without Data and without promo usage', async () => {
+      const webhooks = new CloudPaymentsWebhooks() as any;
+      const workspaceId = new ObjectId().toString();
+      const userId = new ObjectId().toString();
+      const plan = createPlan(1000);
+      const { context, workspace, changePlan, createUsage } = createWebhookContext({
+        workspaceId,
+        userId,
+        plan,
+        subscriptionId: 'subscription-id',
+      });
+
+      context.factories.workspacesFactory.findBySubscriptionId = jest.fn().mockResolvedValue(workspace);
+
+      const res = createMockResponse();
+
+      await webhooks.pay({
+        context,
+        body: createPayBody(2004, '1000', undefined, {
+          AccountId: userId,
+          Data: undefined,
+          SubscriptionId: 'subscription-id',
+        }),
+      }, res);
+
+      expect(context.factories.workspacesFactory.findBySubscriptionId).toHaveBeenCalledWith('subscription-id');
+      expect(changePlan).toHaveBeenCalledWith(plan._id);
+      expect(createUsage).not.toHaveBeenCalled();
+      expect(res.json).toHaveBeenCalledWith({ code: PayCodes.SUCCESS });
+    });
+
     it('should cancel old subscription when a new subscription id is received', async () => {
       const webhooks = new CloudPaymentsWebhooks() as any;
       const workspaceId = new ObjectId().toString();
@@ -775,7 +806,7 @@ describe('CloudPaymentsWebhooks', () => {
 
       await webhooks.pay({
         context,
-        body: createPayBody(2004, '1000', Data, { SubscriptionId: 'new-subscription' }),
+        body: createPayBody(2005, '1000', Data, { SubscriptionId: 'new-subscription' }),
       }, res);
 
       expect(cloudPaymentsClientMocks.cancelSubscription).toHaveBeenCalledWith({ Id: 'old-subscription' });
@@ -807,10 +838,10 @@ describe('CloudPaymentsWebhooks', () => {
         },
       });
 
-      await webhooks.pay({ context, body: createPayBody(2005, '1', Data) }, res);
+      await webhooks.pay({ context, body: createPayBody(2006, '1', Data) }, res);
 
       expect(changePlan).not.toHaveBeenCalled();
-      expect(cloudPaymentsApi.cancelPayment).toHaveBeenCalledWith(2005);
+      expect(cloudPaymentsApi.cancelPayment).toHaveBeenCalledWith(2006);
       expect(createBusinessOperation).toHaveBeenCalledWith(expect.objectContaining({
         type: BusinessOperationType.CardLinkRefund,
         status: BusinessOperationStatus.Confirmed,
@@ -831,7 +862,7 @@ describe('CloudPaymentsWebhooks', () => {
 
       (publish as jest.Mock).mockRejectedValueOnce(new Error('rabbit down'));
 
-      await webhooks.pay({ context, body: createPayBody(2006, '1000', Data) }, res);
+      await webhooks.pay({ context, body: createPayBody(2007, '1000', Data) }, res);
 
       expect(res.json).toHaveBeenCalledWith({ code: PayCodes.SUCCESS });
     });
@@ -848,7 +879,7 @@ describe('CloudPaymentsWebhooks', () => {
 
       (sendNotification as jest.Mock).mockRejectedValueOnce(new Error('notify failed'));
 
-      await webhooks.pay({ context, body: createPayBody(2007, '1000', Data) }, res);
+      await webhooks.pay({ context, body: createPayBody(2008, '1000', Data) }, res);
 
       expect(res.json).toHaveBeenCalledWith({ code: PayCodes.SUCCESS });
     });

test/integration/cases/billing/promo.test.ts

@@ -58,19 +58,19 @@ describe('Promo billing webhooks', () => {
    * Insert a document and load the persisted record.
    * Throws if insert or read fails — keeps fixture setup explicit in tests.
    */
-  async function insertAndLoad<T extends { _id?: ObjectId }, R extends T>(
-    collection: Collection<T>,
-    document: Omit<T, '_id'>,
+  async function insertAndLoad<R extends { _id: ObjectId }>(
+    collection: Collection<any>,
+    document: Omit<R, '_id'>,
     errorMessage: string
   ): Promise<R> {
-    const insertedId = (await collection.insertOne(document as T)).insertedId;
-    const result = await collection.findOne({ _id: insertedId } as Partial<T>);
+    const insertedId = (await collection.insertOne(document)).insertedId;
+    const result = await collection.findOne({ _id: insertedId });
 
     if (!result) {
       throw new Error(errorMessage);
     }
 
-    return result as R;
+    return result as unknown as R;
   }
 
   /**
@@ -95,7 +95,7 @@ describe('Promo billing webhooks', () => {
         name: 'PromoBillingTest',
         accountId: '123',
         tariffPlanId: currentPlanId,
-      } as WorkspaceDBScheme,
+      } as Omit<WorkspaceDBScheme, '_id'>,
       'Failed to create workspace'
     );
 
@@ -241,6 +241,7 @@ describe('Promo billing webhooks', () => {
           OperationType: OperationType.PAYMENT,
           Status: OperationStatus.COMPLETED,
           TestMode: false,
+          TotalFee: 0,
           TransactionId: transactionId,
           Token: '123123',
           IssuerBankCountry: 'US',