@wopr-network/platform-core 1.46.0 → 1.48.0

package/src/billing/stripe/stripe-payment-processor.test.ts

@@ -120,7 +120,7 @@ describe("StripePaymentProcessor", () => {
       expect(result).toEqual([]);
     });
 
-    it("returns formatted payment methods with card label", async () => {
+    it("returns formatted payment methods with card label and reads actual Stripe default", async () => {
       vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
       vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
         data: [
@@ -128,6 +128,10 @@ describe("StripePaymentProcessor", () => {
           { id: "pm_2", card: { brand: "mastercard", last4: "5555" } },
         ],
       } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: "pm_1" },
+      } as unknown as Stripe.Response<Stripe.Customer>);
 
       const result = await processor.listPaymentMethods("tenant-1");
       expect(result).toEqual([
@@ -136,11 +140,49 @@ describe("StripePaymentProcessor", () => {
       ]);
     });
 
+    it("marks second PM as default when Stripe says so", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
+        data: [
+          { id: "pm_1", card: { brand: "visa", last4: "4242" } },
+          { id: "pm_2", card: { brand: "mastercard", last4: "5555" } },
+        ],
+      } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: "pm_2" },
+      } as unknown as Stripe.Response<Stripe.Customer>);
+
+      const result = await processor.listPaymentMethods("tenant-1");
+      expect(result).toEqual([
+        { id: "pm_1", label: "Visa ending 4242", isDefault: false },
+        { id: "pm_2", label: "Mastercard ending 5555", isDefault: true },
+      ]);
+    });
+
+    it("marks no PM as default when customer has no default set", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
+        data: [{ id: "pm_1", card: { brand: "visa", last4: "4242" } }],
+      } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: null },
+      } as unknown as Stripe.Response<Stripe.Customer>);
+
+      const result = await processor.listPaymentMethods("tenant-1");
+      expect(result).toEqual([{ id: "pm_1", label: "Visa ending 4242", isDefault: false }]);
+    });
+
     it("uses generic label for non-card payment methods", async () => {
       vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
       vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
         data: [{ id: "pm_bank", card: undefined }],
       } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: "pm_bank" },
+      } as unknown as Stripe.Response<Stripe.Customer>);
 
       const result = await processor.listPaymentMethods("tenant-1");
       expect(result).toEqual([{ id: "pm_bank", label: "Payment method pm_bank", isDefault: true }]);
@@ -192,6 +234,76 @@ describe("StripePaymentProcessor", () => {
     });
   });
 
+  // --- setDefaultPaymentMethod ---
+
+  describe("setDefaultPaymentMethod", () => {
+    it("throws when tenant has no Stripe customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(null);
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(
+        "No Stripe customer found for tenant: tenant-1",
+      );
+    });
+
+    it("throws PaymentMethodOwnershipError when PM belongs to different customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_OTHER",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(PaymentMethodOwnershipError);
+    });
+
+    it("throws PaymentMethodOwnershipError when PM has no customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: null,
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(PaymentMethodOwnershipError);
+    });
+
+    it("calls stripe.customers.update with invoice_settings when ownership matches", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_123",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockResolvedValue({} as unknown as Stripe.Response<Stripe.Customer>);
+
+      await processor.setDefaultPaymentMethod("tenant-1", "pm_1");
+      expect(mocks.stripe.customers.update).toHaveBeenCalledWith("cus_123", {
+        invoice_settings: { default_payment_method: "pm_1" },
+      });
+    });
+
+    it("succeeds when PM customer is an expanded Customer object", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: { id: "cus_123", object: "customer" },
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockResolvedValue({} as unknown as Stripe.Response<Stripe.Customer>);
+
+      await processor.setDefaultPaymentMethod("tenant-1", "pm_1");
+      expect(mocks.stripe.customers.update).toHaveBeenCalledWith("cus_123", {
+        invoice_settings: { default_payment_method: "pm_1" },
+      });
+    });
+
+    it("propagates Stripe API errors", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_123",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockRejectedValue(new Error("Stripe API error"));
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow("Stripe API error");
+    });
+  });
+
   // --- getCustomerEmail ---
 
   describe("getCustomerEmail", () => {

package/src/billing/stripe/stripe-payment-processor.ts

@@ -154,15 +154,42 @@ export class StripePaymentProcessor implements IPaymentProcessor {
       return [];
     }
 
-    const methods = await this.stripe.customers.listPaymentMethods(mapping.processor_customer_id);
-
-    return methods.data.map((pm, index) => ({
+    const [methods, customer] = await Promise.all([
+      this.stripe.customers.listPaymentMethods(mapping.processor_customer_id),
+      this.stripe.customers.retrieve(mapping.processor_customer_id),
+    ]);
+
+    const defaultPmId =
+      !customer.deleted && customer.invoice_settings?.default_payment_method
+        ? typeof customer.invoice_settings.default_payment_method === "string"
+          ? customer.invoice_settings.default_payment_method
+          : customer.invoice_settings.default_payment_method.id
+        : null;
+
+    return methods.data.map((pm) => ({
       id: pm.id,
       label: formatPaymentMethodLabel(pm),
-      isDefault: index === 0,
+      isDefault: defaultPmId ? pm.id === defaultPmId : false,
     }));
   }
 
+  async setDefaultPaymentMethod(tenant: string, paymentMethodId: string): Promise<void> {
+    const mapping = await this.tenantRepo.getByTenant(tenant);
+    if (!mapping) {
+      throw new Error(`No Stripe customer found for tenant: ${tenant}`);
+    }
+
+    const pm = await this.stripe.paymentMethods.retrieve(paymentMethodId);
+    const pmCustomerId = typeof pm.customer === "string" ? pm.customer : (pm.customer?.id ?? null);
+    if (!pmCustomerId || pmCustomerId !== mapping.processor_customer_id) {
+      throw new PaymentMethodOwnershipError();
+    }
+
+    await this.stripe.customers.update(mapping.processor_customer_id, {
+      invoice_settings: { default_payment_method: paymentMethodId },
+    });
+  }
+
   async detachPaymentMethod(tenant: string, paymentMethodId: string): Promise<void> {
     const mapping = await this.tenantRepo.getByTenant(tenant);
     if (!mapping) {
@@ -170,7 +197,8 @@ export class StripePaymentProcessor implements IPaymentProcessor {
     }
 
     const pm = await this.stripe.paymentMethods.retrieve(paymentMethodId);
-    if (!pm.customer || pm.customer !== mapping.processor_customer_id) {
+    const pmCustomerId = typeof pm.customer === "string" ? pm.customer : (pm.customer?.id ?? null);
+    if (!pmCustomerId || pmCustomerId !== mapping.processor_customer_id) {
       throw new PaymentMethodOwnershipError();
     }
 

package/src/monetization/stripe/stripe-payment-processor.test.ts

@@ -129,7 +129,7 @@ describe("StripePaymentProcessor", () => {
       expect(result).toEqual([]);
     });
 
-    it("returns formatted payment methods with card label", async () => {
+    it("returns formatted payment methods with card label and reads actual Stripe default", async () => {
       vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
       vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
         data: [
@@ -137,6 +137,10 @@ describe("StripePaymentProcessor", () => {
           { id: "pm_2", card: { brand: "mastercard", last4: "5555" } },
         ],
       } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: "pm_1" },
+      } as unknown as Stripe.Response<Stripe.Customer>);
 
       const result = await processor.listPaymentMethods("tenant-1");
       expect(result).toEqual([
@@ -150,6 +154,10 @@ describe("StripePaymentProcessor", () => {
       vi.mocked(mocks.stripe.customers.listPaymentMethods).mockResolvedValue({
         data: [{ id: "pm_bank", card: undefined }],
       } as unknown as Stripe.Response<Stripe.ApiList<Stripe.PaymentMethod>>);
+      vi.mocked(mocks.stripe.customers.retrieve).mockResolvedValue({
+        deleted: false,
+        invoice_settings: { default_payment_method: "pm_bank" },
+      } as unknown as Stripe.Response<Stripe.Customer>);
 
       const result = await processor.listPaymentMethods("tenant-1");
       expect(result).toEqual([{ id: "pm_bank", label: "Payment method pm_bank", isDefault: true }]);
@@ -201,6 +209,86 @@ describe("StripePaymentProcessor", () => {
     });
   });
 
+  // --- setDefaultPaymentMethod ---
+
+  describe("setDefaultPaymentMethod", () => {
+    it("throws when tenant has no Stripe customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(null);
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(
+        "No Stripe customer found for tenant: tenant-1",
+      );
+    });
+
+    it("throws PaymentMethodOwnershipError when PM has no customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: null,
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(PaymentMethodOwnershipError);
+    });
+
+    it("throws PaymentMethodOwnershipError when PM belongs to different customer", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_OTHER",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(PaymentMethodOwnershipError);
+    });
+
+    it("throws PaymentMethodOwnershipError when PM customer is an expanded object with different id", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: { id: "cus_OTHER", object: "customer" },
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow(PaymentMethodOwnershipError);
+    });
+
+    it("sets default when ownership matches (string customer)", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_123",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockResolvedValue({} as unknown as Stripe.Response<Stripe.Customer>);
+
+      await processor.setDefaultPaymentMethod("tenant-1", "pm_1");
+      expect(mocks.stripe.customers.update).toHaveBeenCalledWith("cus_123", {
+        invoice_settings: { default_payment_method: "pm_1" },
+      });
+    });
+
+    it("sets default when ownership matches (expanded Customer object)", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: { id: "cus_123", object: "customer" },
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockResolvedValue({} as unknown as Stripe.Response<Stripe.Customer>);
+
+      await processor.setDefaultPaymentMethod("tenant-1", "pm_1");
+      expect(mocks.stripe.customers.update).toHaveBeenCalledWith("cus_123", {
+        invoice_settings: { default_payment_method: "pm_1" },
+      });
+    });
+
+    it("propagates Stripe errors", async () => {
+      vi.mocked(mocks.tenantRepo.getByTenant).mockResolvedValue(makeTenantRow());
+      vi.mocked(mocks.stripe.paymentMethods.retrieve).mockResolvedValue({
+        id: "pm_1",
+        customer: "cus_123",
+      } as unknown as Stripe.Response<Stripe.PaymentMethod>);
+      vi.mocked(mocks.stripe.customers.update).mockRejectedValue(new Error("Stripe network error"));
+
+      await expect(processor.setDefaultPaymentMethod("tenant-1", "pm_1")).rejects.toThrow("Stripe network error");
+    });
+  });
+
   // --- getCustomerEmail ---
 
   describe("getCustomerEmail", () => {

package/src/monetization/stripe/stripe-payment-processor.ts

@@ -154,15 +154,42 @@ export class StripePaymentProcessor implements IPaymentProcessor {
       return [];
     }
 
-    const methods = await this.stripe.customers.listPaymentMethods(mapping.processor_customer_id);
-
-    return methods.data.map((pm, index) => ({
+    const [methods, customer] = await Promise.all([
+      this.stripe.customers.listPaymentMethods(mapping.processor_customer_id),
+      this.stripe.customers.retrieve(mapping.processor_customer_id),
+    ]);
+
+    const defaultPmId =
+      !customer.deleted && customer.invoice_settings?.default_payment_method
+        ? typeof customer.invoice_settings.default_payment_method === "string"
+          ? customer.invoice_settings.default_payment_method
+          : customer.invoice_settings.default_payment_method.id
+        : null;
+
+    return methods.data.map((pm) => ({
       id: pm.id,
       label: formatPaymentMethodLabel(pm),
-      isDefault: index === 0,
+      isDefault: defaultPmId ? pm.id === defaultPmId : false,
     }));
   }
 
+  async setDefaultPaymentMethod(tenant: string, paymentMethodId: string): Promise<void> {
+    const mapping = await this.tenantRepo.getByTenant(tenant);
+    if (!mapping) {
+      throw new Error(`No Stripe customer found for tenant: ${tenant}`);
+    }
+
+    const pm = await this.stripe.paymentMethods.retrieve(paymentMethodId);
+    const pmCustomerId = typeof pm.customer === "string" ? pm.customer : (pm.customer?.id ?? null);
+    if (!pmCustomerId || pmCustomerId !== mapping.processor_customer_id) {
+      throw new PaymentMethodOwnershipError();
+    }
+
+    await this.stripe.customers.update(mapping.processor_customer_id, {
+      invoice_settings: { default_payment_method: paymentMethodId },
+    });
+  }
+
   async detachPaymentMethod(tenant: string, paymentMethodId: string): Promise<void> {
     const mapping = await this.tenantRepo.getByTenant(tenant);
     if (!mapping) {

package/src/trpc/index.ts

@@ -13,3 +13,7 @@ export {
   tenantProcedure,
 } from "./init.js";
 export { createNotificationTemplateRouter } from "./notification-template-router.js";
+export {
+  createOrgRemovePaymentMethodRouter,
+  type OrgRemovePaymentMethodDeps,
+} from "./org-remove-payment-method-router.js";

package/src/trpc/org-remove-payment-method-router.test.ts

@@ -0,0 +1,189 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { IPaymentProcessor, SavedPaymentMethod } from "../billing/payment-processor.js";
+import type { AutoTopupSettings, IAutoTopupSettingsRepository } from "../credits/auto-topup-settings-repository.js";
+import type { IOrgMemberRepository } from "../tenancy/org-member-repository.js";
+import { createCallerFactory, router, setTrpcOrgMemberRepo } from "./init.js";
+import { createOrgRemovePaymentMethodRouter } from "./org-remove-payment-method-router.js";
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+function makeMockOrgMemberRepo(overrides?: Partial<IOrgMemberRepository>): IOrgMemberRepository {
+  return {
+    listMembers: vi.fn().mockResolvedValue([]),
+    addMember: vi.fn().mockResolvedValue(undefined),
+    updateMemberRole: vi.fn().mockResolvedValue(undefined),
+    removeMember: vi.fn().mockResolvedValue(undefined),
+    findMember: vi.fn().mockResolvedValue({ userId: "u1", role: "owner" }),
+    countAdminsAndOwners: vi.fn().mockResolvedValue(1),
+    listInvites: vi.fn().mockResolvedValue([]),
+    createInvite: vi.fn().mockResolvedValue(undefined),
+    findInviteById: vi.fn().mockResolvedValue(null),
+    findInviteByToken: vi.fn().mockResolvedValue(null),
+    deleteInvite: vi.fn().mockResolvedValue(undefined),
+    deleteAllMembers: vi.fn().mockResolvedValue(undefined),
+    deleteAllInvites: vi.fn().mockResolvedValue(undefined),
+    listOrgsByUser: vi.fn().mockResolvedValue([]),
+    markInviteAccepted: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+function makeMockProcessor(methods: SavedPaymentMethod[]): IPaymentProcessor {
+  return {
+    name: "mock",
+    createCheckoutSession: vi.fn(),
+    handleWebhook: vi.fn(),
+    supportsPortal: vi.fn().mockReturnValue(false),
+    createPortalSession: vi.fn(),
+    setupPaymentMethod: vi.fn(),
+    listPaymentMethods: vi.fn().mockResolvedValue(methods),
+    charge: vi.fn(),
+    detachPaymentMethod: vi.fn().mockResolvedValue(undefined),
+    getCustomerEmail: vi.fn().mockResolvedValue(""),
+    updateCustomerEmail: vi.fn(),
+    listInvoices: vi.fn().mockResolvedValue([]),
+    setDefaultPaymentMethod: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+function makeMockAutoTopupSettings(overrides?: Partial<AutoTopupSettings>): IAutoTopupSettingsRepository {
+  const settings: AutoTopupSettings | null = overrides
+    ? ({
+        tenantId: "org-1",
+        usageEnabled: false,
+        usageThreshold: { toCentsRounded: () => 0 },
+        usageTopup: { toCentsRounded: () => 0 },
+        usageConsecutiveFailures: 0,
+        usageChargeInFlight: false,
+        scheduleEnabled: false,
+        scheduleAmount: { toCentsRounded: () => 0 },
+        scheduleIntervalHours: 0,
+        scheduleNextAt: null,
+        scheduleConsecutiveFailures: 0,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+        ...overrides,
+      } as AutoTopupSettings)
+    : null;
+
+  return {
+    getByTenant: vi.fn().mockResolvedValue(settings),
+    upsert: vi.fn(),
+    setUsageChargeInFlight: vi.fn(),
+    tryAcquireUsageInFlight: vi.fn(),
+    incrementUsageFailures: vi.fn(),
+    resetUsageFailures: vi.fn(),
+    disableUsage: vi.fn(),
+    incrementScheduleFailures: vi.fn(),
+    resetScheduleFailures: vi.fn(),
+    disableSchedule: vi.fn(),
+    advanceScheduleNextAt: vi.fn(),
+    listDueScheduled: vi.fn().mockResolvedValue([]),
+    getMaxConsecutiveFailures: vi.fn().mockResolvedValue(0),
+  };
+}
+
+function authedContext() {
+  return { user: { id: "u1", roles: ["user"] }, tenantId: "org-1" };
+}
+
+function unauthedContext() {
+  return { user: undefined, tenantId: undefined };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("orgRemovePaymentMethod router", () => {
+  let processor: IPaymentProcessor;
+  let autoTopupStore: IAutoTopupSettingsRepository;
+
+  beforeEach(() => {
+    processor = makeMockProcessor([{ id: "pm_1", label: "Visa ending 4242", isDefault: true }]);
+    autoTopupStore = makeMockAutoTopupSettings();
+    setTrpcOrgMemberRepo(makeMockOrgMemberRepo());
+  });
+
+  function buildCaller(deps: { processor: IPaymentProcessor; autoTopupSettingsStore?: IAutoTopupSettingsRepository }) {
+    const subRouter = createOrgRemovePaymentMethodRouter(() => ({
+      processor: deps.processor,
+      autoTopupSettingsStore: deps.autoTopupSettingsStore,
+    }));
+    const appRouter = router({ org: subRouter });
+    return createCallerFactory(appRouter);
+  }
+
+  it("successfully removes a payment method", async () => {
+    const caller = buildCaller({ processor, autoTopupSettingsStore: autoTopupStore })(authedContext());
+    const result = await caller.org.orgRemovePaymentMethod({
+      orgId: "org-1",
+      paymentMethodId: "pm_1",
+    });
+    expect(result).toEqual({ removed: true });
+    expect(processor.detachPaymentMethod).toHaveBeenCalledWith("org-1", "pm_1");
+  });
+
+  it("rejects unauthenticated users", async () => {
+    const caller = buildCaller({ processor, autoTopupSettingsStore: autoTopupStore })(unauthedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "UNAUTHORIZED",
+    });
+  });
+
+  it("rejects when removing last PM with auto-topup usage enabled", async () => {
+    const usageStore = makeMockAutoTopupSettings({ usageEnabled: true });
+    const caller = buildCaller({
+      processor,
+      autoTopupSettingsStore: usageStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  it("rejects when removing last PM with auto-topup schedule enabled", async () => {
+    const scheduleStore = makeMockAutoTopupSettings({ scheduleEnabled: true });
+    const caller = buildCaller({
+      processor,
+      autoTopupSettingsStore: scheduleStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+
+  it("allows removing non-last PM even with auto-topup enabled", async () => {
+    const multiProcessor = makeMockProcessor([
+      { id: "pm_1", label: "Visa ending 4242", isDefault: true },
+      { id: "pm_2", label: "Mastercard ending 5555", isDefault: false },
+    ]);
+    const usageStore = makeMockAutoTopupSettings({ usageEnabled: true });
+    const caller = buildCaller({
+      processor: multiProcessor,
+      autoTopupSettingsStore: usageStore,
+    })(authedContext());
+    const result = await caller.org.orgRemovePaymentMethod({
+      orgId: "org-1",
+      paymentMethodId: "pm_1",
+    });
+    expect(result).toEqual({ removed: true });
+  });
+
+  it("returns FORBIDDEN when detachPaymentMethod throws PaymentMethodOwnershipError", async () => {
+    const { PaymentMethodOwnershipError } = await import("../billing/payment-processor.js");
+    const ownershipErrorProcessor = makeMockProcessor([]);
+    (ownershipErrorProcessor.detachPaymentMethod as ReturnType<typeof vi.fn>).mockRejectedValue(
+      new PaymentMethodOwnershipError(),
+    );
+    const caller = buildCaller({
+      processor: ownershipErrorProcessor,
+      autoTopupSettingsStore: autoTopupStore,
+    })(authedContext());
+    await expect(caller.org.orgRemovePaymentMethod({ orgId: "org-1", paymentMethodId: "pm_1" })).rejects.toMatchObject({
+      code: "FORBIDDEN",
+    });
+  });
+});

package/src/trpc/org-remove-payment-method-router.ts

@@ -0,0 +1,80 @@
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+import type { IPaymentProcessor } from "../billing/payment-processor.js";
+import { PaymentMethodOwnershipError } from "../billing/payment-processor.js";
+import type { IAutoTopupSettingsRepository } from "../credits/auto-topup-settings-repository.js";
+import { orgAdminProcedure, router } from "./init.js";
+
+export interface OrgRemovePaymentMethodDeps {
+  processor: IPaymentProcessor;
+  autoTopupSettingsStore?: IAutoTopupSettingsRepository;
+}
+
+export function createOrgRemovePaymentMethodRouter(getDeps: () => OrgRemovePaymentMethodDeps) {
+  return router({
+    orgRemovePaymentMethod: orgAdminProcedure
+      .input(
+        z.object({
+          orgId: z.string().min(1),
+          paymentMethodId: z.string().min(1),
+        }),
+      )
+      .mutation(async ({ input }) => {
+        const { processor, autoTopupSettingsStore } = getDeps();
+
+        if (!autoTopupSettingsStore) {
+          console.warn(
+            "orgRemovePaymentMethod: autoTopupSettingsStore not provided — last-payment-method guard is inactive",
+          );
+        }
+
+        // Guard: prevent removing the last payment method when auto-topup is enabled
+        if (autoTopupSettingsStore) {
+          const methods = await processor.listPaymentMethods(input.orgId);
+          if (methods.length <= 1) {
+            const settings = await autoTopupSettingsStore.getByTenant(input.orgId);
+            if (settings && (settings.usageEnabled || settings.scheduleEnabled)) {
+              throw new TRPCError({
+                code: "FORBIDDEN",
+                message: "Cannot remove last payment method while auto-topup is enabled. Disable auto-topup first.",
+              });
+            }
+          }
+        }
+
+        try {
+          await processor.detachPaymentMethod(input.orgId, input.paymentMethodId);
+        } catch (err) {
+          if (err instanceof PaymentMethodOwnershipError) {
+            throw new TRPCError({
+              code: "FORBIDDEN",
+              message: "Payment method does not belong to this organization",
+            });
+          }
+          throw new TRPCError({
+            code: "INTERNAL_SERVER_ERROR",
+            message: "Failed to remove payment method. Please try again.",
+          });
+        }
+
+        // TOCTOU guard: re-check count after detach. A concurrent request
+        // may have already removed another payment method between our pre-check
+        // and this detach, leaving the org with 0 methods while auto-topup is
+        // still enabled. Warn operators — the method is already gone.
+        if (autoTopupSettingsStore) {
+          const remaining = await processor.listPaymentMethods(input.orgId);
+          if (remaining.length === 0) {
+            const settings = await autoTopupSettingsStore.getByTenant(input.orgId);
+            if (settings && (settings.usageEnabled || settings.scheduleEnabled)) {
+              console.warn(
+                "orgRemovePaymentMethod: TOCTOU — org %s now has 0 payment methods with auto-topup enabled. Operator must add a payment method or disable auto-topup.",
+                input.orgId,
+              );
+            }
+          }
+        }
+
+        return { removed: true };
+      }),
+  });
+}