@fantastic.dev/better-stripe 0.9.0 → 0.10.1

package/docs/react-workflows.md

@@ -52,8 +52,11 @@ function Purchase({ publishableKey, priceId, createSession }) {
 
 The callback returns `{ stripeSessionId, clientSecret?, url? }`. It must return
 `url` for `redirect` and `clientSecret` for the other session modes. Use the
-request ID for server idempotency. A user-triggered retry creates a new request
-ID; also enforce application-level duplicate-order protection on the server.
+request ID for server idempotency. Retries and rerenders preserve the same ID.
+Changing `orderKey` or checkout mode starts a new logical request. Pass a persisted
+`requestId` prop to preserve identity across unmounts or page reloads. Forward it
+to your authenticated server and Stripe request options; also enforce durable
+application-level duplicate-order protection.
 
 | Mode             | Stripe integration                    | Tradeoff                                                               |
 | ---------------- | ------------------------------------- | ---------------------------------------------------------------------- |

package/docs/settlement.md

@@ -0,0 +1,158 @@
+# Verified settlement and recipient payouts
+
+BetterStripe owns provider reads, immutable settlement claims, transfer execution,
+and recovery. Your server authenticates the caller, resolves recipient accounts,
+selects rates, and authorizes the allocation. Never accept these values directly
+from a browser. Amounts below are integer minor units in one currency.
+
+## Read, allocate, settle
+
+```ts
+import { allocateSale } from "@fantastic.dev/better-stripe";
+
+const sale = await stripe.getVerifiedSale(ctx, {
+  paymentIntentId,
+  invoiceId, // Required for a subscription payment
+  subscriptionId,
+});
+if (sale.status !== "ready") {
+  // Only retry when sale.retryable is true. Missing processing fees are not zero.
+  return sale;
+}
+const allocation = allocateSale({
+  gross: sale.gross,
+  processingFee: sale.processingFee,
+  feeBasisPoints: 900,
+  creatorAccountId,
+  affiliate: { destinationAccountId: affiliateAccountId, basisPoints: 2000 },
+  collaborators: [
+    { destinationAccountId: collaboratorAccountId, basisPoints: 2500 },
+  ],
+});
+return stripe.settleSale(ctx, {
+  paymentIntentId,
+  invoiceId,
+  subscriptionId,
+  allocation: {
+    gross: sale.gross,
+    currency: sale.currency,
+    processingFee: sale.processingFee,
+    platformNet: allocation.platformNet,
+    transfers: allocation.transfers,
+  },
+});
+```
+
+`allocateSale` is pure. The inclusive sale fee is the greater of actual Stripe
+processing and the selected gross percentage. The platform keeps the difference.
+An affiliate receives a percentage of the amount after that fee, or a
+`fixedAmount` in minor units, capped at the amount available. Collaborators
+receive their percentages of the creator remainder. Rounding residue stays with
+the creator. Omit the affiliate for zero commission; no application rate is built in.
+
+`getVerifiedSale` expands the charge's actual balance transaction, verifies
+currency and paid invoice linkage, and reads the subscription's current price.
+It refuses refunded/disputed charges, converted settlement currencies, partial
+invoice payments, and multi-price subscriptions rather than guessing allocations.
+A `pending` result carries a retryable reason; `not_payable` must not trigger a transfer.
+
+`settleSale` verifies the provider data again, then pins the original allocation
+by charge. Retries use that original allocation even if rates have changed. The
+shared transfer engine records legs in the existing component transfer ledger;
+there is no required application `storeSales` table. Optional signed
+`adjustmentAmount` accounts for an authorized application credit or recovered
+cost; it must reconcile with all other amounts. An optional `onSettled` callback
+runs after execution and can run again on retries: make application writes
+idempotent by source charge.
+
+Provider transfers carry the source charge and recipient role. If Stripe succeeds
+and persistence fails, retries reconcile provider records before creating missing
+legs, including legacy ungrouped transfers. Incomplete provider history fails
+closed. Existing refund/dispute reversal APIs recover these original legs too.
+Stripe API idempotency is an additional safeguard, not the only recovery record.
+Do not delete financial component records while payments can be retried or reversed.
+
+The Vite example exposes a [fee-first allocation preview](http://localhost:5173/demo/allocation)
+from Admin → Testing Utilities. Its illustrative inputs use the public helper
+and the package React `SplitBreakdown`; they do not alter store settings.
+
+## Subscription commission terms
+
+```ts
+const commission = await stripe.selectCommissionInvoice(ctx, {
+  subscriptionId,
+  invoiceId,
+  affiliateAccountId, // Server-validated identity
+  term: "one_time", // Default: "forever"
+});
+```
+
+This selects eligibility, not a rate or a money movement. `one_time` selects the
+earliest paid nonzero invoice from complete provider history, even if a renewal
+arrives first. Failed invoices and zero-value trials do not consume eligibility.
+The component pins the term and affiliate identity. Refunds do not reset the
+first invoice. A replay returns the same `claimKey` and eligibility so interrupted
+settlement can finish; deduplicate actual payment execution with `settleSale`.
+If historical pagination exceeds the configured bound, selection refuses to guess.
+
+The Vite example migrates its old subscription claims with
+`pnpm exec convex run commissionMigration:run '{}'` from `example/`. Repeat until
+it returns `0`. Run this after deploying the new component and before replaying
+historical subscription events. The migration preserves terms and first invoices;
+its batch deletes are transactional with component writes.
+
+## Payout snapshots
+
+```ts
+const snapshot = await stripe.getPayoutSnapshot(ctx, {
+  stripeAccountId,
+  cursor,
+  limit: 25,
+});
+```
+
+The snapshot contains per-currency `balances`, cursor-paginated `payouts`,
+deduplicated pending/in-transit `upcoming`, and `nextCursor`. Arrival dates are
+provider estimates, nullable, in milliseconds. `upcomingComplete: false` means
+only a bounded preview was retrieved. An unavailable account returns
+`status: "not_ready"` with empty data and a reason; it does not imply a zero balance.
+The React `PayoutSnapshot` contract accepts this shape directly.
+
+A transfer moves money to a connected account; a payout moves that account's
+available balance to its external bank. These boundaries have different controls.
+
+## Combined payout minimums: supported boundary
+
+A single user-level recipient account naturally combines creator and affiliate
+funds across communities. Keep currency balances separate. Only available funds
+are mature; Stripe's available balance already reflects provider debits and known
+reversals. A platform source ledger is still necessary to explain which earnings
+remain owed and distinguish unrelated funds in an already-mixed account.
+
+The supported default is Stripe-managed automatic payouts with no additional
+application minimum. Stripe enforces its applicable currency/method floor. The
+Balance Settings API does not expose a numeric payout-floor field; this package
+does not invent one. `minimum_balance_by_currency` is a retained reserve after a
+payout, **not a minimum payout trigger**. [Stripe reserve documentation](https://docs.stripe.com/payouts/minimum-balances-for-automatic-payouts).
+
+Custom application thresholds need a separately controlled release boundary:
+
+- Before transfer: retain funds on the platform and maintain a durable payable
+  ledger, maturity, adjustments, and release claims. This changes settlement timing
+  and must account for existing transferred balances.
+- Before bank payout: use a manual payout schedule where the platform has
+  permission, and run an automatic application job. Otherwise provider automatic
+  sweeps can bypass the application threshold. A retained reserve cannot fix that.
+
+Manual holding limits depend on country: Thailand 10 days, US 2 years, other
+countries generally 90 days. Schedule permissions depend on account controls and
+liability. Negative balances, refunds, and in-flight payouts must reduce any
+release amount; source-category thresholds and currency netting are unsafe.
+See [payout schedule permissions](https://docs.stripe.com/connect/manage-payout-schedule)
+and [manual payout restrictions](https://docs.stripe.com/connect/manual-payouts).
+
+Custom threshold enforcement is not provided by the snapshot or settlement APIs.
+It requires a selected retention boundary and migration policy. Applications must
+not describe a displayed threshold as enforced while Stripe controls automatic
+payouts. A numeric below/exact/above provider-floor demonstration is unavailable
+without a supported provider floor read; surface this capability limitation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",
@@ -58,6 +58,8 @@
     "dist",
     "src",
     "docs/react-workflows.md",
+    "docs/settlement.md",
+    "docs/accounts-v2-preview.md",
     "docs/react-workflows-audit.md",
     "CHANGELOG.md",
     "MIGRATION.md"

package/src/client/apiVersion.ts

@@ -0,0 +1,20 @@
+import { STRIPE_API_VERSION } from "./constants.js";
+import { throwStripeError } from "./errors.js";
+/** Explicit opt-in for Stripe's customer-only Accounts v2 public preview. */
+export const STRIPE_CUSTOMER_PREVIEW_API_VERSION = "2026-09-30.preview";
+export type SupportedStripeApiVersion =
+  typeof STRIPE_API_VERSION | typeof STRIPE_CUSTOMER_PREVIEW_API_VERSION;
+export function resolveStripeApiVersion(
+  version?: string,
+): SupportedStripeApiVersion {
+  if (version === undefined) return STRIPE_API_VERSION;
+  if (
+    version === STRIPE_API_VERSION ||
+    version === STRIPE_CUSTOMER_PREVIEW_API_VERSION
+  )
+    return version;
+  throwStripeError(
+    "INVALID_CONFIGURATION",
+    `Unsupported Stripe API version. Use ${STRIPE_API_VERSION} or ${STRIPE_CUSTOMER_PREVIEW_API_VERSION}.`,
+  );
+}

package/src/client/billing/checkout-idempotency.test.ts

@@ -0,0 +1,82 @@
+import { expect, it, vi } from "vitest";
+import type Stripe from "stripe";
+import { componentsGeneric } from "convex/server";
+import type { Component, RunCtx } from "../helpers.js";
+import { createCheckoutSession } from "./checkout.js";
+function makeStripe() {
+  return {
+    prices: {
+      retrieve: vi.fn().mockRejectedValue({ code: "resource_missing" }),
+    },
+    checkout: { sessions: { create: vi.fn() } },
+  };
+}
+function makeCtx() {
+  return {
+    runQuery: vi.fn().mockResolvedValue(null),
+    runMutation: vi.fn().mockResolvedValue(undefined),
+  } as unknown as RunCtx & { runMutation: ReturnType<typeof vi.fn> };
+}
+const makeComponent = () =>
+  componentsGeneric().betterStripe as unknown as Component;
+const asStripe = (value: ReturnType<typeof makeStripe>) =>
+  value as unknown as Stripe;
+function sessionResponse(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "cs_test",
+    status: "open",
+    client_secret: "secret",
+    url: null,
+    ...overrides,
+  };
+}
+
+it("forwards an order key as request options and recovers persistence without another session", async () => {
+  const stripe = makeStripe(),
+    ctx = makeCtx();
+  const cache = new Map<
+    string,
+    { params: string; session: ReturnType<typeof sessionResponse> }
+  >();
+  stripe.checkout.sessions.create.mockImplementation(
+    async (params, options?: { idempotencyKey?: string }) => {
+      const key = options?.idempotencyKey ?? `new-${cache.size}`,
+        prior = cache.get(key),
+        serialized = JSON.stringify(params);
+      if (prior && prior.params !== serialized)
+        throw new Error("idempotency_error");
+      if (prior) return prior.session;
+      const session = sessionResponse({ id: `cs_${cache.size}` });
+      cache.set(key, { params: serialized, session });
+      return session;
+    },
+  );
+  const opts = {
+    userId: "buyer",
+    stripePriceId: "price_1",
+    mode: "payment" as const,
+    returnUrl: "https://app.test/receipt",
+    idempotencyKey: "order:one",
+  };
+  ctx.runMutation.mockRejectedValueOnce(new Error("persistence unavailable"));
+  await expect(
+    createCheckoutSession(asStripe(stripe), makeComponent(), ctx, opts),
+  ).rejects.toThrow("persistence unavailable");
+  await createCheckoutSession(asStripe(stripe), makeComponent(), ctx, opts);
+  expect(cache.size).toBe(1);
+  expect(stripe.checkout.sessions.create).toHaveBeenLastCalledWith(
+    expect.anything(),
+    { idempotencyKey: "order:one" },
+  );
+  await createCheckoutSession(asStripe(stripe), makeComponent(), ctx, {
+    ...opts,
+    idempotencyKey: "order:two",
+  });
+  expect(cache.size).toBe(2);
+  await expect(
+    createCheckoutSession(asStripe(stripe), makeComponent(), ctx, {
+      ...opts,
+      stripePriceId: "price_other",
+    }),
+  ).rejects.toThrow("idempotency_error");
+});

package/src/client/billing/checkout.ts

@@ -1,3 +1,4 @@
+import { idempotencyOptions } from "../core/idempotency.js";
 import type Stripe from "stripe";
 
 import type { SplitRecipient } from "../../component/lib/fees.js";
@@ -110,6 +111,7 @@ export async function createCheckoutSession(
   component: Component,
   ctx: RunCtx,
   opts: {
+    idempotencyKey?: string;
     userId: string;
     orgId?: string;
     stripePriceId: string;
@@ -338,7 +340,10 @@ export async function createCheckoutSession(
     await assertPlatformPrice(stripe, component, ctx, finalPriceId);
   }
 
-  const session = await stripe.checkout.sessions.create(finalSessionParams);
+  const requestOptions = idempotencyOptions(opts.idempotencyKey);
+  const session = requestOptions
+    ? await stripe.checkout.sessions.create(finalSessionParams, requestOptions)
+    : await stripe.checkout.sessions.create(finalSessionParams);
 
   await runMutationOrThrow(
     ctx,

package/src/client/billing/providerReads.test.ts

@@ -0,0 +1,60 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import {
+  getCheckoutSessionFromStripe,
+  getSubscriptionFromStripe,
+  getCouponFromStripe,
+} from "./providerReads.js";
+it("retrieves authoritative expanded provider objects without consulting the component cache", async () => {
+  const raw = {
+    checkout: {
+      sessions: {
+        retrieve: vi
+          .fn()
+          .mockResolvedValue({ id: "cs_1", payment_status: "paid" }),
+      },
+    },
+    subscriptions: {
+      retrieve: vi.fn().mockResolvedValue({ id: "sub_1", status: "active" }),
+    },
+    coupons: {
+      retrieve: vi.fn().mockResolvedValue({ id: "coupon_1", valid: true }),
+    },
+  };
+  const stripe = raw as unknown as Stripe;
+  expect(
+    await getCheckoutSessionFromStripe(stripe, {
+      stripeSessionId: "cs_1",
+      expand: ["subscription", "payment_intent"],
+    }),
+  ).toMatchObject({ payment_status: "paid" });
+  expect(raw.checkout.sessions.retrieve).toHaveBeenCalledWith("cs_1", {
+    expand: ["subscription", "payment_intent"],
+  });
+  await getSubscriptionFromStripe(stripe, {
+    stripeSubscriptionId: "sub_1",
+    expand: ["latest_invoice"],
+  });
+  expect(raw.subscriptions.retrieve).toHaveBeenCalledWith("sub_1", {
+    expand: ["latest_invoice"],
+  });
+  await getCouponFromStripe(stripe, { stripeCouponId: "coupon_1" });
+  expect(raw.coupons.retrieve).toHaveBeenCalledWith("coupon_1", {
+    expand: undefined,
+  });
+});
+
+it("preserves Stripe error identity and codes for server reconciliation", async () => {
+  const failure = Object.assign(new Error("No such Checkout Session"), {
+    code: "resource_missing",
+    statusCode: 404,
+  });
+  const raw = {
+    checkout: { sessions: { retrieve: vi.fn().mockRejectedValue(failure) } },
+  };
+  await expect(
+    getCheckoutSessionFromStripe(raw as unknown as Stripe, {
+      stripeSessionId: "cs_missing",
+    }),
+  ).rejects.toBe(failure);
+});

package/src/client/billing/providerReads.ts

@@ -0,0 +1,30 @@
+import type Stripe from "stripe";
+export type CheckoutSessionReadOptions = {
+  stripeSessionId: string;
+  expand?: string[];
+};
+export type SubscriptionReadOptions = {
+  stripeSubscriptionId: string;
+  expand?: string[];
+};
+export type CouponReadOptions = { stripeCouponId: string; expand?: string[] };
+/** Authoritative Stripe objects for authorized server fulfillment/reconciliation. */
+export function getCheckoutSessionFromStripe(
+  stripe: Stripe,
+  opts: CheckoutSessionReadOptions,
+) {
+  return stripe.checkout.sessions.retrieve(opts.stripeSessionId, {
+    expand: opts.expand,
+  });
+}
+export function getSubscriptionFromStripe(
+  stripe: Stripe,
+  opts: SubscriptionReadOptions,
+) {
+  return stripe.subscriptions.retrieve(opts.stripeSubscriptionId, {
+    expand: opts.expand,
+  });
+}
+export function getCouponFromStripe(stripe: Stripe, opts: CouponReadOptions) {
+  return stripe.coupons.retrieve(opts.stripeCouponId, { expand: opts.expand });
+}

package/src/client/billing/subscriptions.ts

@@ -511,14 +511,7 @@ export async function upsertSubscription(
     accountId?: string;
     userId: string;
     orgId?: string;
-    status:
-      | "active"
-      | "trialing"
-      | "past_due"
-      | "canceled"
-      | "incomplete"
-      | "unpaid"
-      | "paused";
+    status: SubscriptionStatus;
     priceId?: string;
     quantity?: number;
     currentPeriodStart?: string;

package/src/client/connect/payoutSnapshot.test.ts

@@ -0,0 +1,91 @@
+import type Stripe from "stripe";
+import { expect, it, vi } from "vitest";
+import { getPayoutSnapshot } from "./payoutSnapshot.js";
+const payout = (id: string, status = "paid") => ({
+  id,
+  status,
+  amount: 1000,
+  currency: "usd",
+  arrival_date: 0,
+  created: 1,
+});
+it("scopes every read and uses a real cursor for history while completing upcoming pages", async () => {
+  const list = vi.fn(
+    async (
+      args: { status?: string; starting_after?: string },
+      _options: { stripeAccount: string },
+    ) => {
+      void _options;
+      if (args.status === "pending")
+        return args.starting_after
+          ? { data: [payout("po_2", "pending")], has_more: false }
+          : { data: [payout("po_1", "pending")], has_more: true };
+      if (args.status === "in_transit")
+        return { data: [payout("po_1", "pending")], has_more: false };
+      return { data: [payout("po_history")], has_more: true };
+    },
+  );
+  const raw = {
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({
+        available: [{ currency: "usd", amount: 10 }],
+        pending: [{ currency: "eur", amount: 20 }],
+      }),
+    },
+    payouts: { list },
+  };
+  const result = await getPayoutSnapshot(raw as unknown as Stripe, {
+    stripeAccountId: "acct_a",
+    cursor: "po_before",
+  });
+  expect(result).toMatchObject({
+    status: "ready",
+    balances: [
+      { currency: "usd", available: 10, pending: 0 },
+      { currency: "eur", available: 0, pending: 20 },
+    ],
+    nextCursor: "po_history",
+    upcomingComplete: true,
+  });
+  expect(result.upcoming.map((r) => r.id)).toEqual(["po_1", "po_2"]);
+  expect(result.upcoming[0].arrivalDate).toBeNull();
+  expect(list).toHaveBeenCalledWith(
+    expect.objectContaining({ starting_after: "po_before" }),
+    { stripeAccount: "acct_a" },
+  );
+  expect(
+    list.mock.calls.every(
+      (call) =>
+        (call[1] as { stripeAccount: string }).stripeAccount === "acct_a",
+    ),
+  ).toBe(true);
+});
+it("reports bounded upcoming previews and not-ready accounts explicitly", async () => {
+  const raw = {
+    balance: {
+      retrieve: vi.fn().mockResolvedValue({ available: [], pending: [] }),
+    },
+    payouts: {
+      list: vi.fn().mockResolvedValue({
+        data: [payout("po_1", "pending")],
+        has_more: true,
+      }),
+    },
+  };
+  expect(
+    await getPayoutSnapshot(raw as unknown as Stripe, {
+      stripeAccountId: "acct_a",
+      maxUpcomingPages: 1,
+    }),
+  ).toMatchObject({ upcomingComplete: false });
+  raw.balance.retrieve.mockRejectedValue({ code: "account_invalid" });
+  expect(
+    await getPayoutSnapshot(raw as unknown as Stripe, {
+      stripeAccountId: "acct_a",
+    }),
+  ).toMatchObject({
+    status: "not_ready",
+    balances: [],
+    reason: "account_unavailable",
+  });
+});

package/src/client/connect/payoutSnapshot.ts

@@ -0,0 +1,130 @@
+import type Stripe from "stripe";
+import { throwStripeError } from "../errors.js";
+import { getAccountBalance, type AccountBalance } from "./payouts.js";
+export type RecipientPayoutRow = {
+  id: string;
+  amount: number;
+  currency: string;
+  status: string;
+  arrivalDate: number | null;
+  created: number;
+};
+export type RecipientPayoutSnapshot = {
+  balances: AccountBalance[];
+  payouts: RecipientPayoutRow[];
+  upcoming: RecipientPayoutRow[];
+  nextCursor: string | null;
+  status: "ready" | "not_ready";
+  reason?: string;
+  upcomingComplete: boolean;
+};
+export type PayoutSnapshotOptions = {
+  stripeAccountId: string;
+  cursor?: string;
+  limit?: number;
+  maxUpcomingPages?: number;
+};
+const row = (p: Stripe.Payout): RecipientPayoutRow => ({
+  id: p.id,
+  amount: p.amount,
+  currency: p.currency,
+  status: p.status,
+  arrivalDate: p.arrival_date ? p.arrival_date * 1000 : null,
+  created: p.created * 1000,
+});
+/** Account-scoped live balance and cursor history. Upcoming truncation is explicit. */
+export async function getPayoutSnapshot(
+  stripe: Stripe,
+  opts: PayoutSnapshotOptions,
+): Promise<RecipientPayoutSnapshot> {
+  const limit = opts.limit ?? 100,
+    maxPages = opts.maxUpcomingPages ?? 10;
+  if (
+    !opts.stripeAccountId ||
+    !Number.isInteger(limit) ||
+    limit < 1 ||
+    limit > 100 ||
+    !Number.isInteger(maxPages) ||
+    maxPages < 1 ||
+    maxPages > 100
+  )
+    throwStripeError(
+      "INVALID_CONFIGURATION",
+      "Invalid payout account or page bounds.",
+    );
+  const options = { stripeAccount: opts.stripeAccountId };
+  async function upcoming(status: "pending" | "in_transit") {
+    const rows: Stripe.Payout[] = [];
+    let cursor: string | undefined;
+    for (let page = 0; page < maxPages; page++) {
+      const batch = await stripe.payouts.list(
+        { status, limit: 100, starting_after: cursor },
+        options,
+      );
+      rows.push(...batch.data);
+      if (!batch.has_more) return { rows, complete: true };
+      const next = batch.data[batch.data.length - 1]?.id;
+      if (!next || next === cursor)
+        throwStripeError(
+          "STRIPE_API_ERROR",
+          "Stripe payout pagination did not advance.",
+        );
+      cursor = next;
+    }
+    return { rows, complete: false };
+  }
+  try {
+    const [balances, history, pending, transit] = await Promise.all([
+      getAccountBalance(stripe, opts),
+      stripe.payouts.list({ limit, starting_after: opts.cursor }, options),
+      upcoming("pending"),
+      upcoming("in_transit"),
+    ]);
+    const rows = [
+      ...new Map(
+        [...pending.rows, ...transit.rows]
+          .filter((p) => p.status === "pending" || p.status === "in_transit")
+          .map((p) => [p.id, row(p)]),
+      ).values(),
+    ].sort(
+      (a, b) =>
+        (a.arrivalDate ?? Infinity) - (b.arrivalDate ?? Infinity) ||
+        a.created - b.created,
+    );
+    if (history.has_more && !history.data.length)
+      throwStripeError(
+        "STRIPE_API_ERROR",
+        "Stripe payout history did not advance.",
+      );
+    return {
+      status: "ready",
+      balances,
+      payouts: history.data.map(row),
+      upcoming: rows,
+      nextCursor: history.has_more
+        ? history.data[history.data.length - 1]!.id
+        : null,
+      upcomingComplete: pending.complete && transit.complete,
+    };
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      ["account_invalid", "resource_missing"].includes(String(error.code))
+    )
+      return {
+        status: "not_ready",
+        reason: "account_unavailable",
+        balances: [],
+        payouts: [],
+        upcoming: [],
+        nextCursor: null,
+        upcomingComplete: true,
+      };
+    throwStripeError(
+      "STRIPE_API_ERROR",
+      "Could not retrieve recipient payout snapshot.",
+    );
+  }
+}