feat(payments): collect 0.9% platform fee on every stripe money movement

Charges the platform 0.9% on both legs of each transaction on non-internal
projects. The charge leg rides along via Stripe's native
`application_fee_amount` / `application_fee_percent` params on the
PaymentIntent / Subscription. The refund leg cannot use Stripe's built-in
fee handling (Stripe's default is to reverse our charge-leg fee on refund,
netting us zero) so we disable that with `refund_application_fee: false`
and collect the refund-leg fee via an inverse Connect transfer.

The inverse-transfer path is fire-and-forget from the refund route so a
fee-collection failure never blocks the end-customer's refund. Every
attempt writes a durable `PlatformFeeEvent` ledger row first, upserting
on `(sourceType, sourceId)` so replayed refunds cannot double-record. On
retry beyond Stripe's 24h idempotency-key window we reconcile via a
content-addressed `transfer_group` lookup so we don't double-debit the
merchant. FAILED rows keep a Sentry-captured error string so ops can see
what's stuck via the admin `/platform-fees` endpoint.

Merchant Connect accounts now onboard with `debit_negative_balances: true`
so Stripe can ACH-debit the merchant's linked bank when their balance
goes negative from settlement events (payouts, chargebacks). Inverse
transfers themselves still hard-fail on insufficient balance and land in
the ledger as FAILED for manual reconciliation.

Author: mantrakp04

apps/backend/.env

@@ -113,6 +113,7 @@ 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,6 +76,7 @@ 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_DOCS_INTERNAL_BASE_URL=http://localhost:8104

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

@@ -0,0 +1,30 @@
+-- CreateTable
+CREATE TABLE "PlatformFeeEvent" (
+    "id" UUID NOT NULL DEFAULT gen_random_uuid(),
+    "tenancyId" UUID NOT NULL,
+    "projectId" TEXT NOT NULL,
+    "sourceType" TEXT NOT NULL CHECK ("sourceType" IN ('REFUND')),
+    "sourceId" TEXT NOT NULL,
+    "amount" INTEGER NOT NULL CHECK ("amount" >= 0),
+    "currency" TEXT NOT NULL,
+    "status" TEXT NOT NULL CHECK ("status" IN ('PENDING', 'COLLECTED', 'FAILED')),
+    "stripeTransferId" TEXT,
+    "error" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+    "collectedAt" TIMESTAMP(3),
+
+    CONSTRAINT "PlatformFeeEvent_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "PlatformFeeEvent_sourceType_sourceId_key" ON "PlatformFeeEvent"("sourceType", "sourceId");
+
+-- CreateIndex
+CREATE INDEX "PlatformFeeEvent_tenancyId_idx" ON "PlatformFeeEvent"("tenancyId");
+
+-- CreateIndex
+CREATE INDEX "PlatformFeeEvent_projectId_idx" ON "PlatformFeeEvent"("projectId");
+
+-- CreateIndex
+CREATE INDEX "PlatformFeeEvent_status_idx" ON "PlatformFeeEvent"("status");

apps/backend/prisma/schema.prisma

@@ -1312,6 +1312,40 @@ 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(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/src/app/api/latest/internal/payments/platform-fees/route.ts

@@ -0,0 +1,75 @@
+import { PlatformFeeStatus } from "@/lib/payments/platform-fees";
+import { globalPrismaClient } from "@/prisma-client";
+import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
+import { adaptSchema, adminAuthTypeSchema, yupArray, yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
+
+export const GET = createSmartRouteHandler({
+  metadata: {
+    hidden: true,
+  },
+  request: yupObject({
+    auth: yupObject({
+      type: adminAuthTypeSchema.defined(),
+      project: adaptSchema.defined(),
+      tenancy: adaptSchema.defined(),
+    }).defined(),
+  }),
+  response: yupObject({
+    statusCode: yupNumber().oneOf([200]).defined(),
+    bodyType: yupString().oneOf(["json"]).defined(),
+    body: yupObject({
+      // Sum of every platform fee event not yet marked COLLECTED, in
+      // USD stripe-units (cents). Expands to a keyed map when multi-currency
+      // support is introduced.
+      total_due_usd: yupNumber().defined(),
+      events: yupArray(
+        yupObject({
+          id: yupString().defined(),
+          source_type: yupString().defined(),
+          source_id: yupString().defined(),
+          amount: yupNumber().defined(),
+          currency: yupString().defined(),
+          status: yupString().defined(),
+          stripe_transfer_id: yupString().nullable().defined(),
+          error: yupString().nullable().defined(),
+          created_at: yupString().defined(),
+          collected_at: yupString().nullable().defined(),
+        }).defined(),
+      ).defined(),
+    }).defined(),
+  }),
+  handler: async ({ auth }) => {
+    // TODO: pagination. Low-priority today (volume per tenancy is small), but
+    // merchants with high refund throughput will eventually accumulate
+    // thousands of rows here. Add cursor-based pagination before shipping a
+    // merchant-visible UI.
+    const events = await globalPrismaClient.platformFeeEvent.findMany({
+      where: { tenancyId: auth.tenancy.id },
+      orderBy: { createdAt: "desc" },
+    });
+
+    const totalDueUsdUnits = events
+      .filter((e) => e.status !== PlatformFeeStatus.COLLECTED && e.currency === "usd")
+      .reduce((sum, e) => sum + e.amount, 0);
+
+    return {
+      statusCode: 200,
+      bodyType: "json",
+      body: {
+        total_due_usd: totalDueUsdUnits,
+        events: events.map((e) => ({
+          id: e.id,
+          source_type: e.sourceType,
+          source_id: e.sourceId,
+          amount: e.amount,
+          currency: e.currency,
+          status: e.status,
+          stripe_transfer_id: e.stripeTransferId,
+          error: e.error,
+          created_at: e.createdAt.toISOString(),
+          collected_at: e.collectedAt?.toISOString() ?? null,
+        })),
+      },
+    };
+  },
+});

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

@@ -50,6 +50,22 @@ 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/transactions/refund/route.tsx

@@ -1,9 +1,11 @@
 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 { runAsynchronously } from "@stackframe/stack-shared/dist/utils/promises";
 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";
@@ -262,10 +264,24 @@ export const POST = createSmartRouteHandler({
       if (refundAmountStripeUnits > totalStripeUnits) {
         throw new KnownErrors.SchemaError("Refund amount cannot exceed the charged amount.");
       }
-      await stripe.refunds.create({
+      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 — don't block the response on the inverse transfer. The
+      // helper has its own durable ledger + Sentry capture for failures.
+      runAsynchronously(collectInverseFee({
+        tenancy: auth.tenancy,
+        amountStripeUnits: refundAmountStripeUnits,
+        currency: "usd",
+        sourceType: PlatformFeeSourceType.REFUND,
+        sourceId: subscriptionRefund.id,
+      }));
       const refundedAt = new Date();
       if (refundedQuantity > 0) {
         if (!subscription.stripeSubscriptionId) {
@@ -363,14 +379,22 @@ export const POST = createSmartRouteHandler({
       if (refundAmountStripeUnits > totalStripeUnits) {
         throw new KnownErrors.SchemaError("Refund amount cannot exceed the charged amount.");
       }
-      await stripe.refunds.create({
+      const purchaseRefund = await stripe.refunds.create({
         payment_intent: purchase.stripePaymentIntentId,
         amount: refundAmountStripeUnits,
         metadata: {
           tenancyId: auth.tenancy.id,
           purchaseId: purchase.id,
         },
+        refund_application_fee: false,
       });
+      runAsynchronously(collectInverseFee({
+        tenancy: auth.tenancy,
+        amountStripeUnits: refundAmountStripeUnits,
+        currency: "usd",
+        sourceType: PlatformFeeSourceType.REFUND,
+        sourceId: purchaseRefund.id,
+      }));
       const refundedAt = new Date();
       await prisma.oneTimePurchase.update({
         where: { tenancyId_id: { tenancyId: auth.tenancy.id, id: body.id } },

apps/backend/src/app/api/latest/payments/products/[customer_type]/[customer_id]/switch/route.ts

@@ -2,6 +2,7 @@ import { SubscriptionStatus } from "@/generated/prisma/client";
 import { ensureClientCanAccessCustomer, ensureCustomerExists, getDefaultCardPaymentMethodSummary, getStripeCustomerForCustomerOrNull, isActiveSubscription, isAddOnProduct } from "@/lib/payments";
 import { bulldozerWriteSubscription } from "@/lib/payments/bulldozer-dual-write";
 import { getOwnedProductsForCustomer, getSubscriptionMapForCustomer } from "@/lib/payments/customer-data";
+import { getApplicationFeePercentOrUndefined } from "@/lib/payments/platform-fees";
 import { upsertProductVersion } from "@/lib/product-versions";
 import { getStripeForAccount, sanitizeStripePeriodDates } from "@/lib/stripe";
 import { getPrismaClientForTenancy } from "@/prisma-client";
@@ -204,6 +205,11 @@ export const POST = createSmartRouteHandler({
         throw new StackAssertionError("Stripe subscription has no items", { subscriptionId: existingSub.id });
       }
       const existingItem = existingStripeSub.items.data[0];
+      // Intentional: switching an existing (possibly pre-platform-fee)
+      // subscription to a new plan attaches the 0.9% application fee from
+      // this point forward. Subscriptions that never switch plans stay
+      // fee-less until a separate migration applies fees retroactively.
+      const applicationFeePercent = getApplicationFeePercentOrUndefined(auth.tenancy.project.id);
       const updated = await stripe.subscriptions.update(existingSub.stripeSubscriptionId, {
         payment_behavior: "error_if_incomplete",
         payment_settings: { save_default_payment_method: "on_subscription" },
@@ -226,6 +232,7 @@ export const POST = createSmartRouteHandler({
           productVersionId,
           priceId: selectedPriceId,
         },
+        ...(applicationFeePercent !== undefined ? { application_fee_percent: applicationFeePercent } : {}),
       });
       const updatedSubscription = updated as Stripe.Subscription;
       const sanitizedUpdateDates = sanitizeStripePeriodDates(
@@ -261,6 +268,7 @@ export const POST = createSmartRouteHandler({
       // DEPRECATED: this path handles switching from include-by-default (free) products
       // to paid subscriptions. Default products are being removed; this code is kept
       // for backward compatibility only.
+      const applicationFeePercent = getApplicationFeePercentOrUndefined(auth.tenancy.project.id);
       const created = await stripe.subscriptions.create({
         customer: stripeCustomer.id,
         payment_behavior: "error_if_incomplete",
@@ -283,6 +291,7 @@ export const POST = createSmartRouteHandler({
           productVersionId,
           priceId: selectedPriceId,
         },
+        ...(applicationFeePercent !== undefined ? { application_fee_percent: applicationFeePercent } : {}),
       });
       const createdSubscription = created as Stripe.Subscription;
       if (createdSubscription.items.data.length === 0) {

apps/backend/src/app/api/latest/payments/purchases/purchase-session/route.tsx

@@ -1,6 +1,7 @@
 import { SubscriptionStatus } from "@/generated/prisma/client";
 import { getClientSecretFromStripeSubscription, validatePurchaseSession } from "@/lib/payments";
 import { bulldozerWriteSubscription } from "@/lib/payments/bulldozer-dual-write";
+import { computeApplicationFeeAmount, getApplicationFeePercentOrUndefined } from "@/lib/payments/platform-fees";
 import { upsertProductVersion } from "@/lib/product-versions";
 import { getStripeForAccount } from "@/lib/stripe";
 import { getTenancy } from "@/lib/tenancies";
@@ -92,6 +93,22 @@ export const POST = createSmartRouteHandler({
         const existingItem = existingStripeSub.items.data[0];
         const product = await stripe.products.create({ name: data.product.displayName ?? "Subscription" });
         if (selectedPrice.interval) {
+          // TODO (platform-fees): this is a plan-switch mid-cycle that returns
+          // `latest_invoice.confirmation_secret`, so an upgrade/proration invoice
+          // 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.
+          // Refs: https://docs.stripe.com/connect/subscriptions
+          //       https://docs.stripe.com/billing/subscriptions/prorations
+          const applicationFeePercent = getApplicationFeePercentOrUndefined(tenancy.project.id);
           const updated = await stripe.subscriptions.update(conflicting.stripeSubscriptionId, {
             payment_behavior: 'default_incomplete',
             payment_settings: { save_default_payment_method: 'on_subscription' },
@@ -114,6 +131,7 @@ export const POST = createSmartRouteHandler({
               productVersionId,
               priceId: price_id,
             },
+            ...(applicationFeePercent !== undefined ? { application_fee_percent: applicationFeePercent } : {}),
           });
           const clientSecretUpdated = getClientSecretFromStripeSubscription(updated);
           await purchaseUrlVerificationCodeHandler.revokeCode({ tenancy, id: codeId });
@@ -145,6 +163,10 @@ export const POST = createSmartRouteHandler({
     // One-time payment path after conflicts handled
     if (!selectedPrice.interval) {
       const amountCents = Number(selectedPrice.USD) * 100 * Math.max(1, quantity);
+      const applicationFeeAmount = computeApplicationFeeAmount({
+        amountStripeUnits: amountCents,
+        projectId: tenancy.project.id,
+      });
       const paymentIntent = await stripe.paymentIntents.create({
         amount: amountCents,
         currency: "usd",
@@ -160,6 +182,7 @@ export const POST = createSmartRouteHandler({
           tenancyId: data.tenancyId,
           priceId: price_id,
         },
+        ...(applicationFeeAmount > 0 ? { application_fee_amount: applicationFeeAmount } : {}),
       });
       const clientSecret = paymentIntent.client_secret;
       if (typeof clientSecret !== "string") {
@@ -172,6 +195,7 @@ export const POST = createSmartRouteHandler({
     const product = await stripe.products.create({
       name: data.product.displayName ?? "Subscription",
     });
+    const applicationFeePercent = getApplicationFeePercentOrUndefined(tenancy.project.id);
     const created = await stripe.subscriptions.create({
       customer: data.stripeCustomerId,
       payment_behavior: 'default_incomplete',
@@ -194,6 +218,7 @@ export const POST = createSmartRouteHandler({
         productVersionId,
         priceId: price_id,
       },
+      ...(applicationFeePercent !== undefined ? { application_fee_percent: applicationFeePercent } : {}),
     });
     const clientSecret = getClientSecretFromStripeSubscription(created);
     if (typeof clientSecret !== "string") {