@pithy-sh/payments 0.1.0

package/src/rails/providers.ts

@@ -0,0 +1,168 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PaymentsConfig } from "../config/config";
+import { productForProviderSku, railEnabled } from "../config/config";
+import type { PaymentsRail } from "../data/rail";
+import { PaymentsRailNotConfiguredError } from "../error/errors";
+import { type PaymentsProviderCredentials, railCredentials } from "../secret/registry";
+import type { AppleHttpFetch } from "./apple/http";
+import { appleRail } from "./apple/rail";
+import type { PaymentsRailProvider } from "./contract";
+import type { GoogleHttpFetch } from "./google/http";
+import type { GoogleJwk } from "./google/oidc";
+import { googleRail } from "./google/rail";
+import type { LemonSqueezyHttpFetch } from "./lemonSqueezy/api";
+import { lemonSqueezyRail } from "./lemonSqueezy/rail";
+import type { PaddleHttpFetch } from "./paddle/api";
+import { paddleRail } from "./paddle/rail";
+import type { StripeHttpFetch } from "./stripe/api";
+import { stripeRail } from "./stripe/rail";
+
+/**
+ * Which rails this build can speak to, and how one is resolved for a request.
+ *
+ * This is the single composition point. A rail arrives as one entry here plus its module — nothing else in
+ * the package counts rails, and nothing branches on how many there are.
+ *
+ * **Two independent conditions, one answer.** A rail may be off in `pithy.config.ts`, or its credentials may
+ * never have been provisioned, or this build may not implement it yet. All three are
+ * `payments/rail_not_configured` (404), because from the caller's side they are the same statement — that
+ * payment method is not available here — and distinguishing them in a response would describe our deployment
+ * to a stranger. `detail` distinguishes them for the operator, which is where the distinction is useful.
+ */
+
+/**
+ * The per-rail verification seams a caller may supply. Two kinds, and both are narrow on purpose.
+ *
+ * **Trust is additive only**, so nothing here can narrow production's trust: extra roots and extra keys are
+ * *added* to each rail's pinned set, and a payload the extras do not cover is still checked against the store's
+ * own. Each exists for callers with genuinely non-store signing material — the tests, which mint their own so
+ * verification is exercised for real rather than stubbed, and the local development tools that do the same:
+ * Xcode's StoreKit testing signs with a per-machine root, and a Pub/Sub emulator signs with a key Google never
+ * saw.
+ *
+ * **Transport is a seam rather than a policy.** Google's rail cannot verify offline — Play hands out pointers,
+ * not signed state — so it must reach the network, and a network call that could not be substituted could only be
+ * tested through a stub of the module under test. One explicit parameter, defaulting to the runtime's `fetch`.
+ * Every rail now has one, because every rail reaches its store on the reconciliation path even where it verifies
+ * offline: a subscription nobody was notified about can only be learned by asking.
+ *
+ * **The two batch tokens are a cost seam, not a trust one.** Apple's API token and Google's OAuth token are each
+ * bought with a signature and a round-trip, so a reconciliation pass over hundreds of purchases mints one and
+ * passes it down rather than paying twice per purchase. They are parameters rather than a module cache because a
+ * bearer credential derived from a secret is exactly what CLAUDE.md forbids caching in a module variable.
+ */
+export interface RailTrustOptions {
+  /** Roots the Apple rail accepts in addition to Apple's pinned ones, base64 DER. */
+  appleTrustedRoots?: readonly string[];
+  /** The HTTP transport the Apple rail reaches the App Store Server API through. Defaults to `fetch`. */
+  appleTransport?: AppleHttpFetch;
+  /** An App Store Connect token already minted, so a batch of Apple refreshes pays for one. */
+  appleApiToken?: string;
+  /** Keys the Google rail accepts in addition to Google's published set, matched by `kid`. */
+  googleTrustedKeys?: readonly GoogleJwk[];
+  /** The HTTP transport the Google rail reaches Google's endpoints through. Defaults to `fetch`. */
+  googleTransport?: GoogleHttpFetch;
+  /** A Play access token already minted, so a batch of Google refreshes pays for one. */
+  googleAccessToken?: string;
+  /** The HTTP transport the Stripe rail reaches Stripe's API through. Defaults to `fetch`. */
+  stripeTransport?: StripeHttpFetch;
+  /** The HTTP transport the Lemon Squeezy rail reaches its API through. Defaults to `fetch`. */
+  lemonSqueezyTransport?: LemonSqueezyHttpFetch;
+  /** The HTTP transport the Paddle rail reaches its API through. Defaults to `fetch`. */
+  paddleTransport?: PaddleHttpFetch;
+}
+
+/** Build a rail provider from the credential bundle. Each factory takes only its own rail's block. */
+type RailFactory = (
+  credentials: PaymentsProviderCredentials,
+  trust: RailTrustOptions,
+  config: PaymentsConfig,
+) => PaymentsRailProvider;
+
+/**
+ * Every rail this build implements. A rail arrives as one entry here plus its module; an entry with no module
+ * behind it would be a rail that reports itself available and then fails, which is worse than one that reports
+ * itself absent.
+ */
+const RAIL_FACTORIES: Partial<Record<PaymentsRail, RailFactory>> = {
+  apple: (credentials, trust) =>
+    appleRail(railCredentials(credentials, "apple"), {
+      trustedRoots: trust.appleTrustedRoots,
+      transport: trust.appleTransport,
+      apiToken: trust.appleApiToken,
+    }),
+  google: (credentials, trust) =>
+    googleRail(railCredentials(credentials, "google"), {
+      trustedKeys: trust.googleTrustedKeys,
+      transport: trust.googleTransport,
+      accessToken: trust.googleAccessToken,
+    }),
+  stripe: (credentials, trust) =>
+    stripeRail(railCredentials(credentials, "stripe"), { transport: trust.stripeTransport }),
+  lemonSqueezy: (credentials, trust, config) =>
+    lemonSqueezyRail(railCredentials(credentials, "lemonSqueezy"), {
+      transport: trust.lemonSqueezyTransport,
+      // The catalog answers what the store's order object cannot: whether this variant is a subscription.
+      // A Lemon Squeezy variant is one or the other and never both, so the product's declared type is the
+      // whole answer — see `orderNotification` for why the rail must not guess it.
+      sellsSubscription: (variantId) =>
+        productForProviderSku(config, "lemonSqueezy", variantId)?.product.type === "subscription",
+      // Without this the fixed-amount currency guard in `discounts.ts` never runs: it is written to skip
+      // the check when the store's currency is unknown, and nothing was ever telling it. The catalog knows
+      // — a `grants` clause names the currency a product's economy is denominated in.
+      storeCurrency: config.lemonSqueezy?.storeCurrency,
+    }),
+  paddle: (credentials, trust, config) => {
+    // Config is checked before this runs — `resolveRailProvider` refuses a disabled rail, and
+    // `PaymentsConfig` refuses to parse with the rail on and the block absent — so this is the
+    // "enabled, parsed, and somehow still absent" case rather than an adopter's missing three lines.
+    const settings = config.paddle;
+    if (settings === undefined) {
+      throw new PaymentsRailNotConfiguredError({
+        detail:
+          "The paddle rail is on with no `paddle` settings block. Declare `clientToken`, `environment`, and `successUrl`.",
+      });
+    }
+    return paddleRail(railCredentials(credentials, "paddle"), {
+      environment: settings.environment,
+      clientToken: settings.clientToken,
+      checkout: settings.checkout,
+      freshnessSeconds: settings.webhookFreshnessSeconds,
+      storeCurrency: settings.storeCurrency,
+      transport: trust.paddleTransport,
+    });
+  },
+};
+
+/** The rails this build can serve at all, whatever a project's config says. */
+export function implementedRails(): readonly PaymentsRail[] {
+  return Object.keys(RAIL_FACTORIES) as PaymentsRail[];
+}
+
+/**
+ * The provider for one rail, or a 404.
+ *
+ * Config is checked before credentials, so a project that has not enabled a rail never triggers a credential
+ * read for it — a read is a Secrets Store round-trip, and a disabled rail should not cost one.
+ */
+export function resolveRailProvider(
+  rail: PaymentsRail,
+  config: PaymentsConfig,
+  credentials: PaymentsProviderCredentials,
+  trust: RailTrustOptions = {},
+): PaymentsRailProvider {
+  if (!railEnabled(config, rail)) {
+    throw new PaymentsRailNotConfiguredError({
+      detail: `The ${rail} rail is off in this project's config. Set \`rails.${rail}: true\` and redeploy.`,
+    });
+  }
+  const factory = RAIL_FACTORIES[rail];
+  if (!factory) {
+    throw new PaymentsRailNotConfiguredError({
+      detail: `This build of @pithy-sh/payments implements ${implementedRails().join(", ")}, not ${rail}.`,
+    });
+  }
+  return factory(credentials, trust, config);
+}

package/src/rails/stripe/api.ts

@@ -0,0 +1,253 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { PaymentsProviderUnavailableError, PaymentsRailNotConfiguredError } from "../../error/errors";
+
+/**
+ * The one door out to Stripe, and the mapping from how it answered to what that means.
+ *
+ * Stripe is reached with `fetch` and form encoding rather than through the `stripe` npm package, deliberately.
+ * Three calls are needed for hosted-only payments — create a Checkout Session, create a Billing Portal session,
+ * retrieve a Checkout Session — and each is one form POST or GET. The SDK would add a dependency with its own
+ * runtime shims, its own retry policy, and its own idea of what an error is, to save perhaps forty lines. Every
+ * other third-party API in this repo is spoken to the same way: `fetch` out, Zod in.
+ *
+ * **The API version is pinned.** Stripe decides response shapes from the *account's* default version unless a
+ * request names one, so an account upgraded in the dashboard would silently change what this code parses. Pinning
+ * it here means an upgrade is a deliberate edit with a test run behind it. Webhook payload shapes are a separate
+ * matter — those follow the endpoint's own configured version, which is why `objects.ts` accepts both spellings of
+ * the fields Stripe has moved.
+ *
+ * ## How an answer is read
+ *
+ * **A 5xx or a 429 is `payments/provider_unavailable` (503).** Stripe is up but not answering, or is asking us to
+ * slow down. The caller retries and the reconciliation pass covers whatever a retry never fixes.
+ *
+ * **Every other 4xx is `payments/rail_not_configured` (404), and that is the deliberate part.** A 4xx from Stripe
+ * is never the buyer's fault — we build these requests entirely from config and from rows we wrote, so "No such
+ * price", "No such customer", a rejected key, and a missing Billing Portal configuration are all one statement:
+ * this project's Stripe rail is not set up to do what it was asked. 503 would tell a caller to retry something
+ * that will never succeed; 400 would blame a request the caller did not make. 404 says the payment method is not
+ * available here, which is true, and `detail` carries Stripe's own sentence for the operator who can fix it.
+ *
+ * **A 404 is an absent resource only for a caller that said it was probing.** `absentOn404` is how a Checkout
+ * Session retrieve distinguishes "no such session" from "our Stripe account is wrong", and only a caller that
+ * knows the difference may claim it.
+ *
+ * **Nothing in a refusal carries the secret key.** Stripe redacts keys in its own messages, but `detail` is
+ * written to an operator's logs, so anything key-shaped in a message is redacted again here before it gets there.
+ */
+
+/** Stripe's REST base. Public and stable, so it is pinned rather than configured. */
+export const STRIPE_API_BASE = "https://api.stripe.com/v1";
+
+/**
+ * The API version every request pins.
+ *
+ * To move it: read Stripe's changelog for the shape changes between the two, adjust `objects.ts`, run the suite,
+ * and change this line. Never bump it to match an account — the point of pinning is that the account cannot
+ * decide what this code parses.
+ */
+export const STRIPE_API_VERSION = "2025-04-30.basil";
+
+/** One outbound request, narrowed to what Stripe's three endpoints need. */
+export interface StripeHttpRequest {
+  /** The HTTP method. */
+  method?: string;
+  /** Request headers — the bearer key, the pinned version, and a form content type on a POST. */
+  headers?: Record<string, string>;
+  /** The form-encoded body, on a POST. */
+  body?: string;
+}
+
+/** The response shape this module reads. Structural, so a test's transport need not be a whole `Response`. */
+export interface StripeHttpResponse {
+  /** Whether the status is 2xx. */
+  ok: boolean;
+  /** The status code, which is what decides the mapping. */
+  status: number;
+  /** The body as text. Read as text rather than JSON so a non-JSON answer is a diagnosis, not a throw. */
+  text(): Promise<string>;
+}
+
+/**
+ * The HTTP seam for Stripe's endpoints.
+ *
+ * Injectable for one reason: **no test may reach a live Stripe account**, and a rail whose network call could not
+ * be substituted would have to be tested through a stub of itself. One explicit parameter beats reassigning a
+ * global, which leaks between suites and hides which module was exercised.
+ */
+export type StripeHttpFetch = (url: string, init?: StripeHttpRequest) => Promise<StripeHttpResponse>;
+
+/** The default transport: the runtime's own `fetch`. */
+export const stripeHttpFetch: StripeHttpFetch = (url, init) =>
+  fetch(url, init) as unknown as Promise<StripeHttpResponse>;
+
+/** A value Stripe's form encoding can carry. Nested objects and arrays become bracketed keys. */
+export type StripeFormValue = string | number | boolean | null | undefined | StripeFormObject | StripeFormValue[];
+
+/** One level of a Stripe form body. */
+export interface StripeFormObject {
+  [key: string]: StripeFormValue;
+}
+
+/**
+ * Encode a nested object the way Stripe's API reads a form body: `line_items[0][price]=price_1`.
+ *
+ * `URLSearchParams` alone cannot produce that, which is the whole reason this exists. `undefined` and `null` are
+ * dropped rather than sent empty, because Stripe reads an empty value as "unset this field" — so omitting an
+ * optional parameter and sending it blank are two different requests.
+ */
+export function stripeForm(input: StripeFormObject): string {
+  const params = new URLSearchParams();
+  append(params, "", input);
+  return params.toString();
+}
+
+/** What one request is for, and how its answers should be read. */
+export interface StripeJsonOptions {
+  /** What is being fetched, in a `detail` line: "a Checkout Session". Never the URL, never the body. */
+  what: string;
+  /** The Stripe secret key. Read through the secrets store by the caller, never off an env binding. */
+  secretKey: string;
+  /** The form body. Its presence is what makes the request a POST. */
+  form?: StripeFormObject;
+  /** Query parameters, encoded in Stripe's own bracket notation — `expand[0]=subscription`. */
+  query?: StripeFormObject;
+  /**
+   * Whether a 404 means "no such resource" rather than a misconfigured account. Set only by a caller that is
+   * deliberately probing for something that may legitimately not exist.
+   */
+  absentOn404?: boolean;
+}
+
+/** Stripe's error envelope, as much of it as a `detail` line needs. */
+const StripeApiError = z
+  .object({
+    error: z
+      .object({
+        type: z.string().min(1).optional().describe("Stripe's error class — `invalid_request_error`, `api_error`."),
+        code: z.string().min(1).optional().describe("The machine-readable reason — `resource_missing`."),
+        param: z.string().min(1).optional().describe("Which request parameter Stripe blamed."),
+        message: z.string().min(1).optional().describe("Stripe's own sentence. Redacted before it reaches a log."),
+      })
+      .loose()
+      .describe("The error Stripe reported."),
+  })
+  .loose()
+  .describe("Stripe's error response envelope.");
+
+/**
+ * One request to Stripe, and its parsed JSON body — or `undefined` when a 404 was a legitimate answer.
+ *
+ * The body comes back as `unknown`. Reaching an endpoint proves who answered, never what they said, so every
+ * caller Zod-parses its own shape.
+ */
+export async function stripeJson(
+  transport: StripeHttpFetch,
+  path: string,
+  options: StripeJsonOptions,
+): Promise<unknown | undefined> {
+  const query = options.query === undefined ? "" : `?${stripeForm(options.query)}`;
+  const url = `${STRIPE_API_BASE}${path}${query}`;
+  const headers: Record<string, string> = {
+    authorization: `Bearer ${options.secretKey}`,
+    "stripe-version": STRIPE_API_VERSION,
+  };
+  if (options.form !== undefined) headers["content-type"] = "application/x-www-form-urlencoded";
+
+  let response: StripeHttpResponse;
+  try {
+    response = await transport(url, {
+      method: options.form === undefined ? "GET" : "POST",
+      headers,
+      body: options.form === undefined ? undefined : stripeForm(options.form),
+    });
+  } catch (cause) {
+    throw new PaymentsProviderUnavailableError(
+      { detail: `Stripe did not answer when asked for ${options.what}.` },
+      { cause },
+    );
+  }
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    if (response.status === 404 && options.absentOn404) return undefined;
+    throw refusal(response.status, text, options);
+  }
+
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (cause) {
+    throw new PaymentsProviderUnavailableError(
+      { detail: `Stripe answered with a non-JSON body when asked for ${options.what}.` },
+      { cause },
+    );
+  }
+}
+
+/** The refusal for a non-2xx answer: retryable if Stripe is struggling, a configuration failure otherwise. */
+function refusal(status: number, body: string, options: StripeJsonOptions): PaymentsProviderUnavailableError {
+  if (status === 429 || status >= 500) {
+    return new PaymentsProviderUnavailableError({
+      detail: `Stripe answered ${status} when asked for ${options.what}. ${stripeSaid(body)}`,
+    });
+  }
+
+  const key = status === 401 || status === 403 ? " Check the secret key stored for this environment." : "";
+  return new PaymentsRailNotConfiguredError({
+    detail: `Stripe refused the request for ${options.what} with ${status}.${key} ${stripeSaid(body)}`,
+  });
+}
+
+/** Stripe's own account of the failure, redacted. Empty when the body was not a Stripe error envelope. */
+function stripeSaid(body: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(body) as unknown;
+  } catch {
+    return "";
+  }
+  const envelope = StripeApiError.safeParse(parsed);
+  if (!envelope.success) return "";
+  const { type, code, param, message } = envelope.data.error;
+  const parts = [type, code, param === undefined ? undefined : `param ${param}`, message].filter(
+    (part): part is string => part !== undefined,
+  );
+  return parts.length === 0 ? "" : `Stripe said: ${redactStripeSecrets(parts.join(" / "))}.`;
+}
+
+/**
+ * Blank out anything key-shaped in text bound for a log.
+ *
+ * Stripe already redacts keys in its messages, so this is belt and braces — but `detail` is written to an
+ * operator's logs and read by whoever has them, and a credential that reaches one has to be rotated. Cheap
+ * insurance against a message format changing.
+ */
+export function redactStripeSecrets(text: string): string {
+  return text.replace(
+    /\b(sk|rk|whsec)_(test_|live_)?[A-Za-z0-9]+/g,
+    (_match, prefix, mode) => `${prefix}_${mode ?? ""}…`,
+  );
+}
+
+/** Append one value under a bracketed key path, recursing into objects and arrays. */
+function append(params: URLSearchParams, prefix: string, value: StripeFormValue): void {
+  if (value === undefined || value === null) return;
+
+  if (Array.isArray(value)) {
+    for (const [index, entry] of value.entries()) append(params, `${prefix}[${index}]`, entry);
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const [key, entry] of Object.entries(value)) {
+      append(params, prefix === "" ? key : `${prefix}[${key}]`, entry);
+    }
+    return;
+  }
+
+  params.append(prefix, String(value));
+}

package/src/rails/stripe/checkout.ts

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import { encodeSubjectReference } from "../../data/subject";
+import { PaymentsDiscountInvalidError, PaymentsProviderUnavailableError } from "../../error/errors";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import type { CheckoutHandoff, CheckoutSessionInput } from "../contract";
+import { type StripeFormObject, type StripeHttpFetch, stripeHttpFetch, stripeJson } from "./api";
+import { STRIPE_METADATA_ACCOUNT_REFERENCE, STRIPE_METADATA_PRICE } from "./objects";
+
+/**
+ * Hosted Checkout, and nothing else.
+ *
+ * Stripe presents the payment page, handles the card, and owns SCA, tax, and every regulatory surface that comes
+ * with taking money. Pithy sends a browser there and hears the outcome on a webhook. There is no Payment Element
+ * here and no card fields, and nothing computes proration or tax — that half of issue #79's locked decision 2
+ * still stands, and it is the difference between a backend kit and a payments processor.
+ *
+ * **The other half was amended on 2026-08-28: the kit may now *invoke* a plan change**, passing the store's own
+ * figures through unmodified — see {@link SubscriptionRail} in `rails/contract.ts` for the line between asking a
+ * store what a change costs and answering that question ourselves. **Stripe does not implement it.** Paddle is
+ * the only rail that does, so a Stripe subscriber changes plan in the Billing Portal exactly as before, and
+ * `providers.test.ts` is where that stops being a claim. The amendment permits the seam; it does not oblige
+ * every rail to have one.
+ *
+ * ## What this call puts on the session, and why each of them
+ *
+ * **`client_reference_id`, the resolved subject as `encodeSubjectReference` writes it.** A Stripe purchase is only
+ * ever heard about through a webhook, and that webhook carries `cus_…` and no Pithy holder. This is the pairing,
+ * and it is the reason the `/checkout` route resolves the subject through the configured seam and never from a
+ * request body: a client that could name it could attach its purchase to somebody else's account — or, worse,
+ * attach somebody else's purchase to its own.
+ *
+ * **Both halves of the subject, always — `user:ada`, never `ada`.** Nothing keeps an organization id from
+ * equalling some user's, so an id alone paired with a kind at the far end would eventually grant one holder's
+ * subscription to the other. The bare id is also what this rail stamped before subjects existed, and
+ * `decodeSubjectReference` refuses it on purpose: a lenient read would attribute a stranger's renewal to whoever
+ * holds that id. So a stamp that is not the encoding orphans its purchase, which is the safe direction and the
+ * reason nothing here builds the string by hand.
+ *
+ * **The same reference in `metadata`, and again in `subscription_data[metadata]`.** Stripe copies subscription
+ * metadata onto the subscription it creates, so every later `customer.subscription.*` event carries the pairing
+ * too. Without that, Stripe delivering `customer.subscription.created` before `checkout.session.completed` — which
+ * it may — would leave the first renewal notification with nobody to project it against.
+ *
+ * **The price id in `metadata`.** A Checkout Session's `line_items` are expandable, and a webhook payload never
+ * expands anything, so the price a session was created for is otherwise unknowable from its own notification.
+ *
+ * **The customer, when the buyer already has one.** One buyer, one Stripe customer. Left out, every checkout mints
+ * a fresh customer and a buyer's second purchase would be invisible from the billing portal their first one made.
+ * On a first one-time purchase there is no customer to reuse, so Stripe is asked to create one — payment mode
+ * makes none by default, and a one-time buyer would otherwise never enter the account map at all.
+ */
+
+/** What creating a session needs beyond the input: the API key, and the transport to reach Stripe through. */
+export interface StripeCheckoutOptions {
+  /** Stripe's credential block. Only `secretKey` is used here. */
+  credentials: PaymentsStripeCredentials;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: StripeHttpFetch;
+}
+
+/** A created hosted session, narrowed to the one field a browser needs. */
+const StripeHostedSession = z
+  .object({
+    id: z.string().min(1).describe("The session id. Returned to the browser in the success URL's template token."),
+    url: z
+      .string()
+      .min(1)
+      .describe("The hosted page to send the browser to. Absent only for an embedded session, which this is not."),
+  })
+  .loose()
+  .describe("A hosted Stripe session — Checkout or Billing Portal — as much of it as a redirect needs.");
+
+/** Create a hosted Checkout Session for one product, and return where to send the browser. */
+export async function createStripeCheckoutSession(
+  input: CheckoutSessionInput,
+  options: StripeCheckoutOptions,
+): Promise<CheckoutHandoff> {
+  // Resolved before the session is created, so an unusable code is refused as a *code* rather than
+  // surfacing later as a failed checkout. See {@link resolvePromotionCode}.
+  const promotionCodeId =
+    input.discountCode === undefined ? undefined : await resolvePromotionCode(input.discountCode, options);
+
+  // One encoding, from the one function. See `data/subject.ts` — the value goes out here and comes back
+  // through `decodeSubjectReference` on the webhook, and a second spelling anywhere breaks that loop.
+  const accountReference = encodeSubjectReference(input.subject);
+  const reference = { [STRIPE_METADATA_ACCOUNT_REFERENCE]: accountReference };
+  const metadata = { ...reference, [STRIPE_METADATA_PRICE]: input.providerProductId };
+
+  const form: StripeFormObject = {
+    mode: input.subscription ? "subscription" : "payment",
+    line_items: [{ price: input.providerProductId, quantity: 1 }],
+    success_url: input.successUrl,
+    cancel_url: input.cancelUrl,
+    // The resolved subject, both halves. Never a value from a request body — see the module doc.
+    client_reference_id: accountReference,
+    metadata,
+    customer: input.providerAccountId ?? undefined,
+    // Stripe refuses `customer` and `customer_creation` together, and there is nothing to create when the buyer
+    // already has one.
+    customer_creation: input.subscription || input.providerAccountId ? undefined : "always",
+    // Each is legal only in its own mode, so they are mutually exclusive rather than both set.
+    subscription_data: input.subscription ? { metadata: reference } : undefined,
+    payment_intent_data: input.subscription ? undefined : { metadata },
+    // The code, handed over exactly as the caller typed it. Stripe resolves it to a promotion code and
+    // computes the price; nothing here validates it, looks it up, or multiplies anything — the provider is
+    // the authority on what is owed, and a second calculation would be a second answer to the one question a
+    // customer checks against their statement.
+    //
+    // `allow_promotion_codes` is deliberately NOT set alongside it: Stripe refuses a session carrying both,
+    // and the two are different products anyway — one applies a code this project chose, the other puts a
+    // box on Stripe's page for the customer to fill in.
+    discounts: promotionCodeId === undefined ? undefined : [{ promotion_code: promotionCodeId }],
+  };
+
+  const created = await stripeJson(options.transport ?? stripeHttpFetch, "/checkout/sessions", {
+    what: "a Checkout Session",
+    secretKey: options.credentials.secretKey,
+    form,
+  });
+
+  return hostedSession(created, "a Checkout Session");
+}
+
+/** Read a created session's URL, or refuse. Shared with the Billing Portal, which answers the same shape. */
+export function hostedSession(created: unknown, what: string): CheckoutHandoff & { kind: "redirect" } {
+  const parsed = StripeHostedSession.safeParse(created);
+  if (!parsed.success) {
+    // Stripe created something and did not tell us where to send the browser. Nothing here can recover from that,
+    // and a redirect to an absent URL is worse than a refusal the caller can retry.
+    throw new PaymentsProviderUnavailableError({
+      detail: `Stripe created ${what} with no URL to redirect to.`,
+    });
+  }
+  return { kind: "redirect", url: parsed.data.url };
+}
+
+/**
+ * Turn the code a customer typed into the promotion code id Stripe's session wants.
+ *
+ * Stripe's `discounts[].promotion_code` takes a `promo_…` id, not the customer-facing string, so this lookup
+ * is unavoidable. It is also where the code's validity is learned, and learning it *here* is what makes the
+ * refusal a good one: an unknown, expired or exhausted code is refused before a session exists, as
+ * `payments/discount_invalid` naming the code, rather than becoming a checkout that fails in front of the
+ * customer with nothing to say but that something went wrong.
+ *
+ * `active: true` is part of the query rather than a check afterwards, so an expired or exhausted code simply
+ * does not come back. Stripe decides what active means — Pithy does not read `expires_at` or count
+ * redemptions itself, for the same reason it does not compute the discounted price.
+ */
+async function resolvePromotionCode(code: string, options: StripeCheckoutOptions): Promise<string> {
+  const found = await stripeJson(options.transport ?? stripeHttpFetch, "/promotion_codes", {
+    what: `the discount code ${code}`,
+    secretKey: options.credentials.secretKey,
+    query: { code, active: true, limit: 1 },
+  });
+
+  const parsed = StripePromotionCodes.safeParse(found);
+  const promotion = parsed.success ? parsed.data.data[0] : undefined;
+  if (promotion === undefined) {
+    throw new PaymentsDiscountInvalidError({
+      message: `"${code}" is not a discount code we can accept.`,
+      detail: `Stripe has no active promotion code matching "${code}" — unknown, expired, or fully redeemed.`,
+    });
+  }
+  return promotion.id;
+}
+
+/** Stripe's promotion-code list, narrowed to the id a session needs. */
+const StripePromotionCodes = z
+  .object({ data: z.array(z.object({ id: z.string().min(1) }).loose()) })
+  .loose()
+  .describe("A Stripe promotion-code list response.");