@volter/twin-stripe 0.1.0 → 0.1.2

package/src/stripe-twin.ts

@@ -12,7 +12,7 @@ import { applyTwinWrite } from '@volter/twin';
 import { projectResources } from '@volter/twin';
 import { hashFieldValue } from '@volter/twin';
 import { parseStripeForm } from './stripe-form.ts';
-import { emitStripeEvent, eventTypeFor, registerStripeWebhook, unregisterStripeWebhook } from './stripe-events.ts';
+import { emitStripeEvent, eventTypeFor, registerStripeWebhook, requestAuthorizationDecision, STRIPE_WEBHOOK_FALLBACK_SECRET, stripeEventMatches, unregisterStripeWebhook, type StripeEvent } from './stripe-events.ts';
 
 const SERVICE = 'stripe';
 
@@ -168,12 +168,26 @@ function resolveCardRef(params: Record<string, unknown>): string | undefined {
 // params AND the params the PaymentIntent/charge was created with (Stripe accepts the
 // payment_method at either step). null = explicit success; undefined = no known test
 // card (→ default success, keeps existing tests green); object = decline.
-function declineFor(...paramSets: Array<Record<string, unknown>>): DeclineOutcome | null | undefined {
+//
+// `root` (when given) additionally lets a ref that isn't a raw PAN or named token —
+// i.e. a real attached PaymentMethod id like `pm_twin_3` — resolve against the decline
+// outcome captured on that PaymentMethod at creation time (see `_declineOutcome` in the
+// POST /v1/payment_methods handler). Without this, a card created from a declining test
+// PAN would only ever decline on the SAME request that created it — any later charge
+// that references it purely by id (the normal shape for a saved-card/off-session charge,
+// e.g. an invoice retry) could never reproduce the decline.
+function declineFor(root: string | undefined, ...paramSets: Array<Record<string, unknown>>): DeclineOutcome | null | undefined {
   for (const params of paramSets) {
     const ref = resolveCardRef(params);
     if (ref === undefined) continue;
     if (ref in TEST_CARD_DECLINES) return TEST_CARD_DECLINES[ref];
     if (ref in TEST_TOKEN_DECLINES) return TEST_TOKEN_DECLINES[ref];
+    if (root) {
+      const pm = getOne('payment_method', ref, root);
+      if (pm && Object.prototype.hasOwnProperty.call(pm, '_declineOutcome')) {
+        return pm._declineOutcome as DeclineOutcome | null;
+      }
+    }
   }
   return undefined;
 }
@@ -280,6 +294,18 @@ function nextId(type: string, root?: string): string {
   }
   return `${prefix}_twin_${max + 1}`;
 }
+// Real Stripe embeds the resource's OWN id inside its client_secret (format
+// `<id>_secret_<random>`) — Stripe.js's confirmPayment/confirmSetup parse the id back
+// out of the client_secret (splitting on `_secret`) to build the same-origin confirm
+// URL (`/v1/payment_intents/<id>/confirm`), rather than being told the id separately.
+// A secret that doesn't carry the real id breaks that round trip: a browser Stripe.js
+// call would try to confirm a resource whose id it invented from the string
+// (`'pi_twin_secret'` → `'pi_twin'`, which was never actually created). Every PI/SI a
+// caller might confirm CLIENT-SIDE (real Stripe.js — see the QA proxy's browserRouting
+// in packages/twin/stripe/src/index.ts) must mint a secret this way.
+function mintClientSecret(id: string): string {
+  return `${id}_secret_twin`;
+}
 // Stripe resource view: inject `object` + `id`, drop kernel meta.
 //
 // The kernel reserves the field name `type` as its resource-type discriminator, so a
@@ -353,10 +379,28 @@ export const OBJECT_NAME: Record<string, string> = {
   // Forwarding + Crypto onramp.
   forwarding_request: 'forwarding.request', onramp_session: 'crypto.onramp_session',
 };
-function view(type: string, r: Record<string, unknown>): Record<string, unknown> {
-  const { type: _t, updatedAt: _u, _stripe_type, ...rest } = r;
+// Exported for the pack's own modules that must render the SAME vendor view of a stored
+// resource (stripe-emit.ts synthesizes `data.object` for emitted events from it) — one
+// projection, no drift. Not a public API for consumers.
+export function view(type: string, r: Record<string, unknown>): Record<string, unknown> {
+  // `_subscription_data` is twin-internal (a Checkout Session's create-only
+  // subscription_data, held for the completion transition to copy onto the created
+  // subscription) — real Stripe never returns it on the Session, so strip it here.
+  const { type: _t, updatedAt: _u, _stripe_type, _subscription_data, ...rest } = r;
   const out: Record<string, unknown> = { object: OBJECT_NAME[type] ?? type, ...rest, id: r.id };
   if (_stripe_type !== undefined) out.type = _stripe_type;
+  // Stripe's 2025-03-31.basil API moved an invoice's subscription linkage under
+  // `parent.subscription_details` (the top-level `subscription` field is gone there).
+  // Apps pinned to basil — and the webhook payloads such an account receives — read the
+  // subscription id from that block. Emit BOTH shapes: the legacy top-level field this
+  // twin's default version (TWIN_API_VERSION) serves, plus the basil block, so a
+  // consumer on either side of the migration resolves the same subscription.
+  if (type === 'invoice' && out.parent === undefined) {
+    const subscription = typeof out.subscription === 'string' ? out.subscription : null;
+    out.parent = subscription
+      ? { type: 'subscription_details', quote_details: null, subscription_details: { metadata: {}, subscription } }
+      : null;
+  }
   return out;
 }
 // Real Stripe list pagination. Honors limit (default 10, max 100, min 1),
@@ -408,6 +452,7 @@ async function writeResource(
 ): Promise<Record<string, unknown>> {
   const { resource } = await applyTwinWrite(SERVICE, { operation: op, subjectType: type, subjectId: id, fields, ...(occurredAt ? { occurredAt } : {}), actor: { kind: 'agent' } }, root);
   const out = view(type, resource);
+  if (type === 'issuing_authorization') embedIssuingAuthorizationCard(out, root);
   // R17: fire the Stripe event/webhook for this state change (no-op if none registered).
   await emitStripeEvent(op, out, { occurredAt: occurredAt ?? '1970-01-01T00:00:00.000Z' });
   // events.full_types: persist the Stripe `event` envelope for this state change so it
@@ -596,6 +641,94 @@ function subscriptionItemPairs(sub: Record<string, unknown>): Array<{ price: str
   return out;
 }
 
+// The raw item entries a subscription/checkout-derived-subscription create sent,
+// normalized to an ordered array. parseStripeForm already turns the bracket form
+// items[0][price]=… into an array of objects (see lineItemEntries() above for the
+// identical `line_items` case); accept that, and a single-object shape defensively.
+function subscriptionItemEntries(value: unknown): Array<Record<string, unknown>> {
+  if (Array.isArray(value)) return value.filter((x) => x && typeof x === 'object') as Array<Record<string, unknown>>;
+  if (value && typeof value === 'object') return [value as Record<string, unknown>];
+  return [];
+}
+
+// Real Stripe billing cadences a Price's `recurring` can carry.
+type BillingInterval = 'day' | 'week' | 'month' | 'year';
+const BILLING_INTERVALS = new Set<BillingInterval>(['day', 'week', 'month', 'year']);
+
+// Resolve the (interval, interval_count) a new subscription bills on, from the FIRST
+// entry's price (Stripe requires every item on a subscription to share one
+// billing_cycle_anchor, so the first item's cadence drives current_period_end).
+// `entries` is whatever subscriptionItemEntries()/lineItemEntries() produced — each
+// entry's `price` may be a price id string or an already-resolved Price object
+// (the checkout-session line_items shape). Falls back to a defensive month/1 default
+// (`resolved: false`) when no entry resolves to a stored recurring price — e.g. an
+// inline price_data with no persisted Price, or (real Stripe would 400) no item at
+// all. This should not happen for a well-formed subscription create; it exists so
+// current_period_end is always populated rather than silently NaN/undefined.
+function resolveSubscriptionBillingInterval(entries: Array<Record<string, unknown>>, root?: string): { interval: BillingInterval; interval_count: number; resolved: boolean } {
+  for (const entry of entries) {
+    const p = entry.price;
+    const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).id ?? '') : '');
+    if (!priceId) continue;
+    const price = getOne('price', priceId, root);
+    const recurring = price?.recurring as Record<string, unknown> | undefined;
+    if (recurring && typeof recurring === 'object' && typeof recurring.interval === 'string' && BILLING_INTERVALS.has(recurring.interval as BillingInterval)) {
+      const count = Math.max(1, Math.trunc(Number(recurring.interval_count) || 1));
+      return { interval: recurring.interval as BillingInterval, interval_count: count, resolved: true };
+    }
+  }
+  return { interval: 'month', interval_count: 1, resolved: false };
+}
+
+// Add one billing period to a unix timestamp, real-Stripe-faithful: `month`/`year`
+// add CALENDAR months clamped to the target month's last day (Jan 31 + 1 month ->
+// Feb 28/29, not an overflow into March, matching how Stripe advances a billing_
+// cycle_anchor); `day`/`week` are exact multiples of 86400/604800 seconds.
+function addBillingInterval(atUnix: number, interval: BillingInterval, count: number): number {
+  const n = Math.max(1, Math.trunc(count) || 1);
+  if (interval === 'day') return atUnix + n * 24 * 3600;
+  if (interval === 'week') return atUnix + n * 7 * 24 * 3600;
+  const months = interval === 'year' ? n * 12 : n;
+  const d = new Date(atUnix * 1000);
+  const anchorDay = d.getUTCDate();
+  const first = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months, 1, d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds()));
+  const daysInTargetMonth = new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth() + 1, 0)).getUTCDate();
+  first.setUTCDate(Math.min(anchorDay, daysInTargetMonth));
+  return Math.floor(first.getTime() / 1000);
+}
+
+// Build the canonical items.data list Stripe returns on a subscription: a real
+// SubscriptionItem per entry, carrying the resolved Price object plus the
+// deprecated-but-still-served `plan` mirror (some integrations still read
+// item.plan.interval / .product / .id off a subscription item). `subId` is the
+// subscription's own (already-assigned, see the `id` pre-generation in the POST
+// handler) id, so each item's `subscription` back-reference round-trips. Fixes the
+// prior always-empty `items.data` on subscription create — real Stripe's create
+// response includes the actual items, mirroring what was requested.
+function buildSubscriptionItemsList(entries: Array<Record<string, unknown>>, subId: string, at: number, root?: string): Record<string, unknown> {
+  const data = entries.map((entry, i) => {
+    const p = entry.price;
+    const priceId = typeof p === 'string' ? p : (p && typeof p === 'object' ? String((p as Record<string, unknown>).id ?? '') : '');
+    const price = priceId ? getOne('price', priceId, root) : undefined;
+    const quantity = entry.quantity !== undefined ? Math.max(1, Math.trunc(Number(entry.quantity) || 1)) : 1;
+    const recurring = price?.recurring as Record<string, unknown> | undefined;
+    const plan = price ? {
+      id: price.id, object: 'plan', active: price.active ?? true, amount: price.unit_amount ?? null,
+      amount_decimal: price.unit_amount_decimal ?? null, billing_scheme: price.billing_scheme ?? 'per_unit',
+      currency: price.currency ?? 'usd', interval: recurring?.interval ?? null,
+      interval_count: recurring?.interval_count ?? 1, livemode: false,
+      metadata: price.metadata ?? {}, nickname: price.nickname ?? null,
+      product: price.product ?? null, tiers_mode: price.tiers_mode ?? null, usage_type: 'licensed',
+    } : null;
+    return {
+      id: `si_twin_${subId}_${i + 1}`, object: 'subscription_item',
+      price: price ?? (priceId || null), plan, quantity, subscription: subId,
+      created: at, metadata: {}, discounts: [], billing_thresholds: null, tax_rates: [],
+    };
+  });
+  return { object: 'list', data, has_more: false, total_count: data.length, url: `/v1/subscription_items?subscription=${subId}` };
+}
+
 // Rebuild a subscription's items.data sub-list from the live subscription_item rows
 // (so retrieving the subscription reflects items created/updated/deleted via the
 // /v1/subscription_items endpoint). Writes the canonical items list onto the sub.
@@ -814,6 +947,235 @@ async function create(type: string, params: Record<string, unknown>, defaults: R
   return { status: 200, body: await writeResource(type, id, fields, `${type}.create`, req.root, req.occurredAt, req.apiVersion) };
 }
 
+// ── ISSUING helpers: spending controls, real-time-auth shapes ─────────────────────────
+// Authorization.card is the FULL Card object in every vendor egress (API responses and
+// webhook payloads) — it is not expandable (stripe@22.3.0 Issuing.Authorization.card:
+// Stripe.Issuing.Card). The twin stores the id internally and embeds at the boundary;
+// cardholder stays an id string (expandable, unexpanded default). Caught live: the
+// issuing-bridge reads event.data.object.card.id and refused every twin presentment.
+function embedIssuingAuthorizationCard(body: Record<string, unknown>, root?: string): Record<string, unknown> {
+  if (typeof body.card === 'string') {
+    const cardRow = getOne('issuing_card', body.card, root);
+    if (cardRow !== undefined) body.card = cardRow;
+  }
+  return body;
+}
+
+// The closed interval set for spending_controls[spending_limits][][interval]
+// (stripe@22.3.0 Issuing/Cards.d.ts SpendingLimit.Interval — a documented closed enum).
+const SPENDING_LIMIT_INTERVALS = new Set(['all_time', 'daily', 'monthly', 'per_authorization', 'weekly', 'yearly']);
+
+// The stored SpendingControls shape (stripe@22.3.0 Card.SpendingControls): categories and
+// countries are nullable arrays, spending_limits an array of {amount, categories, interval}.
+function emptySpendingControls(): Record<string, unknown> {
+  return {
+    allowed_categories: null, allowed_merchant_countries: null,
+    blocked_categories: null, blocked_merchant_countries: null,
+    spending_limits: [], spending_limits_currency: null,
+  };
+}
+
+// Validate + normalize a caller-provided spending_controls dictionary (card create/update).
+// Vendor rules enforced: interval must be in the closed enum; a spending limit amount is a
+// positive integer; allowed_categories "Cannot be set with blocked_categories" (and the
+// merchant-country pair likewise) — both restrictions verbatim from the SDK's field docs.
+function normalizeSpendingControls(raw: unknown, currency: string | null): { controls?: Record<string, unknown>; error?: StripeResponse } {
+  if (raw === undefined) return {};
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { error: err('Invalid spending_controls: must be a dictionary.', 400, 'parameter_invalid_dictionary') };
+  }
+  const sc = raw as Record<string, unknown>;
+  const strArr = (v: unknown): string[] | undefined => (Array.isArray(v) ? v.map(String) : undefined);
+  const allowedCats = strArr(sc.allowed_categories);
+  const blockedCats = strArr(sc.blocked_categories);
+  if (allowedCats?.length && blockedCats?.length) {
+    return { error: err('spending_controls[allowed_categories] cannot be set with spending_controls[blocked_categories].', 400) };
+  }
+  const allowedCountries = strArr(sc.allowed_merchant_countries);
+  const blockedCountries = strArr(sc.blocked_merchant_countries);
+  if (allowedCountries?.length && blockedCountries?.length) {
+    return { error: err('spending_controls[allowed_merchant_countries] cannot be set with spending_controls[blocked_merchant_countries].', 400) };
+  }
+  const limits: Array<Record<string, unknown>> = [];
+  const rawLimits = Array.isArray(sc.spending_limits) ? sc.spending_limits : [];
+  for (let i = 0; i < rawLimits.length; i++) {
+    const l = rawLimits[i];
+    if (!l || typeof l !== 'object' || Array.isArray(l)) {
+      return { error: err(`Invalid spending_controls[spending_limits][${i}]: must be a dictionary.`, 400, 'parameter_invalid_dictionary') };
+    }
+    const { amount, interval, categories } = l as Record<string, unknown>;
+    if (typeof amount !== 'number' || !Number.isInteger(amount) || amount <= 0) {
+      return { error: err(`Invalid integer: spending_controls[spending_limits][${i}][amount] must be a positive integer.`, 400, 'parameter_invalid_integer') };
+    }
+    if (typeof interval !== 'string' || !SPENDING_LIMIT_INTERVALS.has(interval)) {
+      return { error: err(`Invalid spending_controls[spending_limits][${i}][interval]: must be one of 'all_time', 'daily', 'monthly', 'per_authorization', 'weekly', or 'yearly'.`, 400, 'parameter_invalid_string_enum') };
+    }
+    const cats = strArr(categories);
+    limits.push({ amount, categories: cats?.length ? cats : null, interval });
+  }
+  const arrOrNull = (v: string[] | undefined) => (v === undefined ? undefined : v.length ? v : null);
+  const controls: Record<string, unknown> = {
+    ...emptySpendingControls(),
+    spending_limits: limits,
+    ...(limits.length ? { spending_limits_currency: typeof sc.spending_limits_currency === 'string' ? sc.spending_limits_currency : currency } : {}),
+  };
+  for (const [key, v] of [
+    ['allowed_categories', arrOrNull(allowedCats)], ['blocked_categories', arrOrNull(blockedCats)],
+    ['allowed_merchant_countries', arrOrNull(allowedCountries)], ['blocked_merchant_countries', arrOrNull(blockedCountries)],
+  ] as Array<[string, unknown]>) {
+    if (v !== undefined) controls[key] = v;
+  }
+  return { controls };
+}
+
+// Start of the current spending-limit window, seconds since epoch (UTC calendar windows;
+// weekly starts Monday 00:00 UTC — the week-start day is not vendor-documented).
+function issuingWindowStartSec(interval: string, nowSec: number): number {
+  if (interval === 'all_time') return 0;
+  const d = new Date(nowSec * 1000);
+  if (interval === 'daily') return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()) / 1000;
+  if (interval === 'weekly') {
+    const monOffset = (d.getUTCDay() + 6) % 7; // Monday = 0
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() - monOffset) / 1000;
+  }
+  if (interval === 'monthly') return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1) / 1000;
+  if (interval === 'yearly') return Date.UTC(d.getUTCFullYear(), 0, 1) / 1000;
+  return 0;
+}
+
+type PriorAuthorization = { amount: number; created: number; category: string };
+
+// Evaluate one spending_controls dictionary against a presented authorization. Returns a
+// human-readable reason_message when a control declines the authorization, else null.
+// (The request_history.reason for any violation is 'spending_controls' — the vendor enum's
+// single value for controls declines.)
+function spendingControlsViolation(
+  controls: unknown,
+  opts: { amount: number; category: string; country: string | null; nowSec: number; priorApproved: PriorAuthorization[] },
+): string | null {
+  if (!controls || typeof controls !== 'object') return null;
+  const sc = controls as Record<string, unknown>;
+  const list = (v: unknown): string[] | null => (Array.isArray(v) && v.length ? v.map(String) : null);
+  const allowedCats = list(sc.allowed_categories);
+  if (allowedCats && !allowedCats.includes(opts.category)) return `merchant category ${opts.category} is not in allowed_categories`;
+  const blockedCats = list(sc.blocked_categories);
+  if (blockedCats?.includes(opts.category)) return `merchant category ${opts.category} is in blocked_categories`;
+  const allowedCountries = list(sc.allowed_merchant_countries);
+  if (allowedCountries && (!opts.country || !allowedCountries.includes(opts.country))) return `merchant country ${opts.country ?? '(none)'} is not in allowed_merchant_countries`;
+  const blockedCountries = list(sc.blocked_merchant_countries);
+  if (blockedCountries && opts.country && blockedCountries.includes(opts.country)) return `merchant country ${opts.country} is in blocked_merchant_countries`;
+  for (const rawLimit of Array.isArray(sc.spending_limits) ? sc.spending_limits : []) {
+    if (!rawLimit || typeof rawLimit !== 'object') continue;
+    const l = rawLimit as Record<string, unknown>;
+    const limit = Number(l.amount) || 0;
+    if (limit <= 0) continue;
+    const limCats = list(l.categories);
+    if (limCats && !limCats.includes(opts.category)) continue;
+    const interval = String(l.interval ?? '');
+    if (interval === 'per_authorization') {
+      if (opts.amount > limit) return `amount exceeds the per_authorization spending limit of ${limit}`;
+      continue;
+    }
+    const start = issuingWindowStartSec(interval, opts.nowSec);
+    const spent = opts.priorApproved
+      .filter((a) => a.created >= start && (!limCats || limCats.includes(a.category)))
+      .reduce((s, a) => s + a.amount, 0);
+    if (spent + opts.amount > limit) return `amount exceeds the ${interval} spending limit of ${limit}`;
+  }
+  return null;
+}
+
+// Approved authorizations previously presented on this card/cardholder — the base for
+// interval spending-limit windows (spending limits are calculated over approved
+// authorization amounts).
+function priorApprovedAuthorizations(root: string | undefined, key: 'card' | 'cardholder', value: string): PriorAuthorization[] {
+  return rows('issuing_authorization', root)
+    .filter((a) => a[key] === value && a.approved === true)
+    .map((a) => ({
+      amount: Number(a.amount) || 0,
+      created: Number(a.created) || 0,
+      category: String((a.merchant_data as Record<string, unknown> | undefined)?.category ?? ''),
+    }));
+}
+
+// The default merchant_data the twin presents (test-helper defaults), merged under any
+// caller-provided merchant_data keys (stripe@22.3.0 MerchantData: category, city, country,
+// name, network_id, postal_code, state, tax_id, terminal_id, url).
+function issuingMerchantData(param: unknown): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    category: 'general', category_code: '5399', city: 'San Francisco', country: 'US',
+    name: 'Twin Test Merchant', network_id: '1234567890', postal_code: '94103', state: 'CA',
+    tax_id: null, terminal_id: null, url: null,
+  };
+  if (param && typeof param === 'object' && !Array.isArray(param)) {
+    for (const [k, v] of Object.entries(param as Record<string, unknown>)) base[k] = v;
+  }
+  return base;
+}
+
+// The canonical verification_data shape (stripe@22.3.0 Authorization.VerificationData);
+// check enums are the vendor's ('match' | 'mismatch' | 'not_provided').
+function issuingVerificationData(): Record<string, unknown> {
+  return {
+    address_line1_check: 'not_provided', address_postal_code_check: 'not_provided',
+    authentication_exemption: null, cvc_check: 'match', expiry_check: 'match',
+    postal_code: null, three_d_secure: null,
+  };
+}
+
+// One request_history entry (stripe@22.3.0 Authorization.RequestHistory). The
+// authorization_code "typically starts with the letter 'S', followed by a six-digit
+// number" and is "not guaranteed to be unique across authorizations" (SDK field doc) —
+// the twin derives it deterministically from the request time.
+function requestHistoryEntry(opts: {
+  amount: number; currency: string; approved: boolean; reason: string; reasonMessage: string | null;
+  createdSec: number; merchantAmount: number; merchantCurrency: string;
+}): Record<string, unknown> {
+  return {
+    amount: opts.amount, amount_details: null, approved: opts.approved,
+    authorization_code: opts.approved ? `S${String(100000 + (opts.createdSec % 900000))}` : null,
+    created: opts.createdSec, currency: opts.currency,
+    merchant_amount: opts.merchantAmount, merchant_currency: opts.merchantCurrency,
+    network_risk_score: null, reason: opts.reason, reason_message: opts.reasonMessage,
+    requested_at: opts.createdSec,
+  };
+}
+
+// Materialize a capture against an approved authorization: an Issuing Transaction of
+// type 'capture' (negative amount — captures debit) linked to a balance_transaction of
+// type 'issuing_transaction' with balance_type 'issuing' (both literals from
+// stripe@22.3.0 BalanceTransaction.Type / .BalanceType), so the issuing balance the twin
+// serves (fund_balance / GET /v1/balance issuing section) genuinely goes down on capture.
+async function materializeIssuingCapture(
+  authId: string,
+  auth: Record<string, unknown>,
+  amountCents: number,
+  req: StripeRequest,
+): Promise<{ txnId: string; btId: string }> {
+  const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+  const bt = await create('balance_transaction', {}, {
+    amount: -amountCents, currency, fee: 0, net: -amountCents, type: 'issuing_transaction',
+    status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
+    available_on: nowUnix(req.occurredAt), fee_details: [],
+  }, req);
+  const btId = (bt.body as { id: string }).id;
+  const txn = await create('issuing_transaction', {
+    authorization: authId, card: auth.card, cardholder: auth.cardholder,
+  }, {
+    type: 'capture', amount: -amountCents, currency,
+    merchant_amount: -amountCents, merchant_currency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+    merchant_data: auth.merchant_data ?? issuingMerchantData(undefined),
+    livemode: false, metadata: {}, dispute: null, wallet: null, network_data: null,
+    amount_details: null, purchase_details: null, balance_transaction: btId,
+  }, req);
+  return { txnId: (txn.body as { id: string }).id, btId };
+}
+
+// Does a webhook endpoint's enabled_events subscribe it to `type`? The matcher lives with
+// the delivery registry (stripe-events.ts) so this synchronous issuing leg and the organic
+// asynchronous fan-out share one set of Stripe subscription semantics.
+const endpointSubscribedTo = stripeEventMatches;
+
 // Stripe's dispute.evidence is a flat bag of (mostly null) string fields; the twin
 // emits the canonical empty shape so the object is shaped right without fabricating
 // content. Callers can overwrite individual fields via POST /v1/disputes/:id.
@@ -937,7 +1299,11 @@ function paymentMethodSubObject(pmType: string, params: Record<string, unknown>)
   switch (pmType) {
     case 'card': {
       const c = sub('card');
-      const number = typeof c.number === 'string' ? c.number.replace(/\D/g, '') : '';
+      // parseStripeForm coerces an all-digit card[number] to a JS number (same as any
+      // other numeric-looking form field) — accept both shapes so a raw test PAN still
+      // produces its real last4 instead of silently falling back to the '4242' default.
+      const number = typeof c.number === 'string' ? c.number.replace(/\D/g, '')
+        : typeof c.number === 'number' ? String(c.number).replace(/\D/g, '') : '';
       return { card: {
         brand: 'visa', last4: number ? number.slice(-4) : '4242',
         exp_month: Number(c.exp_month) || 12, exp_year: Number(c.exp_year) || 2034,
@@ -987,9 +1353,18 @@ function paymentMethodSubObject(pmType: string, params: Record<string, unknown>)
 function balanceSummary(root?: string): Record<string, unknown> {
   const available = new Map<string, number>();
   const pending = new Map<string, number>();
+  const issuing = new Map<string, number>();
   for (const t of rows('balance_transaction', root)) {
     const cur = String(t.currency ?? 'usd');
     const net = Number(t.net ?? 0);
+    // Issuing funds are their own balance: real Stripe reports them under the Balance
+    // object's `issuing` section (stripe@22.3.0 Balance.issuing), not in the payments
+    // `available` bucket. balance_type 'issuing' rows (fund_balance topups, capture
+    // debits) accrue there.
+    if (t.balance_type === 'issuing') {
+      issuing.set(cur, (issuing.get(cur) ?? 0) + net);
+      continue;
+    }
     const bucket = t.status === 'available' ? available : pending;
     bucket.set(cur, (bucket.get(cur) ?? 0) + net);
   }
@@ -997,7 +1372,10 @@ function balanceSummary(root?: string): Record<string, unknown> {
     const out = [...m.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } }));
     return out.length ? out : [{ amount: 0, currency: 'usd', source_types: { card: 0 } }];
   };
-  return { object: 'balance', available: toArr(available), pending: toArr(pending), livemode: false };
+  return {
+    object: 'balance', available: toArr(available), pending: toArr(pending), livemode: false,
+    ...(issuing.size ? { issuing: { available: [...issuing.entries()].map(([currency, amount]) => ({ amount, currency, source_types: { card: amount } })) } } : {}),
+  };
 }
 
 // ---- CONNECT: connected accounts (vendor-faithful) ----
@@ -1264,6 +1642,106 @@ function buildCreditNote(
   return { id, body };
 }
 
+// When a PaymentIntent linked to an Invoice succeeds — the 'create subscription now,
+// collect payment client-side' pattern modeled by POST /v1/subscriptions with
+// payment_behavior: 'default_incomplete' (see that handler) — real Stripe marks that
+// Invoice `paid` and, when it's a subscription's first invoice, flips the Subscription
+// from `incomplete` to `active`. This is the state a caller polling/re-fetching the
+// subscription after confirming payment client-side expects to observe (there is no
+// webhook consumer in the twin, so we apply the cascade synchronously here instead of
+// waiting on a delivered event). No-op when the PI isn't linked to a twin-tracked
+// invoice, or that invoice is already paid (idempotent against a duplicate confirm).
+async function cascadeInvoicePaidFromSucceededPaymentIntent(piBody: Record<string, unknown>, req: StripeRequest): Promise<void> {
+  const invoiceId = typeof piBody.invoice === 'string' ? piBody.invoice : undefined;
+  if (!invoiceId) return;
+  const invoice = getOne('invoice', invoiceId, req.root);
+  if (!invoice || invoice.status === 'paid') return;
+  const amount = Number(invoice.total ?? invoice.amount_due) || 0;
+  const at = nowUnix(req.occurredAt);
+  // op 'invoice.pay' maps to the real invoice.paid event (see eventTypeFor), matching
+  // the standalone POST /v1/invoices/:id/pay action's own event.
+  await writeResource('invoice', invoiceId, {
+    status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
+    status_transitions: { ...(invoice.status_transitions as object ?? {}), paid_at: at },
+  }, 'invoice.pay', req.root, req.occurredAt);
+  const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+  if (subId) {
+    const sub = getOne('subscription', subId, req.root);
+    if (sub && sub.status === 'incomplete') {
+      await writeResource('subscription', subId, { status: 'active' }, 'subscription.update', req.root, req.occurredAt);
+    }
+  }
+}
+
+// Recompute subtotal/total from an invoice's line-item list. Shared by every mutation of
+// `lines.data` (add_lines/update_lines/remove_lines and invoiceitems.create attaching
+// directly to a draft invoice — PEAK-3102 round 2) so the two line-item entry points can
+// never again disagree about how a total is derived from its lines.
+function sumInvoiceLines(lines: Array<Record<string, unknown>>): number {
+  return lines.reduce((s, l) => s + (Number(l.amount) || 0), 0);
+}
+
+// Append one line to a DRAFT invoice's `lines.data` and re-derive amount_due/subtotal/total
+// from the resulting list, exactly like add_lines does (PEAK-3102 round 2: POST
+// /v1/invoiceitems with `invoice: <id>` — the call shape PeakHealth's
+// createOrderInvoicePaymentIntent/createAdHocInvoicePaymentIntent both use — previously
+// created the invoiceitem resource but never touched the invoice, so amount_due stayed 0
+// and finalize's `willNeedPaymentIntent` check never fired. Real Stripe attaches an invoice
+// item to its invoice's line list immediately, not just at finalize.
+async function attachLineToDraftInvoice(invoiceId: string, inv: Record<string, unknown>, line: Record<string, unknown>, req: StripeRequest): Promise<void> {
+  const cur = ((inv.lines as { data?: Array<Record<string, unknown>> } | undefined)?.data) ?? [];
+  const next = [...cur, line];
+  const subtotal = sumInvoiceLines(next);
+  const lines = { object: 'list', data: next, has_more: false, total_count: next.length, url: `/v1/invoices/${invoiceId}/lines` };
+  await writeResource('invoice', invoiceId, { lines, subtotal, total: subtotal, amount_due: subtotal, amount_remaining: subtotal }, 'invoice.update', req.root, req.occurredAt);
+}
+
+// Mint the PaymentIntent a charge_automatically invoice with a balance due gets the moment
+// it's finalized (see the finalize/send branch above — PEAK-3102: this is the object
+// PeakHealth's createStandaloneOrder reads via expand[]=payment_intent and previously never
+// got). Mirrors the subscription default_incomplete first-invoice PaymentIntent (same
+// defaults) with one addition real Stripe does here: a `requires_confirmation` status
+// instead of `requires_payment_method` when the invoice already carries a
+// default_payment_method (nothing left to collect from the customer — Stripe.js confirms
+// it directly). `invoice` on create() honors a caller-provided id via `params.id`, so the id
+// is pre-minted by the caller and threaded into the invoice's own write in the SAME
+// transaction (avoids a second invoice update + a second invoice.updated event).
+async function createInvoicePaymentIntent(piId: string, inv: Record<string, unknown>, invoiceId: string, req: StripeRequest): Promise<void> {
+  const amount = Number(inv.amount_due) || 0;
+  const currency = String(inv.currency ?? 'usd');
+  const defaultPaymentMethod = typeof inv.default_payment_method === 'string' ? inv.default_payment_method : undefined;
+  await create('payment_intent', {
+    id: piId, amount, currency, customer: inv.customer, invoice: invoiceId,
+    ...(defaultPaymentMethod ? { payment_method: defaultPaymentMethod } : {}),
+  }, {
+    status: defaultPaymentMethod ? 'requires_confirmation' : 'requires_payment_method',
+    client_secret: mintClientSecret(piId), livemode: false,
+    capture_method: 'automatic', amount_capturable: 0, amount_received: 0, next_action: null,
+    automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
+  }, req);
+}
+
+// Settle the invoice's PaymentIntent on a successful (non-declined, non-out-of-band)
+// POST /v1/invoices/:id/pay: real Stripe moves it to `succeeded` and attaches a `latest_charge`
+// — a Charge that itself carries `invoice` (the back-reference PeakHealth's BioReference /
+// BloodworkTab flow follows after paying). No-op if the invoice never got a PaymentIntent
+// (send_invoice / $0 invoices — see createInvoicePaymentIntent) or it's already succeeded
+// (idempotent against a duplicate pay). A DECLINED pay never reaches here — the caller
+// returns 402 before writing the invoice, so the PI is left exactly as finalize left it.
+async function settleInvoicePaymentIntentOnPay(piId: string, invoiceId: string, amount: number, req: StripeRequest): Promise<void> {
+  const pi = getOne('payment_intent', piId, req.root);
+  if (!pi || pi.status === 'succeeded') return;
+  const chargeId = nextId('charge', req.root);
+  await create('charge', { id: chargeId, amount, currency: pi.currency, customer: pi.customer, payment_intent: piId, invoice: invoiceId }, {
+    status: 'succeeded', paid: true, captured: true, refunded: false, disputed: false,
+    amount_captured: amount, amount_refunded: 0, metadata: {},
+    billing_details: { address: null, email: null, name: null, phone: null }, livemode: false,
+  }, req);
+  await writeResource('payment_intent', piId, {
+    status: 'succeeded', amount_received: amount, amount_capturable: 0, next_action: null, latest_charge: chargeId,
+  }, 'payment_intent.succeeded', req.root, req.occurredAt);
+}
+
 /**
  * Public entry: honors the Idempotency-Key (replay → stored response, no re-write)
  * then delegates to the router. Only POSTs are idempotent (matches Stripe; GET/DELETE
@@ -1324,7 +1802,7 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     const amt = Number(params.amount) || 0;
     // Card-decline fidelity: a known test card that declines → HTTP 402 card_error and
     // NO charge created (matches Stripe — a declined charge is not persisted as paid).
-    const decline = declineFor(params);
+    const decline = declineFor(req.root, params);
     if (decline) return cardError(decline);
     // capture=false creates an UNCAPTURED authorization (Stripe holds the funds): the charge
     // is succeeded+paid but captured:false, amount_captured 0, and carries the capture deadline.
@@ -1556,7 +2034,13 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
   }
 
   // ---- setup_intents ----
-  if (path === '/v1/setup_intents' && method === 'POST') return create('setup_intent', params, { status: 'requires_confirmation', usage: 'off_session', client_secret: 'seti_twin_secret', payment_method_types: ['card'], next_action: null, latest_attempt: null, last_setup_error: null, livemode: false }, req);
+  if (path === '/v1/setup_intents' && method === 'POST') {
+    // Pre-mint the id so client_secret can embed it (see mintClientSecret) — real
+    // Stripe.js needs this to confirm the SI client-side.
+    const siId = typeof params.id === 'string' && params.id ? params.id : nextId('setup_intent', req.root);
+    const { id: _siId, ...rest } = params as Record<string, unknown>;
+    return create('setup_intent', { ...rest, id: siId }, { status: 'requires_confirmation', usage: 'off_session', client_secret: mintClientSecret(siId), payment_method_types: ['card'], next_action: null, latest_attempt: null, last_setup_error: null, livemode: false }, req);
+  }
   if (seg[1] === 'setup_intents' && seg.length === 4 && seg[3] === 'confirm' && method === 'POST') {
     const si = getOne('setup_intent', idAt(2), req.root);
     if (!si) return err(`No such setup_intent: '${idAt(2)}'`, 404, 'resource_missing');
@@ -1661,15 +2145,30 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     // number; the modeled sub-object is the truth.
     const { card: _rawCard, sepa_debit: _sepa, us_bank_account: _ach, type: _t, ...rest } = params as Record<string, unknown>;
     const sub = paymentMethodSubObject(pmType, params);
-    return create('payment_method', { ...rest, type: pmType, customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...sub }, {}, req);
+    // Capture the decline outcome implied by the creating PAN/token now (null = succeeds),
+    // so a LATER charge that references this PM only by id — the normal shape for a saved
+    // card / off-session retry charge — can still reproduce the same decline. See declineFor.
+    const declineOutcome = pmType === 'card' ? (declineFor(undefined, params) ?? null) : null;
+    return create('payment_method', { ...rest, type: pmType, customer: null, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...sub, _declineOutcome: declineOutcome }, {}, req);
   }
   // Attach a PaymentMethod to a customer. Both must exist; on success the PM's `customer`
   // is set. Unknown PM → 404; missing/unknown customer → 400 (resource_missing), like Stripe.
   if (seg[1] === 'payment_methods' && seg.length === 4 && seg[3] === 'attach' && method === 'POST') {
-    if (!getOne('payment_method', idAt(2), req.root)) return err(`No such payment_method: '${idAt(2)}'`, 404, 'resource_missing');
     const customer = typeof params.customer === 'string' ? params.customer : '';
     if (!customer) return err('Missing required param: customer.', 400, 'parameter_missing');
     if (!getOne('customer', customer, req.root)) return err(`No such customer: '${customer}'`, 400, 'resource_missing');
+    // Stripe test mode: attaching a well-known test token (pm_card_visa, …) yields a NEW
+    // PaymentMethod on the customer carrying that card's outcome. The token itself is a
+    // template, never a stored object. ⚠ doc-unverified that the returned id is fresh; the
+    // attachability of the tokens is documented. Live-verified 2026-09-04 that the twin
+    // refused them, the gap the managed substrate tier hit.
+    if (!getOne('payment_method', idAt(2), req.root) && idAt(2).startsWith('pm_card_') && idAt(2) in TEST_TOKEN_DECLINES) {
+      const pan = idAt(2) === 'pm_card_mastercard' ? '5555555555554444' : '4242424242424242';
+      const sub = paymentMethodSubObject('card', { card: { number: pan } });
+      if (idAt(2) === 'pm_card_mastercard') (sub.card as Record<string, unknown>).brand = 'mastercard';
+      return create('payment_method', { type: 'card', customer, livemode: false, billing_details: { address: null, email: null, name: null, phone: null }, ...sub, _declineOutcome: TEST_TOKEN_DECLINES[idAt(2)] ?? null }, {}, req);
+    }
+    if (!getOne('payment_method', idAt(2), req.root)) return err(`No such payment_method: '${idAt(2)}'`, 404, 'resource_missing');
     return { status: 200, body: await writeResource('payment_method', idAt(2), { customer }, 'payment_method.attach', req.root, req.occurredAt) };
   }
   if (path === '/v1/payment_methods' && method === 'GET') {
@@ -1702,11 +2201,14 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     // when APM is on and no explicit types are given, Stripe still reports a payment_method_types
     // list (at minimum card). Honor an explicit payment_method_types[] otherwise.
     const pmTypes = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String) : (apmEnabled ? ['card'] : ['card']);
-    const { automatic_payment_methods: _apm, payment_method_types: _pmt, ...rest } = params as Record<string, unknown>;
+    const { automatic_payment_methods: _apm, payment_method_types: _pmt, id: _piId, ...rest } = params as Record<string, unknown>;
+    // Pre-mint the id so client_secret can embed it (see mintClientSecret) — real
+    // Stripe.js needs this to confirm the PI client-side.
+    const piId = typeof params.id === 'string' && params.id ? params.id : nextId('payment_intent', req.root);
     // capture_method defaults to 'automatic'; amount_capturable/amount_received start at 0 and
     // are driven by the confirm→capture state machine (manual capture lands in requires_capture).
-    return create('payment_intent', rest, {
-      status: 'requires_confirmation', client_secret: 'pi_twin_secret', livemode: false,
+    return create('payment_intent', { ...rest, id: piId }, {
+      status: 'requires_confirmation', client_secret: mintClientSecret(piId), livemode: false,
       capture_method: 'automatic', amount_capturable: 0, amount_received: 0, next_action: null,
       automatic_payment_methods, payment_method_types: pmTypes,
       payment_method_options: (params.payment_method_options as object) ?? {},
@@ -1727,7 +2229,7 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     // Card-decline fidelity: resolve the card from the confirm body OR the payment_method
     // attached at create. A known declining test card → status requires_payment_method
     // (NOT succeeded), last_payment_error populated, and a 402 card_error carrying the PI id.
-    const decline = declineFor(params, existing);
+    const decline = declineFor(req.root, params, existing);
     if (decline) {
       const lastError = {
         type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}),
@@ -1766,7 +2268,9 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       return { status: 200, body };
     }
     const succeededAmount = Number(existing.amount ?? params.amount ?? 0);
-    return { status: 200, body: await writeResource('payment_intent', idAt(2), { ...params, status: 'succeeded', amount_received: succeededAmount, next_action: null }, 'payment_intent.confirm', req.root, req.occurredAt, req.apiVersion) };
+    const confirmedBody = await writeResource('payment_intent', idAt(2), { ...params, status: 'succeeded', amount_received: succeededAmount, next_action: null }, 'payment_intent.confirm', req.root, req.occurredAt, req.apiVersion);
+    await cascadeInvoicePaidFromSucceededPaymentIntent(confirmedBody, req);
+    return { status: 200, body: confirmedBody };
   }
   // Manual capture: an authorized (requires_capture) PI is captured → succeeded, amount_received
   // set, amount_capturable cleared. Capturing a PI in any other state is payment_intent_unexpected_state
@@ -1782,6 +2286,7 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     const toCapture = params.amount_to_capture !== undefined ? Math.max(0, Math.trunc(Number(params.amount_to_capture) || 0)) : authAmount;
     const captured = Math.min(toCapture, authAmount);
     const body = await writeResource('payment_intent', idAt(2), { status: 'succeeded', amount_received: captured, amount_capturable: 0 }, 'payment_intent.succeeded', req.root, req.occurredAt);
+    await cascadeInvoicePaidFromSucceededPaymentIntent(body, req);
     return { status: 200, body };
   }
   // POST /v1/payment_intents/:id/increment_authorization — raise the authorized amount on a
@@ -1994,14 +2499,58 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
   if (path === '/v1/invoiceitems' && method === 'POST') {
     const at = nowUnix(req.occurredAt);
     const qty = Number(params.quantity) || 1;
-    // invoiceitem uses `date` (not `created`); customer is request-supplied (declared scope when absent).
-    return create('invoiceitem', params, { livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty), period: { start: at, end: at } }, req, { timeField: 'date' });
+    // A price-based item (PeakHealth's catalog-product order path) carries no `amount` of
+    // its own — real Stripe derives it from price.unit_amount * quantity. An ad-hoc item
+    // (frozen-quote lab orders) already supplies `amount` directly; leave it untouched.
+    const priceRef = typeof params.price === 'string' ? params.price : '';
+    let resolvedAmount: number | undefined;
+    let resolvedCurrency: string | undefined;
+    if (priceRef) {
+      const price = getOne('price', priceRef, req.root);
+      if (!price) return err(`No such price: '${priceRef}'`, 400, 'resource_missing');
+      resolvedAmount = (Number(price.unit_amount) || 0) * qty;
+      resolvedCurrency = typeof price.currency === 'string' ? price.currency : undefined;
+    }
+    // Invoice items request-supplied `invoice: <id>` attach directly to that DRAFT invoice
+    // (PeakHealth's order/lab-booking flows always attach this way, never via the pending-
+    // items sweep). Real Stripe only accepts new items on a draft invoice and updates its
+    // line list + totals immediately — not just at finalize.
+    const invoiceRef = typeof params.invoice === 'string' ? params.invoice : '';
+    let targetInvoice: Record<string, unknown> | undefined;
+    if (invoiceRef) {
+      targetInvoice = getOne('invoice', invoiceRef, req.root);
+      if (!targetInvoice) return err(`No such invoice: '${invoiceRef}'`, 404, 'resource_missing');
+      if (targetInvoice.status !== 'draft') {
+        return err(`This invoice cannot have invoice items added because it has status ${String(targetInvoice.status)}.`, 400, 'invoice_not_editable');
+      }
+      if (resolvedCurrency === undefined && typeof targetInvoice.currency === 'string') resolvedCurrency = targetInvoice.currency;
+    }
+    // invoiceitem uses `date` (not `created`); customer is request-supplied (declared scope
+    // when absent). `currency` is Stripe-required on every invoiceitem; a price-based item
+    // (no explicit currency param) inherits the price's currency, falling back to the target
+    // invoice's, then 'usd' — real Stripe requires the item's currency to match its invoice.
+    const created = await create('invoiceitem', params, {
+      livemode: false, discountable: true, proration: false, quantity: qty, quantity_decimal: String(qty),
+      period: { start: at, end: at }, currency: resolvedCurrency ?? 'usd',
+      ...(resolvedAmount !== undefined ? { amount: resolvedAmount } : {}),
+    }, req, { timeField: 'date' });
+    if (targetInvoice) {
+      const item = created.body as Record<string, unknown>;
+      const amount = Number(item.amount) || 0;
+      const currency = String(targetInvoice.currency ?? item.currency ?? 'usd');
+      await attachLineToDraftInvoice(invoiceRef, targetInvoice, {
+        id: `il_${item.id as string}`, object: 'line_item', type: 'invoiceitem', amount, currency,
+        quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
+        period: item.period ?? { start: at, end: at }, description: (item.description as string) ?? null,
+      }, req);
+    }
+    return created;
   }
   if (path === '/v1/invoices' && method === 'POST') {
     const at = nowUnix(req.occurredAt);
     // A minimal draft invoice. Aggregate money fields default to 0; nested objects are
     // emitted with Stripe's canonical empty shapes; `customer` is request-supplied.
-    return create('invoice', params, {
+    const createdInvoice = await create('invoice', params, {
       status: 'draft', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
       auto_advance: false, attempt_count: 0, attempted: false,
       amount_due: 0, amount_paid: 0, amount_remaining: 0, amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
@@ -2012,7 +2561,37 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       status_transitions: { finalized_at: null, marked_uncollectible_at: null, paid_at: null, voided_at: null },
       issuer: { type: 'self' },
       payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
+      // A draft invoice has no PaymentIntent yet — real Stripe mints one only on finalize
+      // (draft -> open), never at creation. See the finalize/send handling below.
+      payment_intent: null,
     }, req);
+    // Stripe (documented, pending_invoice_items_behavior defaults to `include`): a new
+    // invoice for a customer pulls in every pending invoice item — one created without an
+    // `invoice` and not yet on any — as its lines. Live-verified 2026-09-04: three pending
+    // items and then invoices.create left the real invoice with three lines; the twin had
+    // left them unattached and the invoice at 0. `exclude` leaves them pending.
+    if (createdInvoice.status === 200 && params.pending_invoice_items_behavior !== 'exclude') {
+      const inv = createdInvoice.body as Record<string, unknown>;
+      const invoiceId = String(inv.id);
+      const customerId = typeof inv.customer === 'string' ? inv.customer : '';
+      const pending = customerId
+        ? listViews('invoiceitem', req.root, 'date').filter((it) => it.customer === customerId && !it.invoice).reverse()
+        : [];
+      for (const item of pending) {
+        const current = getOne('invoice', invoiceId, req.root) ?? inv;
+        const amount = Number(item.amount) || 0;
+        const qty = Number(item.quantity) || 1;
+        await attachLineToDraftInvoice(invoiceId, current, {
+          id: `il_${String(item.id)}`, object: 'line_item', type: 'invoiceitem', amount, currency: String(current.currency ?? item.currency ?? 'usd'),
+          quantity: qty, proration: false, invoice_item: item.id, price: item.price ?? null,
+          period: item.period ?? { start: at, end: at }, description: (item.description as string) ?? null,
+          discountable: item.discountable ?? true, discounts: [], livemode: false, metadata: item.metadata ?? {}, tax_amounts: [], tax_rates: [],
+        }, req);
+        await writeResource('invoiceitem', String(item.id), { invoice: invoiceId }, 'invoiceitem.update', req.root, req.occurredAt);
+      }
+      if (pending.length > 0) return { status: 200, body: getOne('invoice', invoiceId, req.root) ?? inv };
+    }
+    return createdInvoice;
   }
   if (seg[1] === 'invoices' && seg.length === 4 && method === 'POST' && ['finalize', 'pay', 'void', 'mark_uncollectible', 'send'].includes(seg[3]!)) {
     const inv = getOne('invoice', idAt(2), req.root);
@@ -2028,23 +2607,70 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (action === 'pay' && (status === 'void' || status === 'draft')) return err(`This invoice cannot be paid because it has status ${status}.`, 400, 'invoice_not_editable');
     if (action === 'mark_uncollectible' && status !== 'open') return err(`Only open invoices can be marked uncollectible (this one is ${status}).`, 400, 'invoice_not_editable');
     if (action === 'void' && (status === 'paid' || status === 'void')) return err(`This invoice cannot be voided because it has status ${status}.`, 400, 'invoice_not_editable');
+    // Card-decline fidelity: paying an invoice with a known declining test card (passed
+    // explicitly via payment_method, e.g. an off-session retry charge, or falling back to
+    // the invoice's own default_payment_method) must 402 like every other charge/confirm
+    // path — Stripe does NOT mark the invoice paid on a declined attempt. Without this the
+    // twin previously always paid invoices regardless of which card was attached.
+    if (action === 'pay') {
+      // Stripe (documented): paying an invoice charges a payment method — the one passed,
+      // the invoice's default, or the customer's default payment method or source — unless
+      // the payment is recorded out of band. With none of those the attempt fails; the twin
+      // previously paid regardless (live-verified 2026-09-04 against the twin, the gap the
+      // managed substrate tier hit). ⚠ exact message and code doc-unverified.
+      const paidOutOfBandNow = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
+      const payer = getOne('customer', String(inv.customer ?? ''), req.root);
+      const customerDefault = ((payer?.invoice_settings as Record<string, unknown> | undefined)?.default_payment_method) || payer?.default_source;
+      if (!paidOutOfBandNow && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault) {
+        return err('This customer has no attached payment source or default payment method. Please consider adding a default payment method.', 400, 'missing');
+      }
+      const decline = declineFor(req.root, params, { payment_method: inv.default_payment_method });
+      if (decline) return cardError(decline, { payment_intent: typeof inv.payment_intent === 'string' ? inv.payment_intent : undefined });
+    }
     // status transition per action. `send` finalizes a draft (and records the send timestamp);
     // mark_uncollectible marks an open invoice as a write-off; pay supports out-of-band payment.
     const at = nowUnix(req.occurredAt);
     let fields: Record<string, unknown>;
-    if (action === 'finalize') fields = { status: 'open', status_transitions: { ...(inv.status_transitions as object ?? {}), finalized_at: at } };
-    else if (action === 'send') {
+    let paidOutOfBand = false;
+    // Real Stripe mints a PaymentIntent the moment a draft invoice is finalized (draft ->
+    // open) — NOT at creation (PEAK-3102: PeakHealth's createStandaloneOrder reads
+    // invoice.payment_intent right after finalize and gets nothing today). Only a
+    // charge_automatically invoice with a positive balance gets one: send_invoice
+    // (customer pays via the hosted page / bank transfer, no PI) and $0 / fully-discounted
+    // invoices never get one, exactly like the analogous subscription default_incomplete
+    // first-invoice path above. `send` shares this because it auto-finalizes a draft too.
+    const becomesOpenFromDraft = (action === 'finalize' || action === 'send') && inv.status === 'draft';
+    const willNeedPaymentIntent = becomesOpenFromDraft
+      && ((inv.collection_method as string) ?? 'charge_automatically') === 'charge_automatically'
+      && (Number(inv.amount_due) || 0) > 0;
+    const newPaymentIntentId = willNeedPaymentIntent ? nextId('payment_intent', req.root) : null;
+    if (action === 'finalize') {
+      fields = { status: 'open', status_transitions: { ...(inv.status_transitions as object ?? {}), finalized_at: at }, payment_intent: newPaymentIntentId };
+    } else if (action === 'send') {
       // sending a draft auto-finalizes it (Stripe behavior); an already-open invoice stays open.
       const becameOpen = inv.status === 'draft';
-      fields = { status: becameOpen ? 'open' : (inv.status as string), _sent: true, _sent_at: at, status_transitions: { ...(inv.status_transitions as object ?? {}), ...(becameOpen ? { finalized_at: at } : {}) } };
+      fields = {
+        status: becameOpen ? 'open' : (inv.status as string), _sent: true, _sent_at: at,
+        status_transitions: { ...(inv.status_transitions as object ?? {}), ...(becameOpen ? { finalized_at: at } : {}) },
+        ...(becameOpen ? { payment_intent: newPaymentIntentId } : {}),
+      };
     } else if (action === 'pay') {
-      const oob = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
-      fields = { status: 'paid', paid: true, paid_out_of_band: oob, amount_paid: Number(inv.total ?? inv.amount_due) || 0, amount_remaining: 0, status_transitions: { ...(inv.status_transitions as object ?? {}), paid_at: at } };
+      paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
+      fields = { status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: Number(inv.total ?? inv.amount_due) || 0, amount_remaining: 0, status_transitions: { ...(inv.status_transitions as object ?? {}), paid_at: at } };
     } else if (action === 'mark_uncollectible') fields = { status: 'uncollectible', status_transitions: { ...(inv.status_transitions as object ?? {}), marked_uncollectible_at: at } };
     else fields = { status: 'void', status_transitions: { ...(inv.status_transitions as object ?? {}), voided_at: at } };
     // event op for send maps to invoice.sent; others map 1:1 in eventTypeFor.
     const op = action === 'send' ? 'invoice.sent' : action === 'mark_uncollectible' ? 'invoice.marked_uncollectible' : `invoice.${action}`;
-    return { status: 200, body: await writeResource('invoice', idAt(2), fields, op, req.root, req.occurredAt) };
+    const body = await writeResource('invoice', idAt(2), fields, op, req.root, req.occurredAt);
+    if (newPaymentIntentId) await createInvoicePaymentIntent(newPaymentIntentId, inv, idAt(2), req);
+    // A successful (non-declined, non-out-of-band) pay settles the PaymentIntent real Stripe
+    // created at finalize: it moves to `succeeded` and gets a `latest_charge` — the field
+    // PeakHealth's BioReference/BloodworkTab flow reads after `pay`. paid_out_of_band means
+    // the balance was collected OUTSIDE Stripe, so the PI is left alone (never confirmed).
+    if (action === 'pay' && !paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
+      await settleInvoicePaymentIntentOnPay(inv.payment_intent, idAt(2), Number(fields.amount_paid) || 0, req);
+    }
+    return { status: 200, body: expandResource('invoice', body, params, req.root) };
   }
   // GET /v1/invoices/:id/lines — the invoice's line items (a paginated sub-list). The lines
   // live on the invoice's `lines.data`; we paginate them. Unknown invoice → 404. (Must
@@ -2090,7 +2716,7 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       const remove = new Set(entries.map((e) => (typeof e.id === 'string' ? e.id : '')).filter(Boolean));
       next = next.filter((l) => !remove.has(String(l.id)));
     }
-    const subtotal = next.reduce((s, l) => s + (Number(l.amount) || 0), 0);
+    const subtotal = sumInvoiceLines(next);
     const lines = { object: 'list', data: next, has_more: false, total_count: next.length, url: `/v1/invoices/${idAt(2)}/lines` };
     return { status: 200, body: await writeResource('invoice', idAt(2), { lines, subtotal, total: subtotal, amount_due: subtotal, amount_remaining: subtotal }, 'invoice.update', req.root, req.occurredAt) };
   }
@@ -2199,17 +2825,129 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     }
     // Trials: trial_period_days / trial_end put the sub in `trialing` with trial_start/_end.
     const trial = resolveTrial(params, at);
-    const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, ...rest } = params as Record<string, unknown>;
-    return create('subscription', rest, {
-      status: trial ? 'trialing' : 'active', livemode: false, currency: 'usd', collection_method: 'charge_automatically',
+    // Billing period: real Stripe always populates a billing period on a subscription.
+    // During a trial the "current period" IS the trial window (mirrors trial_start/
+    // trial_end); otherwise it's one billing interval — day/week/month/year ×
+    // interval_count, read off the FIRST item's Price (`recurring`) — starting at the
+    // anchor (`at`, same value stored as billing_cycle_anchor/start_date above).
+    //
+    // current_period_start/current_period_end were moved off the top-level
+    // Subscription object onto subscription items in Stripe's 2025-03-31.basil API
+    // version (see stripe-known-deviations.json's subscription.current_period_*
+    // entries) — the vendored schema fixture is fetched from the LATEST published
+    // spec, so it reflects that post-migration shape. This twin's own default served
+    // version when a caller sends no Stripe-Version header is TWIN_API_VERSION
+    // ('2024-06-20', pre-dating the migration — see its definition above), so
+    // emitting these fields top-level here is version-consistent with what this twin
+    // actually serves by default, not a fabrication.
+    const itemEntries = subscriptionItemEntries(params.items);
+    const { interval, interval_count } = resolveSubscriptionBillingInterval(itemEntries, req.root);
+    const periodStart = trial ? trial.start : at;
+    const periodEnd = trial ? trial.end : addBillingInterval(at, interval, interval_count);
+    const subId = typeof params.id === 'string' && params.id ? params.id : nextId('subscription', req.root);
+    const itemsList = buildSubscriptionItemsList(itemEntries, subId, at, req.root);
+    const itemsData = itemsList.data as Array<Record<string, unknown>>;
+    const currency = typeof params.currency === 'string' && params.currency ? params.currency : 'usd';
+
+    // payment_behavior: 'default_incomplete' — the "create subscription now, collect
+    // payment client-side" pattern (what the backend always sends — see
+    // Stripe.service.ts createSubscriptionIntentForUser). Real Stripe auto-generates
+    // the subscription's FIRST Invoice right away, and — unless it's $0 — a linked
+    // PaymentIntent whose client_secret the frontend confirms via Stripe.js
+    // (stripe.confirmPayment). Without this the subscription's `latest_invoice` stays
+    // absent and the frontend never gets a clientSecret to confirm, so checkout for
+    // ANY non-$0 plan can never complete (see PR #199's sibling fix, which populated
+    // current_period_start/_end + items but left this gap). A trialing subscription has
+    // no invoice due yet, so it's excluded — mirrors real Stripe.
+    const paymentBehavior = typeof params.payment_behavior === 'string' ? params.payment_behavior : undefined;
+    const needsFirstInvoice = paymentBehavior === 'default_incomplete' && !trial;
+    let subtotal = 0;
+    for (const it of itemsData) {
+      const price = it.price && typeof it.price === 'object' ? (it.price as Record<string, unknown>) : undefined;
+      subtotal += (Number(price?.unit_amount) || 0) * (Number(it.quantity) || 1);
+    }
+    const coupon = discounts[0]?.coupon as Record<string, unknown> | undefined;
+    const discountAmount = applyCouponDiscount(subtotal, coupon);
+    const invoiceTotal = Math.max(0, subtotal - discountAmount);
+    // A 100%-off coupon (or an item set that totals to 0) still gets a first invoice in
+    // real Stripe, but it's `paid` immediately with no PaymentIntent needed — mirrors
+    // how the twin's Checkout Session setup-mode flow needs no payment either.
+    const isFree = invoiceTotal <= 0;
+
+    // Pre-mint the invoice/PI ids so the subscription's own `latest_invoice` can be set
+    // in the SAME write as its create (avoids a second update — and a second
+    // customer.subscription.updated event — right after creation).
+    const invoiceId = needsFirstInvoice ? nextId('invoice', req.root) : null;
+    const piId = needsFirstInvoice && !isFree ? nextId('payment_intent', req.root) : null;
+
+    const { coupon: _c, discounts: _ds, trial_period_days: _tpd, trial_end: _te, items: _items, id: _id, ...rest } = params as Record<string, unknown>;
+    const subResp = await create('subscription', { ...rest, id: subId }, {
+      status: trial ? 'trialing' : (needsFirstInvoice && !isFree ? 'incomplete' : 'active'),
+      livemode: false, currency, collection_method: 'charge_automatically',
       cancel_at_period_end: false, start_date: at, billing_cycle_anchor: at, metadata: {},
       discounts, billing_schedules: [],
       ...(trial ? { trial_start: trial.start, trial_end: trial.end } : { trial_start: null, trial_end: null }),
-      items: { object: 'list', data: [], has_more: false, total_count: 0 },
+      current_period_start: periodStart, current_period_end: periodEnd,
+      items: itemsList,
+      latest_invoice: invoiceId,
       automatic_tax: { enabled: false, liability: null },
       billing_mode: { type: 'classic' },
       invoice_settings: { issuer: { type: 'self' } },
     }, req);
+
+    // expand[]=latest_invoice / latest_invoice.payment_intent (the two values this
+    // backend sends — see Stripe.service.ts's `expand` array on subscriptions.create):
+    // create() doesn't run expand generically (unlike the GET :id retrieve routes), so
+    // apply it explicitly here. Reuses the same EXPANDABLE map / expandObject machinery
+    // GET already relies on (subscription.latest_invoice -> invoice, invoice.payment_intent
+    // -> payment_intent are already declared there) — a no-op when `expand` is absent.
+    if (!needsFirstInvoice || !invoiceId) {
+      return { status: 200, body: expandResource('subscription', subResp.body as Record<string, unknown>, params, req.root) };
+    }
+
+    const invoiceLines = itemsData.map((it, i) => {
+      const price = it.price && typeof it.price === 'object' ? (it.price as Record<string, unknown>) : undefined;
+      const quantity = Number(it.quantity) || 1;
+      return {
+        id: `il_twin_${invoiceId}_${i + 1}`, object: 'line_item', type: 'subscription',
+        amount: (Number(price?.unit_amount) || 0) * quantity, currency, quantity, proration: false,
+        price: it.price ?? null, subscription: subId, invoice_item: null,
+        period: { start: periodStart, end: periodEnd }, description: null,
+      };
+    });
+    await create('invoice', {
+      id: invoiceId,
+      status: isFree ? 'paid' : 'open', livemode: false, currency, collection_method: 'charge_automatically',
+      auto_advance: false, attempt_count: 0, attempted: !isFree,
+      customer, subscription: subId, billing_reason: 'subscription_create',
+      amount_due: invoiceTotal, amount_paid: isFree ? invoiceTotal : 0, amount_remaining: isFree ? 0 : invoiceTotal,
+      amount_overpaid: 0, amount_paid_off_stripe: 0, amount_shipping: 0,
+      subtotal, total: invoiceTotal, starting_balance: 0,
+      post_payment_credit_notes_amount: 0, pre_payment_credit_notes_amount: 0,
+      period_start: periodStart, period_end: periodEnd,
+      default_tax_rates: [], discounts: discountAmount > 0 && discounts[0] ? [discounts[0]] : [],
+      lines: { object: 'list', data: invoiceLines, has_more: false, total_count: invoiceLines.length, url: `/v1/invoices/${invoiceId}/lines` },
+      automatic_tax: { enabled: false, liability: null, status: null },
+      status_transitions: { finalized_at: at, marked_uncollectible_at: null, paid_at: isFree ? at : null, voided_at: null },
+      issuer: { type: 'self' },
+      payment_settings: { default_mandate: null, payment_method_options: null, payment_method_types: null },
+      payment_intent: piId,
+    }, {}, req);
+
+    if (piId) {
+      // capture_method 'automatic' + status 'requires_payment_method' matches real
+      // Stripe's freshly-created (unconfirmed) PaymentIntent; requires_payment_method
+      // (not requires_confirmation) is the real-Stripe status here because no
+      // payment_method has been attached yet — the frontend collects it via Elements
+      // before calling confirmPayment.
+      await create('payment_intent', { id: piId, amount: invoiceTotal, currency, customer, invoice: invoiceId }, {
+        status: 'requires_payment_method', client_secret: mintClientSecret(piId), livemode: false,
+        capture_method: 'automatic', amount_capturable: 0, amount_received: 0, next_action: null,
+        automatic_payment_methods: null, payment_method_types: ['card', 'link'], payment_method_options: {},
+      }, req);
+    }
+
+    return { status: 200, body: expandResource('subscription', subResp.body as Record<string, unknown>, params, req.root) };
   }
   if (path === '/v1/subscriptions/search' && method === 'GET') return searchResult('subscription', params, path, req.root);
   if (path === '/v1/subscriptions' && method === 'GET') {
@@ -3458,6 +4196,14 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 },
       metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {}, livemode: false,
     };
+    // `subscription_data` is a CREATE-ONLY param in real Stripe (the Session object never
+    // echoes it) but it is NOT discarded: on completion Stripe copies it onto the created
+    // subscription (metadata, trial settings, description, …). Stash it under a reserved
+    // `_`-key the view() projection strips, so the stored Session shape stays faithful
+    // while the completion transition can copy it faithfully.
+    if (params.subscription_data && typeof params.subscription_data === 'object') {
+      fields._subscription_data = params.subscription_data;
+    }
     // `id` is provided so create() does not mint a second one (url must match).
     return create('checkout_session', { id, ...fields }, {}, req);
   }
@@ -3510,15 +4256,43 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       const currency = typeof existing.currency === 'string' ? existing.currency : 'usd';
       if (mode === 'payment') {
         const amount = Number(existing.amount_total) || 0;
-        const pi = await create('payment_intent', { amount, currency, ...(customer ? { customer } : {}) }, { status: 'succeeded', client_secret: 'pi_twin_secret', livemode: false }, req);
+        const linkedPiId = nextId('payment_intent', req.root);
+        const pi = await create('payment_intent', { amount, currency, id: linkedPiId, ...(customer ? { customer } : {}) }, { status: 'succeeded', client_secret: mintClientSecret(linkedPiId), livemode: false }, req);
         link.payment_intent = (pi.body as Record<string, unknown>).id;
         link.payment_status = 'paid';
       } else if (mode === 'subscription') {
         if (customer) {
-          const sub = await create('subscription', { customer }, {
-            status: 'active', livemode: false, currency, collection_method: 'charge_automatically',
-            cancel_at_period_end: false, metadata: {}, discounts: [], billing_schedules: [],
-            items: { object: 'list', data: [], has_more: false, total_count: 0 },
+          // Same billing-period + items fidelity as POST /v1/subscriptions (see the
+          // comments there): a completed subscription-mode Checkout Session also
+          // needs a populated current_period_start/_end and a real items.data, or a
+          // consumer reading either off this session's linked subscription hits the
+          // same gap. Resolve the interval/items from the session's own line_items
+          // (already-resolved Price objects — see buildLineItem's `priceField`).
+          const at = nowUnix(req.occurredAt);
+          const sessionLineItems = ((existing.line_items as { data?: unknown } | undefined)?.data as Array<Record<string, unknown>> | undefined) ?? [];
+          const { interval, interval_count } = resolveSubscriptionBillingInterval(sessionLineItems, req.root);
+          const subId = nextId('subscription', req.root);
+          // Real Stripe copies the session's create-only `subscription_data` onto the
+          // subscription it creates at completion. The twin models the cheap, load-bearing
+          // fields: `metadata` (how apps bind a checkout attempt to the resulting
+          // subscription — dropping it silently orphans the attempt), `description`, and
+          // `trial_period_days` (→ status 'trialing', trial_start/trial_end, and
+          // current_period_end = trial end, exactly like real Stripe). Read from the RAW
+          // row: view() strips the internal `_subscription_data` stash.
+          const rawSession = rows('checkout_session', req.root).find((x) => x.id === idAt(3));
+          const subData = (rawSession?._subscription_data && typeof rawSession._subscription_data === 'object'
+            ? rawSession._subscription_data : {}) as Record<string, unknown>;
+          const subMetadata = (subData.metadata && typeof subData.metadata === 'object') ? subData.metadata as Record<string, unknown> : {};
+          const trialDays = typeof subData.trial_period_days === 'number' && subData.trial_period_days > 0 ? subData.trial_period_days : null;
+          const trialEnd = trialDays === null ? null : at + trialDays * 86400;
+          const sub = await create('subscription', { customer, id: subId }, {
+            status: trialEnd === null ? 'active' : 'trialing', livemode: false, currency, collection_method: 'charge_automatically',
+            cancel_at_period_end: false, start_date: at, billing_cycle_anchor: at, metadata: subMetadata,
+            description: typeof subData.description === 'string' ? subData.description : null,
+            discounts: [], billing_schedules: [],
+            trial_start: trialEnd === null ? null : at, trial_end: trialEnd,
+            current_period_start: at, current_period_end: trialEnd ?? addBillingInterval(at, interval, interval_count),
+            items: buildSubscriptionItemsList(sessionLineItems, subId, at, req.root),
             automatic_tax: { enabled: false, liability: null }, billing_mode: { type: 'classic' },
             invoice_settings: { issuer: { type: 'self' } },
           }, req);
@@ -3527,7 +4301,8 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
         link.payment_status = 'paid';
       } else {
         // setup mode: create+link a succeeded setup_intent; no payment collected.
-        const si = await create('setup_intent', { ...(customer ? { customer } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: 'seti_twin_secret', payment_method_types: ['card'], livemode: false }, req);
+        const linkedSiId = nextId('setup_intent', req.root);
+        const si = await create('setup_intent', { id: linkedSiId, ...(customer ? { customer } : {}) }, { status: 'succeeded', usage: 'off_session', client_secret: mintClientSecret(linkedSiId), payment_method_types: ['card'], livemode: false }, req);
         link.setup_intent = (si.body as Record<string, unknown>).id;
       }
       return { status: 200, body: await writeResource('checkout_session', idAt(3), { ...params, ...link }, 'checkout.session.completed', req.root, req.occurredAt) };
@@ -3941,12 +4716,17 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     const enabledEvents = Array.isArray(params.enabled_events) ? params.enabled_events.map(String) : (typeof params.enabled_events === 'string' ? [params.enabled_events] : undefined);
     if (!enabledEvents || enabledEvents.length === 0) return err('Missing required param: enabled_events.', 400, 'parameter_missing');
     const id = nextId('webhook_endpoint', req.root);
+    const secret = `whsec_twin_${id}`;
     const resp = await create('webhook_endpoint', { ...params, id }, {
       url, enabled_events: enabledEvents, status: 'enabled', livemode: false, metadata: {},
       api_version: '2024-06-20', application: null, description: typeof params.description === 'string' ? params.description : null,
-      secret: `whsec_twin_${id}`,
+      secret,
     }, req);
-    registerStripeWebhook(url);
+    // Register the URL WITH its minted secret (live delivery signs each POST with this
+    // endpoint's own whsec_twin_*; consumers verify with stripe.webhooks.constructEvent
+    // against the secret returned here) AND its enabled_events, so organic fan-out only
+    // reaches endpoints subscribed to the event's type.
+    registerStripeWebhook(url, secret, enabledEvents);
     return resp;
   }
   if (path === '/v1/webhook_endpoints' && method === 'GET') {
@@ -3962,7 +4742,17 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (!w || w._deleted) return err(`No such webhook endpoint: '${idAt(2)}'`, 404, 'resource_missing');
     const fields: Record<string, unknown> = { ...params };
     if (Array.isArray(params.enabled_events)) fields.enabled_events = params.enabled_events.map(String);
-    return { status: 200, body: await writeResource('webhook_endpoint', idAt(2), fields, 'webhook_endpoint.update', req.root, req.occurredAt) };
+    const body = await writeResource('webhook_endpoint', idAt(2), fields, 'webhook_endpoint.update', req.root, req.occurredAt);
+    // Keep the delivery registry in step: an updated url replaces the old registration, and
+    // updated enabled_events replace the subscription the fan-out filters on.
+    const newUrl = typeof body.url === 'string' ? body.url : String(w.url);
+    if (typeof w.url === 'string' && w.url !== newUrl) unregisterStripeWebhook(w.url);
+    registerStripeWebhook(
+      newUrl,
+      typeof body.secret === 'string' ? body.secret : (typeof w.secret === 'string' ? w.secret : undefined),
+      Array.isArray(body.enabled_events) ? body.enabled_events.map(String) : undefined,
+    );
+    return { status: 200, body };
   }
   if (seg[1] === 'webhook_endpoints' && seg.length === 3 && method === 'DELETE') {
     const w = getOne('webhook_endpoint', idAt(2), req.root);
@@ -4092,6 +4882,18 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
   // ════════════════════════════════════════════════════════════════════════════════
   // ISSUING — virtual/physical card issuing (cardholders → cards → authorizations →
   // transactions → disputes). All resources are stateful and round-trip via the kernel.
+  //
+  // Real-time authorization (the synchronous leg): a presented authorization first runs
+  // the card's (then the cardholder's) spending_controls; a violation declines with the
+  // vendor's request_history.reason 'spending_controls' BEFORE any webhook is consulted
+  // (Stripe applies spending controls ahead of the issuing_authorization.request event).
+  // If a registered webhook endpoint subscribes to issuing_authorization.request, the twin
+  // delivers the signed request event SYNCHRONOUSLY and honors the endpoint's JSON
+  // response ({approved: bool, amount?: int}) within Stripe's 2-second window; a timeout
+  // declines with reason 'webhook_timeout', an invalid response with 'webhook_error'
+  // (reason semantics verbatim from stripe@22.3.0 RequestHistory.Reason). With no enrolled
+  // endpoint the authorization stays 'pending' awaiting the (deprecated but still real)
+  // POST /v1/issuing/authorizations/:id/approve|decline API decision.
   // ════════════════════════════════════════════════════════════════════════════════
 
   // ---- Issuing Cardholders ----
@@ -4104,10 +4906,11 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (chType !== 'individual' && chType !== 'company') return err("Invalid type: must be one of 'individual' or 'company'.", 400, 'parameter_invalid_string_enum');
     const billing = params.billing && typeof params.billing === 'object' ? params.billing as Record<string, unknown> : undefined;
     if (!billing || !billing.address || typeof billing.address !== 'object') return err('Missing required param: billing[address].', 400, 'parameter_missing');
-    return create('issuing_cardholder', params, {
+    const chControls = normalizeSpendingControls(params.spending_controls, null);
+    if (chControls.error) return chControls.error;
+    return create('issuing_cardholder', { ...params, spending_controls: chControls.controls ?? emptySpendingControls() }, {
       status: 'active', livemode: false, metadata: {}, phone_number: params.phone_number ?? null,
       email: params.email ?? null, requirements: { disabled_reason: null, past_due: [] },
-      spending_controls: { allowed_categories: null, blocked_categories: null, spending_limits: [], spending_limits_currency: null },
     }, req);
   }
   if (seg[1] === 'issuing' && seg[2] === 'cardholders' && seg.length === 3 && method === 'GET') {
@@ -4124,7 +4927,10 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
   }
   if (seg[1] === 'issuing' && seg[2] === 'cardholders' && seg.length === 4 && method === 'POST') {
     if (!getOne('issuing_cardholder', idAt(3), req.root)) return err(`No such cardholder: '${idAt(3)}'`, 404, 'resource_missing');
-    return { status: 200, body: await writeResource('issuing_cardholder', idAt(3), params, 'issuing_cardholder.updated', req.root, req.occurredAt) };
+    const chUpdate = normalizeSpendingControls(params.spending_controls, null);
+    if (chUpdate.error) return chUpdate.error;
+    const chFields = chUpdate.controls ? { ...params, spending_controls: chUpdate.controls } : params;
+    return { status: 200, body: await writeResource('issuing_cardholder', idAt(3), chFields, 'issuing_cardholder.updated', req.root, req.occurredAt) };
   }
 
   // ---- Issuing Cards ----
@@ -4140,10 +4946,14 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (cardType !== 'virtual' && cardType !== 'physical') return err("Invalid type: must be one of 'virtual' or 'physical'.", 400, 'parameter_invalid_string_enum');
     const seq = rows('issuing_card', req.root).length + 1;
     const last4 = String(4242 + seq).slice(-4);
-    return create('issuing_card', params, {
+    // spending_controls are validated + normalized at write time (closed interval enum,
+    // positive limit amounts, allowed/blocked exclusivity) so present-authorization can
+    // enforce them; an invalid dictionary 400s like the vendor.
+    const sc = normalizeSpendingControls(params.spending_controls, typeof params.currency === 'string' ? params.currency : null);
+    if (sc.error) return sc.error;
+    return create('issuing_card', { ...params, spending_controls: sc.controls ?? emptySpendingControls() }, {
       status: cardType === 'virtual' ? 'active' : 'inactive', livemode: false, metadata: {},
       brand: 'Visa', last4, exp_month: 12, exp_year: 2030, cancellation_reason: null,
-      spending_controls: { allowed_categories: null, blocked_categories: null, spending_limits: [], spending_limits_currency: null },
     }, req);
   }
   if (seg[1] === 'issuing' && seg[2] === 'cards' && seg.length === 3 && method === 'GET') {
@@ -4159,12 +4969,16 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     return c ? { status: 200, body: c } : err(`No such card: '${idAt(3)}'`, 404, 'resource_missing');
   }
   if (seg[1] === 'issuing' && seg[2] === 'cards' && seg.length === 4 && method === 'POST') {
-    if (!getOne('issuing_card', idAt(3), req.root)) return err(`No such card: '${idAt(3)}'`, 404, 'resource_missing');
+    const existingCard = getOne('issuing_card', idAt(3), req.root);
+    if (!existingCard) return err(`No such card: '${idAt(3)}'`, 404, 'resource_missing');
     // Stripe only accepts status transitions to active|inactive|canceled here.
     if (params.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(params.status))) {
       return err("Invalid status: must be one of 'active', 'inactive', or 'canceled'.", 400, 'parameter_invalid_string_enum');
     }
-    return { status: 200, body: await writeResource('issuing_card', idAt(3), params, 'issuing_card.updated', req.root, req.occurredAt) };
+    const scUpdate = normalizeSpendingControls(params.spending_controls, typeof existingCard.currency === 'string' ? existingCard.currency : null);
+    if (scUpdate.error) return scUpdate.error;
+    const fields = scUpdate.controls ? { ...params, spending_controls: scUpdate.controls } : params;
+    return { status: 200, body: await writeResource('issuing_card', idAt(3), fields, 'issuing_card.updated', req.root, req.occurredAt) };
   }
 
   // ---- Issuing Authorizations (+approve / decline) ----
@@ -4179,29 +4993,54 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
       card: (a, v) => a.card === v,
       cardholder: (a, v) => a.cardholder === v,
       status: (a, v) => a.status === v,
-    });
+    }).map((a) => embedIssuingAuthorizationCard({ ...a }, req.root));
     return { status: 200, body: listBody('issuing_authorization', items, path, params) };
   }
   if (seg[1] === 'issuing' && seg[2] === 'authorizations' && seg.length === 4 && method === 'GET') {
     const a = getOne('issuing_authorization', idAt(3), req.root);
-    return a ? { status: 200, body: a } : err(`No such authorization: '${idAt(3)}'`, 404, 'resource_missing');
+    return a ? { status: 200, body: embedIssuingAuthorizationCard({ ...a }, req.root) } : err(`No such authorization: '${idAt(3)}'`, 404, 'resource_missing');
   }
   if (seg[1] === 'issuing' && seg[2] === 'authorizations' && seg.length === 5 && (seg[4] === 'approve' || seg[4] === 'decline') && method === 'POST') {
     const auth = getOne('issuing_authorization', idAt(3), req.root);
     if (!auth) return err(`No such authorization: '${idAt(3)}'`, 404, 'resource_missing');
-    if (auth.status !== 'pending') return err(`This authorization has already been finalized (status ${auth.status}).`, 400, 'authorization_already_finalized');
+    if (auth.status !== 'pending' || auth.approved === true) return err(`This authorization has already been finalized (status ${auth.status}).`, 400, 'authorization_already_finalized');
     const approved = seg[4] === 'approve';
-    const updated = await writeResource('issuing_authorization', idAt(3), {
-      status: 'closed', approved, ...(approved && params.amount !== undefined ? { amount: Math.trunc(Number(params.amount) || 0) } : {}),
-    }, approved ? 'issuing_authorization.updated' : 'issuing_authorization.updated', req.root, req.occurredAt);
-    // An approved authorization materializes a captured Issuing Transaction (type 'capture').
-    if (approved) {
-      const amt = Number((updated as Record<string, unknown>).amount) || 0;
-      await create('issuing_transaction', {
-        authorization: idAt(3), card: auth.card, cardholder: auth.cardholder, amount: -amt,
-        currency: auth.currency ?? 'usd', merchant_data: auth.merchant_data ?? null,
-      }, { type: 'capture', livemode: false, metadata: {}, dispute: null, balance_transaction: null }, req);
+    // The (deprecated but real) API decision is "you" answering the real-time request, so
+    // it lands in request_history with the vendor's webhook_approved / webhook_declined
+    // reason, and the open pending_request is consumed (pending_request is only non-null
+    // while a request is undecided).
+    const decidedSec = nowUnix(req.occurredAt);
+    // A caller-provided amount mirrors the webhook path's partial-approval rule: honored
+    // only when the presentment was amount-controllable (ApprovalParams.amount SDK doc),
+    // and it must be a positive integer — a negative here would CREDIT the issuing balance.
+    if (approved && params.amount !== undefined) {
+      const requestedAmount = Math.trunc(Number(params.amount) || 0);
+      if (requestedAmount <= 0) return err('Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+      const pendingRequest = auth.pending_request as Record<string, unknown> | null | undefined;
+      if (pendingRequest?.is_amount_controllable !== true) {
+        return err('amount may only be provided when the authorization was presented with is_amount_controllable.', 400);
+      }
     }
+    const decidedAmount = approved && params.amount !== undefined ? Math.trunc(Number(params.amount) || 0) : (Number(auth.amount) || 0);
+    const currency = typeof auth.currency === 'string' ? auth.currency : 'usd';
+    const history = Array.isArray(auth.request_history) ? auth.request_history as Array<Record<string, unknown>> : [];
+    // An approved authorization materializes a captured Issuing Transaction (type 'capture')
+    // AND debits the issuing balance (balance_transaction type 'issuing_transaction',
+    // balance_type 'issuing') so the float is honest.
+    const captured = approved ? await materializeIssuingCapture(idAt(3), auth, decidedAmount, req) : null;
+    const priorTxns = Array.isArray(auth.transactions) ? auth.transactions : [];
+    const priorBts = Array.isArray(auth.balance_transactions) ? auth.balance_transactions : [];
+    const updated = await writeResource('issuing_authorization', idAt(3), {
+      status: 'closed', approved, pending_request: null,
+      ...(approved && params.amount !== undefined ? { amount: decidedAmount } : {}),
+      request_history: [...history, requestHistoryEntry({
+        amount: decidedAmount, currency, approved,
+        reason: approved ? 'webhook_approved' : 'webhook_declined', reasonMessage: null,
+        createdSec: decidedSec, merchantAmount: Number(auth.merchant_amount) || decidedAmount,
+        merchantCurrency: typeof auth.merchant_currency === 'string' ? auth.merchant_currency : currency,
+      })],
+      ...(captured ? { transactions: [...priorTxns, captured.txnId], balance_transactions: [...priorBts, captured.btId] } : {}),
+    }, 'issuing_authorization.updated', req.root, req.occurredAt);
     return { status: 200, body: updated };
   }
   if (seg[1] === 'issuing' && seg[2] === 'authorizations' && seg.length === 4 && method === 'POST') {
@@ -4267,11 +5106,13 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     return { status: 200, body: await writeResource('issuing_dispute', idAt(3), params, 'issuing_dispute.updated', req.root, req.occurredAt) };
   }
 
-  // ---- Test helpers: Issuing (fund balance, present authorization) ----
+  // ---- Test helpers: Issuing (fund balance, present authorization, capture) ----
   // POST /v1/test_helpers/issuing/cards/:card/shipping/* — not modeled (physical shipping).
   // POST /v1/test_helpers/issuing/authorizations — PRESENT a card authorization (the test-mode
-  // way to simulate real-time card usage). Stripe requires `card` (must exist) + `amount`. The
-  // authorization is created 'pending' awaiting approve/decline (a real merchant request).
+  // way to simulate real-time card usage). Stripe requires `card` (must exist) + `amount`.
+  // Decision order (see the ISSUING section header): card status → spending_controls →
+  // synchronous issuing_authorization.request webhook (when an endpoint is enrolled) →
+  // otherwise 'pending' awaiting the deprecated approve/decline API.
   if (seg[1] === 'test_helpers' && seg[2] === 'issuing' && seg[3] === 'authorizations' && seg.length === 4 && method === 'POST') {
     const card = typeof params.card === 'string' ? params.card : '';
     if (!card) return err('Missing required param: card.', 400, 'parameter_missing');
@@ -4279,12 +5120,134 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (!c) return err(`No such card: '${card}'`, 400, 'resource_missing');
     if (params.amount === undefined) return err('Missing required param: amount.', 400, 'parameter_missing');
     const amount = Math.trunc(Number(params.amount) || 0);
-    return create('issuing_authorization', { ...params, card, cardholder: c.cardholder }, {
-      status: 'pending', approved: false, amount, currency: params.currency ?? c.currency ?? 'usd',
-      authorization_method: 'online', livemode: false, metadata: {},
-      merchant_data: { category: 'general', city: 'San Francisco', country: 'US', name: 'Twin Test Merchant', network_id: '1234567890' },
-      pending_request: { amount, currency: params.currency ?? c.currency ?? 'usd', is_amount_controllable: false },
-    }, req);
+    const currency = String(params.currency ?? c.currency ?? 'usd');
+    const createdSec = nowUnix(req.occurredAt);
+    const cardholderId = typeof c.cardholder === 'string' ? c.cardholder : '';
+    const merchantData = issuingMerchantData(params.merchant_data);
+    const category = String(merchantData.category ?? '');
+    const country = merchantData.country == null ? null : String(merchantData.country);
+    const isAmountControllable = params.is_amount_controllable === true;
+    const authMethodParam = typeof params.authorization_method === 'string' ? params.authorization_method : 'online';
+    if (!['chip', 'contactless', 'keyed_in', 'online', 'swipe'].includes(authMethodParam)) {
+      return err("Invalid authorization_method: must be one of 'chip', 'contactless', 'keyed_in', 'online', or 'swipe'.", 400, 'parameter_invalid_string_enum');
+    }
+    const merchantAmount = params.merchant_amount !== undefined ? Math.trunc(Number(params.merchant_amount) || 0) : amount;
+    const merchantCurrency = typeof params.merchant_currency === 'string' ? params.merchant_currency : currency;
+    const authId = nextId('issuing_authorization', req.root);
+    // The full vendor authorization shape (all fields the published spec requires).
+    const baseFields: Record<string, unknown> = {
+      amount, amount_details: null, authorization_method: authMethodParam,
+      balance_transactions: [], transactions: [],
+      currency, fleet: null, fuel: null, livemode: false,
+      merchant_amount: merchantAmount, merchant_currency: merchantCurrency, merchant_data: merchantData,
+      metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
+      network_data: null, verification_data: issuingVerificationData(), wallet: null,
+    };
+    const decline = (reason: string, reasonMessage: string | null) =>
+      create('issuing_authorization', { id: authId, card, cardholder: cardholderId }, {
+        ...baseFields, status: 'closed', approved: false, pending_request: null,
+        request_history: [requestHistoryEntry({
+          amount, currency, approved: false, reason, reasonMessage,
+          createdSec, merchantAmount, merchantCurrency,
+        })],
+      }, req);
+    // 1) Card state: an inactive/canceled card declines with the vendor's card_inactive /
+    //    card_canceled request_history reasons (stripe@22.3.0 RequestHistory.Reason).
+    if (c.status === 'canceled') return decline('card_canceled', 'The card has been canceled.');
+    if (c.status !== 'active') return decline('card_inactive', 'The card is inactive.');
+    // 2) spending_controls — card-level first, then cardholder-level; either declines with
+    //    the vendor's single controls reason 'spending_controls'. Applied BEFORE the
+    //    real-time webhook, like Stripe.
+    const cardholderRow = cardholderId ? getOne('issuing_cardholder', cardholderId, req.root) : undefined;
+    const controlsOpts = { amount, category, country, nowSec: createdSec };
+    const violation =
+      spendingControlsViolation(c.spending_controls, { ...controlsOpts, priorApproved: priorApprovedAuthorizations(req.root, 'card', card) }) ??
+      spendingControlsViolation(cardholderRow?.spending_controls, { ...controlsOpts, priorApproved: priorApprovedAuthorizations(req.root, 'cardholder', cardholderId) });
+    if (violation) return decline('spending_controls', violation);
+    // 3) Real-time authorization: the FIRST enabled webhook endpoint enrolled for
+    //    issuing_authorization.request receives the signed request event synchronously and
+    //    its HTTP response decides the authorization.
+    const endpoint = rows('webhook_endpoint', req.root).find((w) =>
+      w._deleted !== true && w.status === 'enabled' && endpointSubscribedTo(w.enabled_events, 'issuing_authorization.request'));
+    if (!endpoint) {
+      // No real-time enrollment: the authorization stays pending awaiting the (deprecated
+      // but real) approve/decline API within the authorization window.
+      return create('issuing_authorization', { id: authId, card, cardholder: cardholderId }, {
+        ...baseFields, status: 'pending', approved: false, request_history: [],
+        pending_request: {
+          amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
+          merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
+        },
+      }, req);
+    }
+    // data.object during an issuing_authorization.request carries the authorization with
+    // pending_request POPULATED ("This field will only be non-null during an
+    // issuing_authorization.request webhook" — stripe@22.3.0 Authorization.pending_request).
+    const pendingRequest = {
+      amount, amount_details: null, currency, is_amount_controllable: isAmountControllable,
+      merchant_amount: merchantAmount, merchant_currency: merchantCurrency, network_risk_score: null,
+    };
+    const requestObject: Record<string, unknown> = embedIssuingAuthorizationCard({
+      object: 'issuing.authorization', id: authId, created: createdSec,
+      ...baseFields, card, cardholder: cardholderId,
+      status: 'pending', approved: false, pending_request: pendingRequest, request_history: [],
+    }, req.root);
+    const requestEvent: StripeEvent = {
+      id: `evt_twin_req_${authId}`, object: 'event', type: 'issuing_authorization.request',
+      created: createdSec, livemode: false, data: { object: requestObject },
+    };
+    // The stored Events API sees the request event too, exactly like real Stripe.
+    await persistStripeEvent('issuing_authorization.request', requestObject, req.root, req.occurredAt, req.apiVersion);
+    const secret = typeof endpoint.secret === 'string' && endpoint.secret ? endpoint.secret : STRIPE_WEBHOOK_FALLBACK_SECRET;
+    const outcome = await requestAuthorizationDecision(String(endpoint.url), requestEvent, secret);
+    if (outcome.kind === 'approved') {
+      // Partial-amount approval is honored only when the request was presented
+      // amount-controllable (pending_request.is_amount_controllable — SDK field doc).
+      const held = isAmountControllable && outcome.amount !== undefined ? outcome.amount : amount;
+      return create('issuing_authorization', { id: authId, card, cardholder: cardholderId }, {
+        ...baseFields, amount: held, status: 'pending', approved: true, pending_request: null,
+        request_history: [requestHistoryEntry({
+          amount: held, currency, approved: true, reason: 'webhook_approved', reasonMessage: null,
+          createdSec, merchantAmount, merchantCurrency,
+        })],
+      }, req);
+    }
+    if (outcome.kind === 'declined') return decline('webhook_declined', null);
+    if (outcome.kind === 'timeout') return decline('webhook_timeout', outcome.message);
+    return decline('webhook_error', outcome.message);
+  }
+  // POST /v1/test_helpers/issuing/authorizations/:id/capture — capture an approved, still-
+  // pending authorization: creates the Issuing Transaction (type 'capture'), debits the
+  // issuing balance, and (by default — close_authorization defaults true, SDK doc) closes
+  // the authorization. capture_amount (SDK: AuthorizationCaptureParams.capture_amount)
+  // allows partial capture up to the held amount.
+  if (seg[1] === 'test_helpers' && seg[2] === 'issuing' && seg[3] === 'authorizations' && seg.length === 6 && seg[5] === 'capture' && method === 'POST') {
+    const auth = getOne('issuing_authorization', idAt(4), req.root);
+    if (!auth) return err(`No such authorization: '${idAt(4)}'`, 404, 'resource_missing');
+    if (auth.approved !== true || auth.status !== 'pending') {
+      return err(`This authorization cannot be captured because it is not an approved pending authorization (status: ${auth.status}, approved: ${auth.approved === true}).`, 400);
+    }
+    const held = Number(auth.amount) || 0;
+    // Cumulative bound: partial captures (close_authorization=false) consume the hold — a
+    // later capture may only take what remains, never re-spend the full held amount.
+    const capturedSoFar = (Array.isArray(auth.transactions) ? auth.transactions : [])
+      .map((t) => getOne('issuing_transaction', String(t), req.root))
+      .reduce((s, t) => s + Math.abs(Number(t?.amount) || 0), 0);
+    const remaining = held - capturedSoFar;
+    const captureAmount = params.capture_amount !== undefined ? Math.trunc(Number(params.capture_amount) || 0) : remaining;
+    if (captureAmount <= 0 || captureAmount > remaining) {
+      return err('Invalid capture_amount: must be a positive integer no greater than the uncaptured authorized amount.', 400, 'parameter_invalid_integer');
+    }
+    const closeAuthorization = params.close_authorization !== false; // defaults true (SDK doc)
+    const captured = await materializeIssuingCapture(idAt(4), auth, captureAmount, req);
+    const priorTxns = Array.isArray(auth.transactions) ? auth.transactions : [];
+    const priorBts = Array.isArray(auth.balance_transactions) ? auth.balance_transactions : [];
+    const updated = await writeResource('issuing_authorization', idAt(4), {
+      ...(closeAuthorization ? { status: 'closed' } : {}),
+      transactions: [...priorTxns, captured.txnId],
+      balance_transactions: [...priorBts, captured.btId],
+    }, 'issuing_authorization.updated', req.root, req.occurredAt);
+    return { status: 200, body: updated };
   }
   // POST /v1/test_helpers/issuing/cards/:id/status — not modeled here (use cards POST update).
   // POST /v1/test_helpers/issuing/transactions/create_force_capture — present a force-captured
@@ -4296,10 +5259,21 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
     if (!c) return err(`No such card: '${card}'`, 400, 'resource_missing');
     if (params.amount === undefined) return err('Missing required param: amount.', 400, 'parameter_missing');
     const amount = Math.trunc(Number(params.amount) || 0);
-    const { amount: _a, ...forceRest } = params as Record<string, unknown>;
-    return create('issuing_transaction', { ...forceRest, card, cardholder: c.cardholder }, {
-      type: 'capture', amount: -Math.abs(amount), currency: params.currency ?? c.currency ?? 'usd',
-      authorization: null, dispute: null, balance_transaction: null, livemode: false, metadata: {},
+    if (amount <= 0) return err('Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
+    const currency = String(params.currency ?? c.currency ?? 'usd');
+    // A force capture is a settlement with no prior authorization — it still debits the
+    // issuing balance (captures move the float, authorization or not).
+    const forcedBt = await create('balance_transaction', {}, {
+      amount: -amount, currency, fee: 0, net: -amount, type: 'issuing_transaction',
+      status: 'available', balance_type: 'issuing', reporting_category: 'issuing_transaction',
+      available_on: nowUnix(req.occurredAt), fee_details: [],
+    }, req);
+    return create('issuing_transaction', { card, cardholder: c.cardholder }, {
+      type: 'capture', amount: -amount, currency,
+      merchant_amount: -amount, merchant_currency: typeof params.merchant_currency === 'string' ? params.merchant_currency : currency,
+      merchant_data: issuingMerchantData(params.merchant_data),
+      authorization: null, dispute: null, balance_transaction: (forcedBt.body as { id: string }).id,
+      livemode: false, metadata: {}, wallet: null, network_data: null, amount_details: null, purchase_details: null,
     }, req);
   }
   // POST /v1/test_helpers/issuing/fund_balance — fund the issuing balance (test mode). Stripe
@@ -4307,6 +5281,7 @@ async function routeStripeTwinRequest(req: StripeRequest): Promise<StripeRespons
   if (seg[1] === 'test_helpers' && seg[2] === 'issuing' && seg[3] === 'fund_balance' && seg.length === 4 && method === 'POST') {
     if (params.amount === undefined) return err('Missing required param: amount.', 400, 'parameter_missing');
     const amount = Math.trunc(Number(params.amount) || 0);
+    if (amount <= 0) return err('Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
     if (params.currency === undefined || params.currency === '') return err('Missing required param: currency.', 400, 'parameter_missing');
     const currency = String(params.currency);
     // Record a funding entry as a balance_transaction tagged issuing so it accrues statefully.