fix(billing): convert cents to units in creditDisputeReinstated (#3625)

V8 audit C5: amountCents was passed directly to creditCompensation
instead of being converted to meter units. Adds getDollarsToUnitRatio()
conversion (default 1000 → 5000 cents = 50,000 units) + audit-trail
logging of both amountCents and creditUnits for traceability.

Author: PierreBrisorgueil

modules/billing/services/billing.admin.service.js

@@ -9,6 +9,7 @@ import ProcessedStripeEventRepository from '../repositories/billing.processedStr
 import OrganizationRepository from '../../organizations/repositories/organizations.repository.js';
 import BillingExtraBalanceRepository from '../repositories/billing.extraBalance.repository.js';
 import BillingWebhookService from './billing.webhook.service.js';
+import { getDollarsToUnitRatio } from '../lib/billing.constants.js';
 
 /**
  * Valid plan names from config (immutable set for O(1) lookups).
@@ -296,13 +297,12 @@ const cancelSubscription = async (orgId) => {
  *              Idempotent: `refundRequestId` is used as the idempotency key so double-clicking
  *              the admin UI never produces a double credit.
  *
- *              Audit trail: logs adminUserId + chargeId + amountCents on every call.
+ *              Audit trail: logs adminUserId + chargeId + amountCents + creditUnits on every call.
  *
  * @param {string} chargeId - Stripe charge ID (ch_xxx) to correlate with the dispute.
- * @param {number} amountCents - Amount to credit in cents (positive integer). Converted to
- *                               meter units by a 1:1 mapping — callers should pass the
- *                               dispute amount or a proportion; the exact unit conversion
- *                               is owned by ops (they know the pack price per unit).
+ * @param {number} amountCents - Dispute amount in cents (positive integer). Internally converted
+ *                               to meter units via `config.billing.meter.dollarsToUnitRatio`
+ *                               (default 1000 → $1 = 1000 units, so 5000 cents = 50,000 units).
  * @param {string} reason - Ops note for audit trail (stored in ledger entry refId context).
  * @param {string} refundRequestId - UUID per click (idempotency key).
  * @param {string} orgId - Organization ObjectId (string) — whose extras balance to credit.
@@ -338,14 +338,15 @@ const creditDisputeReinstated = async (chargeId, amountCents, reason, refundRequ
   // Idempotency key includes the refundRequestId to prevent double-click double-credit.
   const refId = `dispute-credit-${refundRequestId}`;
 
-  // Credit the extras balance using the compensation path.
-  // amountCents is used directly as the credit unit — ops chooses the proportional amount.
-  const result = await BillingExtraBalanceRepository.creditCompensation(orgId, amountCents, refId, reason);
+  // Convert cents to meter units using the configured dollarsToUnitRatio.
+  const creditUnits = Math.round((amountCents / 100) * getDollarsToUnitRatio());
+  const result = await BillingExtraBalanceRepository.creditCompensation(orgId, creditUnits, refId, reason);
 
   logger.info('[billing.admin] creditDisputeReinstated — applied', {
     orgId,
     chargeId,
     amountCents,
+    creditUnits,
     reason,
     refundRequestId,
     adminUserId,

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

@@ -452,17 +452,35 @@ describe('BillingAdminService unit tests:', () => {
         chargeId, amountCents, reason, refundRequestId, orgId, adminUserId,
       );
 
+      // amountCents=2000, default dollarsToUnitRatio=1000 → creditUnits = Math.round((2000/100)*1000) = 20000
+      const expectedCreditUnits = Math.round((amountCents / 100) * 1000);
       expect(result.applied).toBe(true);
       expect(result.ledgerEntry).toBeDefined();
       expect(mockExtraBalanceRepository.creditCompensation).toHaveBeenCalledWith(
         orgId,
-        amountCents,
+        expectedCreditUnits,
         `dispute-credit-${refundRequestId}`,
         reason,
       );
       expect(mockLogger.info).toHaveBeenCalledWith(
         '[billing.admin] creditDisputeReinstated — applied',
-        expect.objectContaining({ orgId, chargeId, amountCents, applied: true }),
+        expect.objectContaining({ orgId, chargeId, amountCents, creditUnits: expectedCreditUnits, applied: true }),
+      );
+    });
+
+    test('converts amountCents to creditUnits using dollarsToUnitRatio (V8 audit C5)', async () => {
+      mockConfig.billing.meter = { dollarsToUnitRatio: 1000 };
+
+      await BillingAdminService.creditDisputeReinstated(
+        'ch_test', 5000, 'dispute', 'req_xxxxxxxx', orgId, adminUserId,
+      );
+
+      // 5000 cents = $50 × 1000 units/dollar = 50,000 units
+      expect(mockExtraBalanceRepository.creditCompensation).toHaveBeenCalledWith(
+        orgId,
+        50000,
+        expect.any(String),
+        'dispute',
       );
     });