Add promo code support to billing API by alisawavezen12 · Pull Request #685 · codex-team/hawk.api.nodejs

alisawavezen12 · 2026-10-14T12:19:53Z

Add promo code validation, plan restrictions, and discounted payment amounts. Reserve promo codes for payments and handle successful and failed payment callbacks.

Related changes in Web: codex-team/hawk.garage#927

neSpecc · 2026-10-21T16:36:48Z

+  /**
+   * Signed amount of the current promo payment in rubles
+   */
+  paymentAmount?: number;
+  /**
+   * Signed promo payment attempt, also used as the business operation ID.
+   */
+  promoPaymentId?: string;
+  /**
+   * Signed identifier of the promo code applied to this payment.
+   */
+  promoCodeId?: string;
+  /**
+   * Signed full plan price in rubles before the discount.
+   */
+  originalAmount?: number;
+  /**
+   * Signed percentage discount captured when the quote was prepared.
+   */
+  discountPercent?: number;
+  /**
+   * Signed start date for future full-price payments
+   */
+  nextPaymentDate?: string;


If these fields related to the new promo codes feature, it's better to wrap them to the promo wrapper.

If they are used for regular payments as well, it should be explained, why they was added.

neSpecc · 2026-10-21T16:42:36Z

+      const promoCode = await db.collection('promoCodes').findOne({ _id: new ObjectId(payment.promoCodeId) });
+
+      if (!promoCode) {
+        throw new Error('PROMO_CODE_INVALID');
+      }
+
+      await findActivePromoCode(db, promoCode.value, plan._id);
+      await checkPromoCodeUsage(db, promoCode._id, new ObjectId(data.userId), workspace._id, payment.transactionId);
+
+      await db.collection('businessOperations').updateOne({


it's strange that one level contains both request/response handling, business logic and db queries.

As i can see, we don't use such a code organization pattern in other methods in this file.

neSpecc · 2026-10-21T16:43:37Z

+   * @param payment - validated promo payment
+   * @returns matching business operation
+   */
+  private async getPromoBusinessOperation(req: express.Request, payment: PromoPayment): Promise<BusinessOperationModel> {


i'm not sure it's a good to pass the whole request here. Pass exact arguments instead.

neSpecc · 2026-10-21T16:46:00Z

+   * @param data - verified payment data
+   * @param succeeded - whether the provider reported a successful payment
+   */
+  private async finishPromoPayment(


this method seems to be too big. It also mixes request/response, db queries, etc. Consider how to make it more understandable.

neSpecc · 2026-10-21T16:46:44Z

+  }
+
+  /**
+   * Retry cancellation without touching the subscription selected by a newer payment.


Description is not clear. Describe the use case (shortly).

neSpecc · 2026-10-21T16:46:57Z

+  }
+
+  /**
+   * Renew callback ownership and fence writes from an expired handler.


neSpecc

Overall, the promo logic itself mostly works and is covered by tests, but a few things need to change before merging.

1. The PR changes the regular payment flow, not only promo. Regular /pay and /recurrent were rewritten (see the inline comments). This is the main risk, so please revert them to the master logic. If regular payments need idempotency or handling of out-of-order callbacks, let's do that in a separate PR with its own tests. The existing integration tests in test/integration/cases/billing pass, but they don't cover subscription replacement and cancellation, so green CI doesn't prove the regular flow is safe.

2. Suggested shape of the feature. A promo code should only change the price and reuse the existing flow:

composePayment: get a quote from a promo code service and put promo: { ... } into the checksum;
/check: expectedAmount = data.promo ? data.promo.finalAmount : plan.monthlyCharge, plus a check that the code can still be used. The business operation is created through the factory as usual;
/pay: the regular flow plus if (data.promo) redeem(...) (safe to repeat thanks to the unique index). The receipt uses the amount actually paid;
/fail: no changes.

DB access should go through PromoCodesFactory / PromoCodeRedemptionsFactory, like the other models, and domain functions shouldn't receive req / res. This removes finishPromoPayment and its own lease mechanism, which duplicates /pay and /fail (plan change, unblock, notifications, receipt, card saving) and will drift from them with every change.

3. payWithCard ignores the promo code. It charges the full price, so /check rejects the payment with WRONG_AMOUNT. Garage doesn't call it now, but let's explicitly reject promo checksums there.

neSpecc · 2026-10-21T19:23:03Z

+      if (!businessOperation._id) {
+        throw new Error('Business operation has no id');
      }

-      const subscriptionId = body.SubscriptionId;
-
-      /**
-       * Cancellation of the current subscription if:
-       * 1) the user pays manually (the workspace has an active subscription, but the request body does not)
-       * 2) if payment is made for another subscription (subscriptions id are not equal)
-       */
-      if (workspace.subscriptionId) {
-        if (!subscriptionId || subscriptionId !== workspace.subscriptionId) {
-          await this.clientApi.cancelSubscription({
-            Id: workspace.subscriptionId,
-          });
-        }
-      }
-
-      if (subscriptionId) {
-        await workspace.setSubscriptionId(subscriptionId);
-      }
+      await applyPaidPlan(
+        this.getPromoDatabase(), workspace._id, tariffPlan._id,
+        businessOperation._id, businessOperation.dtCreated,
+        body.SubscriptionId || null, data.isCardLinkOperation
+      );
+      await this.cancelSupersededSubscriptions(workspace._id);
+      await businessOperation.setStatus(BusinessOperationStatus.Confirmed);


This changes the regular (non-promo) payment flow. workspace.changePlan() and the subscription cancel/replace logic are replaced with applyPaidPlan() from promoCodes/, and every payment now writes new workspace fields (billingPaymentId, billingPaymentDate, cardLinkPaymentId, cardLinkPaymentDate, subscriptionIdsToCancel) that are not in WorkspaceDBScheme.

Also, the result of applyPaidPlan() is ignored. If its conditions don't match (e.g. the workspace lastChargeDate is later than the operation's dtCreated), it updates nothing and returns false, but we still confirm the operation, unblock the workspace and tell the user the payment succeeded. On master the plan was always applied.

Please keep the master logic here.

neSpecc · 2026-10-21T19:23:03Z

      const error = e as Error;

-      this.sendError(res, PayCodes.SUCCESS, `[Billing / Pay] Can't update workspace billing data ${error.toString()}`, body);
+      this.sendError(res.status(500), PayCodes.SUCCESS, `[Billing / Pay] Can't update workspace billing data ${error.toString()}`, body);


HTTP 500 changes the retry behaviour for all regular payments: CloudPayments will start re-sending /pay. At the same time the body says code: 0 (success). If we want retries for regular payments, that should be a separate decision, not part of the promo feature.

neSpecc · 2026-10-21T19:23:03Z

+          await this.getPromoDatabase().collection('workspaces')
+            .updateOne({
+              _id: workspace._id,
+              subscriptionId: body.Id,
+            }, {
+              $unset: { subscriptionId: '' },
+            });


This is regular subscription handling, unrelated to promo codes. It's now a raw DB query in the webhook layer instead of workspace.setSubscriptionId(null). If we need "unset only if the id still matches", let's add it to WorkspaceModel in a separate PR.

neSpecc · 2026-10-21T19:23:03Z

+   *
+   * @returns connected accounts database
+   */
+  private getPromoDatabase(): Db {


The name says "promo", but it returns the shared accounts DB and is also used by regular /pay and /recurrent. I'd remove it and work with collections through models/factories, like the rest of this file.

neSpecc · 2026-10-21T19:23:03Z

+   * @param data - parsed payment data
+   * @returns signed payment details
+   */
+  private getPromoPayment(body: CheckRequest | PayRequest | FailRequest, data: PaymentData): PromoPayment {


This is a mapper rather than a getter, so buildPromoPayment would be clearer.

neSpecc · 2026-10-21T19:23:04Z

+  /**
+   * Signed discounted amount in rubles.
+   */
+  paymentAmount: number;


paymentAmount (checksum) and finalAmount (quote, redemption) are the same value under two names, and amount next to it is easy to confuse with them. Let's use one name, e.g. finalAmount, and call the callback value something like paidAmount.

neSpecc · 2026-10-21T19:23:04Z

+/**
+ * Check successful uses only. Parallel payments may both pass before either succeeds.
+ *
+ * @param db - accounts database
+ * @param promoCodeId - selected code
+ * @param userId - payer
+ * @param workspaceId - paid workspace
+ * @param transactionId - same successful callback retry, if present
+ */
+export async function checkPromoCodeUsage(


The function throws when the code can't be used, so assertPromoCodeNotUsed / ensurePromoCodeAvailable would be clearer. The description talks about race conditions rather than what the function is for.

neSpecc · 2026-10-21T19:23:04Z

+
+  const maxUses = getMaxUses(promoCode.maxUses);
+
+  if (maxUses !== undefined && await redemptions.countDocuments({ promoCodeId }) + 1 > maxUses) {


maxUses is checked only before the payment and not atomically, so parallel payments can exceed the limit. If that's acceptable, let's make it an explicit product decision.

neSpecc · 2026-10-21T19:23:04Z

+/**
+ * Calculate a signed quote without writing a usage record.
+ *
+ * @param db - accounts database
+ * @param input - requested payment
+ * @returns discounted quote
+ */
+export async function preparePromoCode(db: Db, input: PromoCodeInput): Promise<PromoCodeQuote> {


The description says "signed quote", but the function doesn't sign anything: it calculates the discounted price. Something like calculatePromoQuote would be clearer.

neSpecc · 2026-10-21T19:23:04Z

+/**
+ * Validate the signed quote against the successful payment callback.
+ *
+ * @param payment - signed identity and provider callback fields
+ */
+export function validatePromoPayment(payment: PromoPayment): void {


The description says "against the successful payment callback", but this is also called in /check.

neSpecc

Thanks, all previous comments are addressed. The regular /check, /pay, /fail and /recurrent flow now matches master apart from the separate data.promo blocks, and the promo logic goes through the factories.

A few things left, see inline. The main one is payload.userId in cloudpayments.ts, the rest are naming and descriptions.

neSpecc · 2026-10-28T14:39:31Z

          amount: +body.Amount * PENNY_MULTIPLIER,
          currency: body.Currency,
-          userId: member._id,
+          userId: data.promo ? member.userId : member._id,


Now the same field means different things depending on the promo code: for regular payments it's the team membership _id (as in master), for promo payments it's the user id.

In this repo, userId of a plan purchase is read only by the new validatePromoOperation(). I'd keep member._id for all payments and drop the userId comparison there: transactionId, workspace, plan and amount are enough to match the operation, and the redemption already gets the user id from the signed checksum. If we want to store the real user id, let's change it for all payments in a separate PR.

neSpecc · 2026-10-28T14:39:31Z

+   *
+   * @param payment - verified signed quote and provider callback fields
+   */
+  public async ensurePaymentAvailable(payment: PromoPayment): Promise<void> {


It's hard to tell from the name what "payment available" means, and the description explains how the method works rather than what it's for. Something like ensurePromoCodeStillValid() with "Re-check in /check that the paid amount matches the signed price and the code can still be used for this plan, payer and workspace".

neSpecc · 2026-10-28T14:39:31Z

+   * Read legacy percentage documents without changing stored data.
+   *
+   * @param query - indexed code or identifier lookup
+   * @param tariffPlanId - selected plan
+   */
+  private async findActivePromoCode(query: Filter<PromoCode>, tariffPlanId: ObjectId): Promise<PromoCode> {
+    const promoCode = await this.collection.findOne(query);
+
+    ensureActivePromoCode(promoCode, tariffPlanId);
+
+    /*
+     * shortcut: support discountPercent until existing documents have been migrated to discount.
+     */
+    const legacy = promoCode as PromoCode & { discountPercent?: number };
+
+    if (promoCode.discount === undefined && typeof legacy.discountPercent === 'number') {
+      return {
+        ...promoCode,
+        discount: {
+          type: 'percent',
+          value: legacy.discountPercent,
+        },
+      };
+    }


The promoCodes collection is created by this PR, so production has no discountPercent documents. If there are some on stage, let's update them by hand and remove this shim.

Then the description can say what the method is for, e.g. "Find a promo code that can be applied to the selected plan, or throw".

neSpecc · 2026-10-28T14:39:31Z

+   * @param identity - payer and paid workspace
+   * @param transactionId - provider transaction on callback retries
+   */
+  public async ensurePromoCodeAvailable(


This method has the same name as the pure ensurePromoCodeAvailable() from promoCodes/redemptions.ts that it calls, so at a call site it's unclear which one is used. Maybe rename the pure one, e.g. validatePromoCodeUsage().

Also, the description says what the method doesn't do instead of what it's for. Something like "Throw if this payer or workspace has already used the code, or the code has reached maxUses".

neSpecc · 2026-10-28T14:39:31Z

@@ -0,0 +1,151 @@
+import { ObjectId } from 'mongodb';


After the refactoring this file contains promo payment types and validators, while redemptions live in PromoCodeRedemptionsFactory. A name like promoCodes/validation.ts would match the content better.

neSpecc · 2026-10-28T14:39:31Z

+    payload.workspaceId.toString() !== payment.workspaceId ||
+    payload.userId.toString() !== payment.userId ||
+    payload.tariffPlanId.toString() !== payment.tariffPlanId ||
+    payload.amount !== payment.paidAmount * 100 || payload.currency !== payment.currency) {


Let's use PENNY_MULTIPLIER instead of 100, like cloudpayments.ts does when it creates this operation (it would need to be moved to a shared place).

neSpecc · 2026-10-28T14:39:31Z

+  /**
+   * Retry a promo callback whose successful usage could not be persisted.
+   */
+  RETRY = 1,


CloudPayments describes only code: 0 for Pay notifications, and the retry is triggered by the non-200 HTTP status, not by the code. Also, PayCodes is shared by all payments, while the description ties this value to promo codes.

I'd drop RETRY and keep res.status(500) with a comment at the call site in /pay.

neSpecc · 2026-10-28T14:39:31Z

+  promo?: PromoPaymentData;
+  /**
+   * Subscription start date signed by composePayment for plan purchases and card linking.
+   * Kept outside promo because regular payments use it too; promo /check also


Regular payments don't read nextPaymentDate: composePayment only signs it into the checksum, and the only reader is validatePromoSubscription(). Let's describe what the field is, e.g. "Start date of the subscription created after this payment", without the claim about regular payments.

alisawavezen12 and others added 10 commits October 13, 2026 14:17

step 1

7534e06

redemptions

8b42f9f

chore

6b5988f

chore

a2e1536

chore

68ec256

chore

51647cb

lint fix

ea0aa88

chore

e1b3003

Merge branch 'master' into feat/promocodes

0b8a222

Bump version up to 1.6.1

0fc4e66

neSpecc reviewed Oct 21, 2026

View reviewed changes

alisawavezen12 added 3 commits October 27, 2026 22:36

fix

4386d72

chore

8698c72

Sign subscription dates in payment checksums

7b4bac5

neSpecc reviewed Oct 28, 2026

View reviewed changes


		const maxUses = getMaxUses(promoCode.maxUses);

		if (maxUses !== undefined && await redemptions.countDocuments({ promoCodeId }) + 1 > maxUses) {

Conversation

alisawavezen12 commented Oct 14, 2026 • edited by neSpecc Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neSpecc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neSpecc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alisawavezen12 commented Oct 14, 2026 •

edited by neSpecc

Loading