refactor: nix charges on refund

Rather than maintaining complex refund cut logic, lets not charge on refunds.
Let's keep the logic where we dont refund the app fee.

Author: nams1570

apps/backend/.env

@@ -113,7 +113,6 @@ STACK_OPENAI_API_KEY=# enter your openai api key
 STACK_FEATUREBASE_API_KEY=# enter your featurebase api key
 STACK_STRIPE_SECRET_KEY=# enter your stripe api key
 STACK_STRIPE_WEBHOOK_SECRET=# enter your stripe webhook secret
-STACK_STRIPE_PLATFORM_ACCOUNT_ID=# enter your platform stripe account id (acct_...), destination for Connect inverse transfers
 STACK_TELEGRAM_BOT_TOKEN= # enter you telegram bot token
 STACK_TELEGRAM_CHAT_ID=# enter your telegram chat id
 

apps/backend/.env.development

@@ -76,7 +76,6 @@ STACK_VERCEL_SANDBOX_TOKEN=vercel_sandbox_disabled_for_local_development
 STACK_OPENAI_API_KEY=mock_openai_api_key
 STACK_STRIPE_SECRET_KEY=sk_test_mockstripekey
 STACK_STRIPE_WEBHOOK_SECRET=mock_stripe_webhook_secret
-STACK_STRIPE_PLATFORM_ACCOUNT_ID=acct_mock_platform
 STACK_OPENROUTER_API_KEY=FORWARD_TO_PRODUCTION
 STACK_FEEDBACK_MODE=FORWARD_TO_PRODUCTION
 STACK_MINTLIFY_MCP_URL=https://stackauth-e0affa27.mintlify.app/mcp

apps/backend/prisma/migrations/20260422000000_add_platform_fee_event/migration.sql

@@ -1312,40 +1312,6 @@ model SubscriptionInvoice {
   @@unique([tenancyId, stripeInvoiceId])
 }
 
-// Ledger of platform fees collected via inverse Connect transfers (e.g. our
-// 0.9% cut of refund outflows). Each row is keyed by the originating Stripe
-// event so collection is idempotent under webhook / handler retry.
-model PlatformFeeEvent {
-  id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-
-  tenancyId String @db.Uuid
-  projectId String
-
-  // Discriminator for the source event. Currently only REFUND; additional
-  // sources (e.g. manual adjustments) may be added later.
-  sourceType String
-  // Stripe ID of the originating event — refund id for REFUND. Unique with
-  // sourceType to make fee collection idempotent.
-  sourceId   String
-
-  amount   Int
-  currency String
-
-  // PENDING | COLLECTED | FAILED
-  status           String
-  stripeTransferId String?
-  error            String?
-
-  createdAt   DateTime  @default(now())
-  updatedAt   DateTime  @updatedAt
-  collectedAt DateTime?
-
-  @@unique([sourceType, sourceId])
-  @@index([tenancyId])
-  @@index([projectId])
-  @@index([status])
-}
-
 model OutgoingRequest {
   id String @id @default(uuid()) @db.Uuid
 

apps/backend/prisma/schema.prisma

@@ -50,22 +50,6 @@ export const POST = createSmartRouteHandler({
           transfers: { requested: true },
         },
         country: "US",
-        // `debit_negative_balances` lets Stripe ACH-debit the merchant's
-        // linked bank when their Stripe balance goes negative due to payouts,
-        // chargebacks, or other settlement events. It does NOT let our
-        // `stripe.transfers.create` push a connected account into a negative
-        // balance on its own — transfers hard-fail on insufficient balance
-        // and land in the PlatformFeeEvent ledger with status=FAILED for
-        // manual reconciliation. We still enable this setting so that merchant
-        // balances that *would* go negative for other reasons (e.g. their own
-        // refunds running ahead of incoming payments) are covered automatically.
-        // Refs: https://docs.stripe.com/connect/account-debits
-        //       https://docs.stripe.com/connect/account-balances#negative-balances
-        settings: {
-          payouts: {
-            debit_negative_balances: true,
-          },
-        },
         metadata: {
           tenancyId: auth.tenancy.id,
         }

apps/backend/src/app/api/latest/internal/payments/platform-fees/route.ts

@@ -1,22 +1,44 @@
 import { buildOneTimePurchaseTransaction, buildSubscriptionTransaction, resolveSelectedPriceFromProduct } from "@/app/api/latest/internal/payments/transactions/transaction-builder";
 import { bulldozerWriteManualTransaction, bulldozerWriteOneTimePurchase, bulldozerWriteSubscription } from "@/lib/payments/bulldozer-dual-write";
-import { collectInverseFee, PlatformFeeSourceType } from "@/lib/payments/platform-fees";
 import type { ManualTransactionRow } from "@/lib/payments/schema/types";
 import { getStripeForAccount } from "@/lib/stripe";
 import { getPrismaClientForTenancy } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
-import { runAsynchronouslyAndWaitUntil } from "@/utils/background-tasks";
 import type { TransactionEntry } from "@stackframe/stack-shared/dist/interface/crud/transactions";
 import { KnownErrors } from "@stackframe/stack-shared/dist/known-errors";
 import { adaptSchema, adminAuthTypeSchema, moneyAmountSchema, productSchema, yupArray, yupBoolean, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { moneyAmountToStripeUnits } from "@stackframe/stack-shared/dist/utils/currencies";
 import { SUPPORTED_CURRENCIES, type MoneyAmount } from "@stackframe/stack-shared/dist/utils/currency-constants";
 import { StackAssertionError, throwErr } from "@stackframe/stack-shared/dist/utils/errors";
+import type Stripe from "stripe";
 import { InferType } from "yup";
 
 const USD_CURRENCY = SUPPORTED_CURRENCIES.find((currency) => currency.code === "USD")
   ?? throwErr("USD currency configuration missing in SUPPORTED_CURRENCIES");
 
+/**
+ * Builds the parameters object for `stripe.refunds.create`. Centralised so the
+ * platform-fee invariant — that we never let Stripe reverse our charge-leg
+ * 0.9% application fee on refund — has exactly one source of truth and one
+ * place to test.
+ *
+ * Stripe's default for `refund_application_fee` on a Connect direct charge is
+ * `true`, which proportionally reverses the application fee along with the
+ * refund. We always set it to `false` so the platform retains its cut.
+ */
+export function buildStripeRefundParams(args: {
+  paymentIntentId: string,
+  amountStripeUnits: number,
+  metadata?: Record<string, string>,
+}): Stripe.RefundCreateParams {
+  return {
+    payment_intent: args.paymentIntentId,
+    amount: args.amountStripeUnits,
+    ...(args.metadata ? { metadata: args.metadata } : {}),
+    refund_application_fee: false,
+  };
+}
+
 function getTotalUsdStripeUnits(options: { product: InferType<typeof productSchema>, priceId: string | null, quantity: number }) {
   const selectedPrice = resolveSelectedPriceFromProduct(options.product, options.priceId ?? null);
   const usdPrice = selectedPrice?.USD;
@@ -264,23 +286,9 @@ export const POST = createSmartRouteHandler({
       if (refundAmountStripeUnits > totalStripeUnits) {
         throw new KnownErrors.SchemaError("Refund amount cannot exceed the charged amount.");
       }
-      const subscriptionRefund = await stripe.refunds.create({
-        payment_intent: paymentIntentId,
-        amount: refundAmountStripeUnits,
-        // Keep the charge-leg application fee with the platform. Stripe's
-        // default would reverse it proportionally, cancelling out our 0.9%
-        // cut on the original charge.
-        refund_application_fee: false,
-      });
-      // Fee collection is best-effort and the originating refund has already
-      // succeeded, but we still need to keep the background ledger/transfer work
-      // alive after the response on serverless runtimes.
-      runAsynchronouslyAndWaitUntil(collectInverseFee({
-        tenancy: auth.tenancy,
+      await stripe.refunds.create(buildStripeRefundParams({
+        paymentIntentId,
         amountStripeUnits: refundAmountStripeUnits,
-        currency: "usd",
-        sourceType: PlatformFeeSourceType.REFUND,
-        sourceId: subscriptionRefund.id,
       }));
       const refundedAt = new Date();
       if (refundedQuantity > 0) {
@@ -379,21 +387,13 @@ export const POST = createSmartRouteHandler({
       if (refundAmountStripeUnits > totalStripeUnits) {
         throw new KnownErrors.SchemaError("Refund amount cannot exceed the charged amount.");
       }
-      const purchaseRefund = await stripe.refunds.create({
-        payment_intent: purchase.stripePaymentIntentId,
-        amount: refundAmountStripeUnits,
+      await stripe.refunds.create(buildStripeRefundParams({
+        paymentIntentId: purchase.stripePaymentIntentId,
+        amountStripeUnits: refundAmountStripeUnits,
         metadata: {
           tenancyId: auth.tenancy.id,
           purchaseId: purchase.id,
         },
-        refund_application_fee: false,
-      });
-      runAsynchronouslyAndWaitUntil(collectInverseFee({
-        tenancy: auth.tenancy,
-        amountStripeUnits: refundAmountStripeUnits,
-        currency: "usd",
-        sourceType: PlatformFeeSourceType.REFUND,
-        sourceId: purchaseRefund.id,
       }));
       const refundedAt = new Date();
       await prisma.oneTimePurchase.update({
@@ -429,3 +429,31 @@ export const POST = createSmartRouteHandler({
     };
   },
 });
+
+import.meta.vitest?.describe("buildStripeRefundParams", (test) => {
+  test("always sets refund_application_fee: false to keep our 0.9% with the platform", ({ expect }) => {
+    const params = buildStripeRefundParams({ paymentIntentId: "pi_test", amountStripeUnits: 5000 });
+    expect(params.refund_application_fee).toBe(false);
+  });
+  test("propagates payment_intent and amount as-is", ({ expect }) => {
+    const params = buildStripeRefundParams({ paymentIntentId: "pi_abc", amountStripeUnits: 1234 });
+    expect(params.payment_intent).toBe("pi_abc");
+    expect(params.amount).toBe(1234);
+  });
+  test("propagates metadata when provided and omits the key when not", ({ expect }) => {
+    const withMeta = buildStripeRefundParams({
+      paymentIntentId: "pi_x",
+      amountStripeUnits: 1,
+      metadata: { tenancyId: "t1", purchaseId: "p1" },
+    });
+    expect(withMeta.metadata).toEqual({ tenancyId: "t1", purchaseId: "p1" });
+    // refund_application_fee invariant must hold even when metadata is set —
+    // pin this explicitly so a future change to the metadata branch can't
+    // accidentally strip the fee flag.
+    expect(withMeta.refund_application_fee).toBe(false);
+
+    const withoutMeta = buildStripeRefundParams({ paymentIntentId: "pi_x", amountStripeUnits: 1 });
+    expect("metadata" in withoutMeta).toBe(false);
+    expect(withoutMeta.refund_application_fee).toBe(false);
+  });
+});

apps/backend/src/app/api/latest/internal/payments/setup/route.ts

@@ -98,14 +98,13 @@ export const POST = createSmartRouteHandler({
           // is created synchronously. `application_fee_percent` is applied to
           // invoices generated from the subscription's normal billing cycle, but
           // per Stripe's subscription/proration docs the immediately-generated
-          // upgrade invoice may not inherit the newly-set fee percent. Our
-          // charge-leg guarantee for this specific invoice is therefore
-          // best-effort until we either (a) observe the behaviour against a real
-          // onboarded Connect account, or (b) listen for the resulting
-          // `invoice.created` webhook and stamp `application_fee_amount` on the
-          // invoice before it finalises. Refund-leg collection (via
-          // `collectInverseFee`) is unaffected and still works on the full
-          // refund amount regardless.
+          // upgrade invoice may not inherit the newly-set fee percent — i.e. we
+          // may miss collecting our 0.9% on the proration invoice itself even
+          // though all later renewals of the new plan are covered. Best-effort
+          // until we either (a) observe the behaviour against a real onboarded
+          // Connect account, or (b) listen for the resulting `invoice.created`
+          // webhook and stamp `application_fee_amount` on the invoice before it
+          // finalises.
           // Refs: https://docs.stripe.com/connect/subscriptions
           //       https://docs.stripe.com/billing/subscriptions/prorations
           const applicationFeePercent = getApplicationFeePercentOrUndefined(tenancy.project.id);