feat(billing): webhook hardening — 9 reliability improvements (#3598)

1. Pin Stripe API version to 2026-04-22.dahlia
2. Read current_period_start/end from items.data[0] (Stripe ≥2025-08-27) with top-level fallback
3. Dead-letter protection: track attempts; dead-letter at ≥5, skip rollback, return 200 to Stripe
4. Per-family event ordering guards: separate lastSubscriptionEvent* / lastInvoiceEvent* fields
5. Fail-closed for paused/unpaid/incomplete_expired status in meter mode
6. Refund backfill: fetch PaymentIntent when stripeSessionId missing from charge metadata
7. Integer-cents math for refund proportional calculation (no IEEE 754 drift)
8. Stable extras checkout idempotency key via optional intentId parameter
9. Server-side active-sub guard in createCheckout via live stripe.subscriptions.list call

Author: PierreBrisorgueil

modules/billing/controllers/billing.controller.js

@@ -133,8 +133,8 @@ const getUsage = async (req, res) => {
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js controller, not Qwik
 const extrasCheckout = async (req, res) => {
   try {
-    const { packId, successUrl, cancelUrl } = req.body;
-    const result = await BillingService.createExtrasCheckout(req.organization, packId, successUrl, cancelUrl);
+    const { packId, successUrl, cancelUrl, intentId } = req.body;
+    const result = await BillingService.createExtrasCheckout(req.organization, packId, successUrl, cancelUrl, intentId);
     responses.success(res, 'extras checkout session created')(result);
   } catch (err) {
     const status = err.message?.startsWith('Invalid') || err.message?.includes('not found') ? 422 : 502;

modules/billing/lib/events.js

@@ -15,6 +15,9 @@ import { EventEmitter } from 'events';
  *     Payload: { organizationId, idempotencyKey, extrasUnits, attempts, lastError }
  *   - `payment.failed`  — emitted when an invoice payment fails (pastDueSince set on first failure)
  *     Payload: { organizationId }
+ *   - `billing.refund.unresolved` — emitted when a charge.refunded event cannot be correlated
+ *     to a known session/org (missing metadata on charge AND PaymentIntent, or ambiguous pack).
+ *     Payload: { chargeId, paymentIntentId, refundAmount } | { reason, orgId, stripeSessionId, amountRefundedCents }
  */
 const billingEvents = new EventEmitter();
 

modules/billing/lib/stripe.js

@@ -17,7 +17,7 @@ let stripeClient = null;
 const getStripe = () => {
   if (stripeClient) return stripeClient;
   if (!config.stripe?.secretKey) return null;
-  stripeClient = new Stripe(config.stripe.secretKey);
+  stripeClient = new Stripe(config.stripe.secretKey, { apiVersion: '2026-04-22.dahlia' });
   return stripeClient;
 };
 

modules/billing/middlewares/billing.requireQuota.js

@@ -57,6 +57,36 @@ function requireQuota(resource, action) {
 
         // ── Degraded-mode gate (past_due grace period) ─────────────────────
         const subscription = await SubscriptionRepository.findByOrganization(req.organization._id);
+
+        // Fail-closed statuses: paused, unpaid, incomplete_expired → always route to free quota.
+        // These statuses fire as customer.subscription.updated (status field changes), so they
+        // arrive here while the subscription doc may still hold a paid-tier meterQuota.
+        // Resetting to zero prevents paid-quota bleed-through on lapsed subscriptions.
+        const failClosedStatuses = ['paused', 'unpaid', 'incomplete_expired'];
+        if (subscription && failClosedStatuses.includes(subscription.status)) {
+          const planId = getDefaultPlanId();
+          const freePlan = BillingPlanService.getActivePlan(planId);
+          if (!freePlan) {
+            return responses.error(res, 503, 'Service Unavailable', 'Billing plan configuration is temporarily unavailable')({
+              type: 'PLAN_NOT_CONFIGURED',
+              planId,
+            });
+          }
+          const extrasBalance = await BillingExtraBalanceRepository.getBalance(orgId);
+          const remaining = (freePlan.meterQuota ?? 0) + extrasBalance;
+          if (remaining <= 0) {
+            return responses.error(res, 402, 'Payment Required', 'Meter exhausted')({
+              type: 'METER_EXHAUSTED',
+              meterUsed: 0,
+              meterQuota: freePlan.meterQuota ?? 0,
+              extrasRemaining: extrasBalance,
+              packsAvailable: config.billing?.packs ?? [],
+              upgradeUrl: config.billing?.upgradeUrl ?? '/billing/plans',
+            });
+          }
+          return next();
+        }
+
         if (subscription?.status === 'past_due' && subscription.pastDueSince != null) {
           const gracePeriodMs = getGracePeriodDays() * 24 * 60 * 60 * 1000;
           const elapsed = Date.now() - new Date(subscription.pastDueSince).getTime();

modules/billing/models/billing.processedStripeEvent.model.mongoose.js

@@ -30,6 +30,36 @@ const ProcessedStripeEventMongoose = new Schema(
       required: true,
       default: () => new Date(),
     },
+    /**
+     * Number of handler execution attempts (including failed ones).
+     * Incremented on each handler exception before deciding to rollback or dead-letter.
+     */
+    attempts: {
+      type: Number,
+      default: 0,
+    },
+    /**
+     * Last handler error message — set when the handler throws.
+     */
+    lastError: {
+      type: String,
+      default: null,
+    },
+    /**
+     * Timestamp of the last handler error.
+     */
+    lastErrorAt: {
+      type: Date,
+      default: null,
+    },
+    /**
+     * When true, the event has exceeded max retry attempts.
+     * The claim is kept permanently so Stripe stops retrying.
+     */
+    deadLetter: {
+      type: Boolean,
+      default: false,
+    },
   },
   {
     timestamps: false,

modules/billing/models/billing.processedStripeEvent.schema.js

@@ -11,6 +11,10 @@ const ProcessedStripeEvent = z.object({
   eventId: z.string().trim().min(1, 'eventId is required'),
   type: z.string().trim().min(1, 'type is required'),
   processedAt: z.coerce.date().default(() => new Date()),
+  attempts: z.number().int().nonnegative().default(0),
+  lastError: z.string().nullable().optional(),
+  lastErrorAt: z.coerce.date().nullable().optional(),
+  deadLetter: z.boolean().default(false),
 });
 
 const ProcessedStripeEventCreate = z.object({

modules/billing/models/billing.subscription.model.mongoose.js

@@ -83,11 +83,45 @@ const SubscriptionMongoose = new Schema(
     /**
      * Stripe event.id of the last processed subscription event.
      * Tiebreaker for same-second events (lex string ordering on evt_ IDs).
+     * @deprecated use lastSubscriptionEventCreatedAt / lastInvoiceEventCreatedAt per-family fields.
      */
     stripeEventId: {
       type: String,
       default: null,
     },
+
+    // ── Per-family event ordering guards ─────────────────────────────────────
+    // Separate trackers for 'subscription' vs 'invoice' event families prevent
+    // same-second cross-family deliveries from cancelling each other's state.
+
+    /**
+     * Stripe event.created (Unix seconds) of the last processed customer.subscription.* event.
+     */
+    lastSubscriptionEventCreatedAt: {
+      type: Number,
+      default: null,
+    },
+    /**
+     * Stripe event.id of the last processed customer.subscription.* event (same-second tiebreaker).
+     */
+    lastSubscriptionEventId: {
+      type: String,
+      default: null,
+    },
+    /**
+     * Stripe event.created (Unix seconds) of the last processed invoice.* event.
+     */
+    lastInvoiceEventCreatedAt: {
+      type: Number,
+      default: null,
+    },
+    /**
+     * Stripe event.id of the last processed invoice.* event (same-second tiebreaker).
+     */
+    lastInvoiceEventId: {
+      type: String,
+      default: null,
+    },
   },
   {
     timestamps: true,

modules/billing/models/billing.subscription.schema.js

@@ -26,6 +26,11 @@ const baseShape = {
   lastResetAt: z.coerce.date().nullable().optional(),
   stripeEventCreatedAt: z.number().int().nullable().optional(),
   stripeEventId: z.string().nullable().optional(),
+  // Per-family event ordering guards
+  lastSubscriptionEventCreatedAt: z.number().int().nullable().optional(),
+  lastSubscriptionEventId: z.string().nullable().optional(),
+  lastInvoiceEventCreatedAt: z.number().int().nullable().optional(),
+  lastInvoiceEventId: z.string().nullable().optional(),
 };
 
 const Subscription = z.object({
@@ -73,6 +78,9 @@ const ExtrasCheckoutRequest = z
     packId: z.string().trim().min(1, 'packId is required'),
     successUrl: z.string().url('successUrl must be a valid URL'),
     cancelUrl: z.string().url('cancelUrl must be a valid URL'),
+    // Caller-provided stable intent ID for idempotency (prevents double-click double-charge).
+    // When absent, a soft-stable minute-bucketed key is used as fallback.
+    intentId: z.string().min(1).optional(),
   })
   .strict();
 

modules/billing/repositories/billing.processedStripeEvent.repository.js

@@ -74,8 +74,52 @@ const deleteByEventId = async (eventId) => {
   return { deleted: result.deletedCount > 0 };
 };
 
+/**
+ * @function incrementAttempts
+ * @description Atomically increment the attempts counter and record the last error details
+ *              on the processed event document. Used by withIdempotency to track retry depth.
+ * @param {string} eventId - Stripe event ID.
+ * @param {string} errorMessage - Error message from the last failed handler execution.
+ * @returns {Promise<Object|null>} Updated document or null if not found.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
+const incrementAttempts = async (eventId, errorMessage) => {
+  if (typeof eventId !== 'string' || eventId.trim() === '') {
+    throw new Error('invalid argument: eventId must be a non-empty string');
+  }
+  return ProcessedStripeEvent().findOneAndUpdate(
+    { eventId },
+    {
+      $inc: { attempts: 1 },
+      $set: { lastError: String(errorMessage ?? ''), lastErrorAt: new Date() },
+    },
+    { returnDocument: 'after' },
+  ).exec();
+};
+
+/**
+ * @function markDeadLetter
+ * @description Mark a processed event as dead-lettered — keeps the claim permanently so
+ *              Stripe stops retrying, and sets deadLetter=true for ops visibility.
+ * @param {string} eventId - Stripe event ID.
+ * @returns {Promise<Object|null>} Updated document or null if not found.
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
+const markDeadLetter = async (eventId) => {
+  if (typeof eventId !== 'string' || eventId.trim() === '') {
+    throw new Error('invalid argument: eventId must be a non-empty string');
+  }
+  return ProcessedStripeEvent().findOneAndUpdate(
+    { eventId },
+    { $set: { deadLetter: true } },
+    { returnDocument: 'after' },
+  ).exec();
+};
+
 export default {
   tryRecord,
   wasProcessed,
   deleteByEventId,
+  incrementAttempts,
+  markDeadLetter,
 };

modules/billing/repositories/billing.subscription.repository.js

@@ -214,38 +214,59 @@ const markUnpaid = (id, threshold) => {
 /**
  * @function updateIfEventNewer
  * @description Atomically update a subscription only when the incoming Stripe event is newer
- *              than the last processed event. Prevents out-of-order webhook delivery from
- *              overwriting more-recent state.
+ *              than the last processed event for the given family.
+ *              Prevents out-of-order webhook delivery from overwriting more-recent state.
  *              Same-second events are ordered by lex-string comparison of event IDs (evt_ prefix
  *              makes these globally deterministic within a second) — V5 P1 #2 tiebreaker.
+ *
+ *              The `family` parameter scopes the event-ordering guard to either the
+ *              'subscription' family (customer.subscription.*) or the 'invoice' family
+ *              (invoice.*).  Same-second cross-family deliveries no longer cancel each other.
+ *              Falls back to legacy stripeEventCreatedAt/stripeEventId for back-compat when
+ *              per-family fields are not yet populated (gradual migration — no down-time).
+ *
  *              Returns null when the guard prevents the write (stale event).
  * @param {string} id - The subscription ObjectId (string).
  * @param {number} eventCreatedAt - Stripe event.created Unix timestamp (seconds).
  * @param {string} eventId - Stripe event.id (e.g. evt_xxx) — tiebreaker for same-second delivery.
  * @param {Object} fields - Fields to $set on the document.
+ * @param {'subscription'|'invoice'} [family='subscription'] - Event family to scope the ordering guard.
  * @returns {Promise<Object|null>} Updated doc, or null if id invalid or event is stale.
  */
 // biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Node.js repository, not Qwik
-const updateIfEventNewer = (id, eventCreatedAt, eventId, fields) => {
+const updateIfEventNewer = (id, eventCreatedAt, eventId, fields, family = 'subscription') => {
   if (!id || !mongoose.Types.ObjectId.isValid(id)) return null;
+
+  const createdAtField = family === 'invoice' ? 'lastInvoiceEventCreatedAt' : 'lastSubscriptionEventCreatedAt';
+  const eventIdField = family === 'invoice' ? 'lastInvoiceEventId' : 'lastSubscriptionEventId';
+
   return Subscription.findOneAndUpdate(
     {
       _id: id,
       $or: [
-        { stripeEventCreatedAt: { $exists: false } },
-        { stripeEventCreatedAt: null },
-        { stripeEventCreatedAt: { $lt: eventCreatedAt } },
+        { [createdAtField]: { $exists: false } },
+        { [createdAtField]: null },
+        { [createdAtField]: { $lt: eventCreatedAt } },
         {
-          stripeEventCreatedAt: eventCreatedAt,
+          [createdAtField]: eventCreatedAt,
           $or: [
-            { stripeEventId: { $exists: false } },
-            { stripeEventId: null },
-            { stripeEventId: { $lt: eventId } },
+            { [eventIdField]: { $exists: false } },
+            { [eventIdField]: null },
+            { [eventIdField]: { $lt: eventId } },
           ],
         },
       ],
     },
-    { $set: { ...fields, stripeEventCreatedAt: eventCreatedAt, stripeEventId: eventId } },
+    {
+      $set: {
+        ...fields,
+        [createdAtField]: eventCreatedAt,
+        [eventIdField]: eventId,
+        // Keep legacy fields in sync for back-compat with existing queries / reports
+        stripeEventCreatedAt: eventCreatedAt,
+        stripeEventId: eventId,
+      },
+    },
     { returnDocument: 'after', runValidators: true },
   )
     .populate(defaultPopulate)