fix(billing): add checkout metadata, harden webhook and customer creation (#3265)

* fix(billing): add checkout metadata, harden webhook and customer creation

- Add organizationId and plan metadata to Stripe checkout sessions (#3259)
- Wrap SubscriptionRepository.create in try/catch for duplicate key race condition (#3260)
- Fallback to stripeCustomerId lookup when checkout metadata is missing (#3261)
- Remove Stripe error details from webhook signature failure response (#3262)

Closes #3259, closes #3260, closes #3261, closes #3262

* fix(billing): address review feedback on metadata and fallback

- Use planId instead of name for checkout metadata plan field
- Fix webhook fallback to extract organization._id from populated doc
- Use destructured stripeCustomerId for consistency in fallback
- Update test mocks to reflect populated organization shape

Author: PierreBrisorgueil

modules/billing/controllers/billing.webhook.controller.js

@@ -39,7 +39,7 @@ const handleWebhook = async (req, res) => {
   try {
     event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
   } catch (err) {
-    return res.status(400).json({ error: `Webhook signature verification failed: ${err.message}` });
+    return res.status(400).json({ error: 'Webhook signature verification failed' });
   }
 
   try {

modules/billing/services/billing.service.js

@@ -85,22 +85,37 @@ const createCheckout = async (organization, priceId, successUrl, cancelUrl) => {
         stripeCustomerId: customer.id,
       });
     } else {
-      subscription = await SubscriptionRepository.create({
-        organization: organization._id,
-        stripeCustomerId: customer.id,
-      });
+      try {
+        subscription = await SubscriptionRepository.create({
+          organization: organization._id,
+          stripeCustomerId: customer.id,
+        });
+      } catch (err) {
+        if (err.code === 11000) {
+          subscription = await SubscriptionRepository.findByOrganization(organization._id);
+        } else {
+          throw err;
+        }
+      }
     }
     // Re-read to handle race: if another request already set stripeCustomerId, use that
     const latest = await SubscriptionRepository.findByOrganization(organization._id);
     if (latest?.stripeCustomerId) subscription = latest;
   }
 
+  // Derive plan name from priceId for checkout metadata
+  const matchedPlan = plans.find((p) => p.stripePriceMonthly === priceId || p.stripePriceAnnual === priceId);
+
   const session = await stripe.checkout.sessions.create({
     customer: subscription.stripeCustomerId,
     mode: 'subscription',
     line_items: [{ price: priceId, quantity: 1 }],
     success_url: successUrl,
     cancel_url: cancelUrl,
+    metadata: {
+      organizationId: String(organization._id),
+      plan: matchedPlan?.planId || 'free',
+    },
   });
 
   return session.url;

modules/billing/services/billing.webhook.service.js

@@ -37,9 +37,15 @@ const syncOrganizationPlan = async (organizationId, plan) => {
  */
 const handleCheckoutCompleted = async (session) => {
   const { customer: stripeCustomerId, subscription: stripeSubscriptionId, metadata } = session;
-  const organizationId = metadata?.organizationId;
+  let organizationId = metadata?.organizationId;
   const plan = metadata?.plan || 'free';
 
+  // Fallback: resolve organizationId from stripeCustomerId if metadata is missing
+  if (!organizationId) {
+    const sub = await SubscriptionRepository.findByStripeCustomerId(stripeCustomerId);
+    if (sub) organizationId = String(sub.organization?._id || sub.organization);
+  }
+
   if (!organizationId || !mongoose.Types.ObjectId.isValid(organizationId)) return;
 
   const existing = await SubscriptionRepository.findByOrganization(organizationId);

modules/billing/tests/billing.checkout.unit.tests.js

@@ -15,8 +15,8 @@ describe('Billing service unit tests:', () => {
   const orgId = '507f1f77bcf86cd799439011';
   const mockOrganization = { _id: orgId, name: 'Test Org' };
   const validPlans = [
-    { planId: 'starter', stripePriceMonthly: 'price_starter_m', stripePriceAnnual: 'price_starter_y' },
-    { planId: 'pro', stripePriceMonthly: 'price_pro_m', stripePriceAnnual: 'price_pro_y' },
+    { planId: 'starter', name: 'Starter', stripePriceMonthly: 'price_starter_m', stripePriceAnnual: 'price_starter_y' },
+    { planId: 'pro', name: 'Pro', stripePriceMonthly: 'price_pro_m', stripePriceAnnual: 'price_pro_y' },
   ];
 
   beforeEach(async () => {
@@ -204,6 +204,10 @@ describe('Billing service unit tests:', () => {
         line_items: [{ price: 'price_starter_m', quantity: 1 }],
         success_url: 'http://ok',
         cancel_url: 'http://cancel',
+        metadata: {
+          organizationId: orgId,
+          plan: 'starter',
+        },
       });
     });
   });

modules/billing/tests/billing.controller.unit.tests.js

@@ -77,7 +77,7 @@ describe('Billing webhook controller unit tests:', () => {
     await BillingWebhookController.handleWebhook(req, res);
 
     expect(res.status).toHaveBeenCalledWith(400);
-    expect(res.json).toHaveBeenCalledWith({ error: 'Webhook signature verification failed: bad signature' });
+    expect(res.json).toHaveBeenCalledWith({ error: 'Webhook signature verification failed' });
   });
 
   test('should handle checkout.session.completed event', async () => {

modules/billing/tests/billing.service.unit.tests.js

@@ -20,6 +20,7 @@ describe('Billing webhook service unit tests:', () => {
     mockSubscriptionRepository = {
       findByOrganization: jest.fn(),
       findByStripeSubscriptionId: jest.fn(),
+      findByStripeCustomerId: jest.fn(),
       create: jest.fn(),
       update: jest.fn(),
     };
@@ -108,18 +109,41 @@ describe('Billing webhook service unit tests:', () => {
       );
     });
 
-    test('should return early when organizationId is missing', async () => {
+    test('should return early when organizationId is missing and no customer fallback', async () => {
+      mockSubscriptionRepository.findByStripeCustomerId.mockResolvedValue(null);
+
       const mod = await import('../services/billing.webhook.service.js');
       BillingWebhookService = mod.default;
 
       await BillingWebhookService.handleCheckoutCompleted({
-        customer: 'cus_123',
+        customer: 'cus_unknown',
         subscription: 'sub_456',
         metadata: {},
       });
 
+      expect(mockSubscriptionRepository.findByStripeCustomerId).toHaveBeenCalledWith('cus_unknown');
       expect(mockSubscriptionRepository.findByOrganization).not.toHaveBeenCalled();
     });
+
+    test('should fallback to stripeCustomerId when organizationId is missing in metadata', async () => {
+      mockSubscriptionRepository.findByStripeCustomerId.mockResolvedValue({ organization: { _id: orgId } });
+      mockSubscriptionRepository.findByOrganization.mockResolvedValue(null);
+      mockSubscriptionRepository.create.mockResolvedValue({});
+
+      const mod = await import('../services/billing.webhook.service.js');
+      BillingWebhookService = mod.default;
+
+      await BillingWebhookService.handleCheckoutCompleted({
+        customer: 'cus_123',
+        subscription: 'sub_456',
+        metadata: {},
+      });
+
+      expect(mockSubscriptionRepository.findByStripeCustomerId).toHaveBeenCalledWith('cus_123');
+      expect(mockSubscriptionRepository.create).toHaveBeenCalledWith(
+        expect.objectContaining({ organization: orgId }),
+      );
+    });
   });
 
   describe('handleSubscriptionUpdated', () => {