@volter/twin-stripe 2.0.2 → 2.0.4

package/dist/src/semantics/checkout.d.ts

@@ -1,5 +1,10 @@
 import type { Semantics, SemanticsContext } from '@volter/world-core';
 import { type Row } from './shared.js';
+/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
+ *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
+ *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
+ *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
+export declare function nestedMetadata(given: unknown): Row | undefined;
 /** The card the customer entered on the page. */
 export type EnteredCard = {
     number: string;

package/dist/src/semantics/checkout.js

@@ -61,6 +61,28 @@ function sessionTrialRefusal(ctx, param) {
     const message = param === 'trial_end' ? 'The `subscription_data[trial_end]` timestamp has to be at least 48 hours in the future.' : 'The `subscription_data[trial_period_days]` has to be at least 1.';
     return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
 }
+/** The payment method types a session takes: the list a caller pinned to an earlier version gives as
+ *  payment_method_types ("A list of the types of payment methods (e.g., `card`) this Checkout Session can accept", the
+ *  parameter the served version's allowed_payment_method_types is described against: "Unlike `payment_method_types`,
+ *  this acts as a filter on the dynamically computed set of eligible payment methods", docs.stripe.com/api/checkout/
+ *  sessions/create), else the allowed_payment_method_types of the served one, else card. Where the documentation stops
+ *  and the twin decides: an allowed list is answered whole (the twin does not compute eligibility), and without one the
+ *  session takes card (the account's enabled methods are not modelled). */
+function sessionMethodTypes(params) {
+    const given = Array.isArray(params.payment_method_types) ? params.payment_method_types : params.allowed_payment_method_types;
+    return Array.isArray(given) && given.length ? given.map(String) : ['card'];
+}
+/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
+ *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
+ *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
+ *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
+export function nestedMetadata(given) {
+    if (given === '')
+        return {};
+    if (!given || typeof given !== 'object' || Array.isArray(given))
+        return undefined;
+    return Object.fromEntries(Object.entries(given).filter(([, v]) => v !== ''));
+}
 const create = async (ctx) => {
     const params = ctx.params;
     const mode = typeof params.mode === 'string' ? params.mode : 'payment';
@@ -99,8 +121,9 @@ const create = async (ctx) => {
         customer_creation: mode === 'payment' ? (params.customer_creation === 'always' ? 'always' : 'if_required') : null,
         amount_subtotal: entries.length ? items.reduce((s, it) => s + it.amount_subtotal, 0) : null,
         amount_total: entries.length ? items.reduce((s, it) => s + it.amount_total, 0) - off : null,
-        currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: ['card'], expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
+        currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: sessionMethodTypes(params), expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
         discounts: discount ? [{ coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null }] : [],
+        ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: params.allowed_payment_method_types.map(String) } : {}),
         metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, livemode: false,
         // "Details on the state of phone number collection for the session" (docs.stripe.com/api/checkout/sessions/object),
         // off unless the create enables it
@@ -182,10 +205,10 @@ async function complete(ctx, id, existing, card) {
             ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
             // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
             ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
-            ...(pid.metadata && typeof pid.metadata === 'object' ? { metadata: pid.metadata } : {}),
+            ...(nestedMetadata(pid.metadata) ? { metadata: nestedMetadata(pid.metadata) } : {}),
         };
         const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
-        await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: ['card'] });
+        await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: Array.isArray(existing.payment_method_types) ? existing.payment_method_types : ['card'] });
         const charge = await mintCharge(ctx, piId, fields, amount);
         await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
         link.payment_intent = piId;
@@ -208,7 +231,7 @@ async function complete(ctx, id, existing, card) {
             // the session's view never carries its create-only subscription_data: read the stored row
             const raw = ctx.row(CS, id)?._subscription_data;
             const subData = (raw && typeof raw === 'object' ? raw : {});
-            const subMetadata = subData.metadata && typeof subData.metadata === 'object' ? subData.metadata : {};
+            const subMetadata = nestedMetadata(subData.metadata) ?? {};
             // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
             const trialEnd = resolveTrial(subData, now)?.end ?? null;
             const sub = await created(ctx, 'subscription', { customer, id: subId }, {

package/dist/src/semantics/payment-intents.js

@@ -5,6 +5,16 @@ import { settleCharge } from "./ledger.js";
 import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMethodDetails } from "./payment-methods.js";
 import { at_, confirmOnly, created, fail, finder, search } from "./shared.js";
 const PI = 'payment_intent';
+/** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
+ *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list
+ *  refuses a confirm with a method of another type. Kept apart from the intent: a `_` subject is never pushed
+ *  (world-core isTwinBookkeeping). */
+const TYPES_GIVEN = '_payment_intent_types_given';
+/** Whether the intent's caller named its methods: on create (TYPES_GIVEN), or by an update that set its
+ *  payment_method_types ("Alternatively, update the allowed payment_method_types for this PaymentIntent",
+ *  methodNotAllowed below), which the generic update writes as given, so the intent's history holds it. */
+const typesGiven = (ctx, id) => ctx.tree().some((r) => r.type === TYPES_GIVEN && r.id === id)
+    || ctx.history(PI, id).some((e) => e.operation !== 'payment_intent.create' && Array.isArray(e.fields?.payment_method_types));
 const send = (ctx, r) => ctx.reply(r.body, r.status);
 // ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
 //
@@ -143,6 +153,8 @@ const create = async (ctx) => {
         payment_method_options: params.payment_method_options ?? {},
         ...rest,
     }, 'payment_intent.create');
+    if (Array.isArray(given))
+        await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
     if (asBool(confirmNow))
         return confirmIntent(ctx, body, {});
     return ctx.reply(ctx.expand(PI, body));
@@ -156,6 +168,39 @@ const confirm = async (ctx) => {
     const made = await methodFromData(ctx, data);
     return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
 };
+/** The type of the payment method an intent is paid with: its PaymentMethod's, or a documented test name's (pm_card_*,
+ *  tok_* a card; pm_usBankAccount_* a US bank account), else unknown. */
+function methodType(ctx, method) {
+    if (typeof method !== 'string' || !method)
+        return undefined;
+    const row = ctx.get('payment_method', method);
+    if (row)
+        return typeof row.type === 'string' ? row.type : undefined;
+    if (/^pm_us_?bank_?account/i.test(method))
+        return 'us_bank_account';
+    if (/^(pm_card_|tok_)/.test(method))
+        return 'card';
+    return undefined;
+}
+/** A confirm with a payment method of a type the intent's caller did not allow, refused as Stripe refuses it: "The
+ *  PaymentMethod provided (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of
+ *  the following types: card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include
+ *  "card_present"" (a real answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745, an intent made
+ *  with payment_method_types ['card']). Only a list the caller gave restricts: without one Stripe offers the methods
+ *  the account enables, which the twin does not model. Where the evidence stops: that answer's code is not quoted; the
+ *  twin answers payment_intent_invalid_parameter ("One or more provided parameters wasn't allowed for the given
+ *  operation on the PaymentIntent", docs.stripe.com/error-codes), param payment_method. */
+function methodNotAllowed(ctx, existing, params) {
+    const types = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String)
+        : Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types.map(String)
+            : typesGiven(ctx, String(existing.id)) && Array.isArray(existing.payment_method_types) ? existing.payment_method_types.map(String) : undefined;
+    if (!types)
+        return undefined;
+    const type = methodType(ctx, params.payment_method ?? existing.payment_method);
+    if (!type || types.includes(type))
+        return undefined;
+    return ctx.refuse({ status: 400, code: 'payment_intent_invalid_parameter', param: 'payment_method', message: `The PaymentMethod provided (${type}) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: ${types.join(', ')}. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "${type}"` });
+}
 /** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
 async function confirmIntent(ctx, existing, params) {
     const id = String(existing.id);
@@ -166,6 +211,9 @@ async function confirmIntent(ctx, existing, params) {
     const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
     if (named && ctx.get('mandate', named)?.status !== 'active')
         return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
+    const notAllowed = methodNotAllowed(ctx, existing, params);
+    if (notAllowed)
+        return notAllowed;
     // a declining test card leaves the intent needing a payment method, with the error on it and a 402
     const decline = declineFor(finder(ctx), params, existing);
     if (decline) {

package/dist/src/stripe-capabilities.js

@@ -213,6 +213,20 @@ export const STRIPE_CAPABILITIES = [
         const l = await h({ m: 'GET', p: '/v1/customers' });
         return ok(g) && id(g) === id(c) && ok(u) && field(u, 'name') === 'Ada Lovelace' && field(l, 'object') === 'list';
     })),
+    // stripe-node posts a null metadata value as `metadata[key]=` (Cal.com's PaymentIntent metadata, a guest with no phone)
+    done('stripe.metadata.create_empty_value_unset', 'metadata', 'A create\'s metadata key posted empty is not set (an empty value unsets a key); metadata posted empty is {}', 'api', 'common', () => withRoot(async (h) => {
+        const c = await h({ m: 'POST', p: '/v1/customers', b: 'email=sam@twin.test&metadata[identifier]=cal.com&metadata[bookerPhoneNumber]=' });
+        const pi = await h({ m: 'POST', p: '/v1/payment_intents', b: `amount=5000&currency=usd&customer=${id(c)}&metadata[bookingId]=12&metadata[calAccountId]=` });
+        const none = await h({ m: 'POST', p: '/v1/products', b: 'name=Consultation&metadata=' });
+        const got = await h({ m: 'GET', p: `/v1/payment_intents/${id(pi)}` });
+        const md = (r) => r.body.metadata;
+        return ok(c) && JSON.stringify(md(c)) === JSON.stringify({ identifier: 'cal.com' })
+            && ok(pi) && JSON.stringify(md(pi)) === JSON.stringify({ bookingId: '12' }) && JSON.stringify(md(got)) === JSON.stringify({ bookingId: '12' })
+            && ok(none) && JSON.stringify(md(none)) === '{}';
+    })),
+    // Objects on a connected account are that account's: Stripe answers a retrieve of one without its Stripe-Account
+    // header (or with another account's) 404 resource_missing. The twin keeps one store for the platform and its accounts.
+    todo('stripe.connect.account_scoped_objects', 'connect', 'Objects made with a Stripe-Account header are visible only as that account (retrieve/list/update from the platform or another account is resource_missing)', 'api', 'common'),
     done('stripe.customers.list_filter', 'customers', 'Customer list filter by email', 'api', 'core', () => withRoot(async (h) => {
         await h({ m: 'POST', p: '/v1/customers', b: 'email=match@twin.test' });
         await h({ m: 'POST', p: '/v1/customers', b: 'email=other@twin.test' });
@@ -519,6 +533,91 @@ export const STRIPE_CAPABILITIES = [
         const plain = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=500&currency=usd' });
         return field(plain, 'automatic_payment_methods') === null;
     })),
+    // payment_method_types: a caller pinned before 2026-08-26.preview (stripe-node sends the version it is configured
+    // with; Cal.com's paid booking posts payment_method_types[]=card under 2020-08-27) names the methods and the intent
+    // echoes them; a value naming no payment method type is refused in the intents' words ("The payment method type "…"
+    // is invalid. See … for the full list of supported payment method types.", stripe-node issues/1472). From the removal
+    // on the parameter is gone: "Passing `payment_method_types` now returns a 400 error with the code
+    // `payment_method_types_no_longer_supported`", "at 2026-08-26.preview or later" (docs.stripe.com/changelog/dahlia/
+    // 2026-08-26/removes-payment-method-types-parameter-from-payment-intents-setup-intents), on create, update and confirm.
+    done('stripe.payment_intents.payment_method_types', 'payment_intents', 'PaymentIntent payment_method_types: taken and echoed on create/update for a caller pinned before 2026-08-26.preview (an unknown type refused); refused payment_method_types_no_longer_supported at 2026-08-26.preview or later', 'api', 'core', () => withRoot(async (h, root) => {
+        const at = (v, p, b) => handleStripeTwinRequest({ method: 'POST', path: p, body: b, apiVersion: v, root });
+        const pinned = (p, b) => at('2020-08-27', p, b);
+        const pi = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card&metadata[bookingId]=12');
+        const indexed = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[0]=card&payment_method_types[1]=us_bank_account');
+        const updated = await pinned(`/v1/payment_intents/${id(pi)}`, 'payment_method_types[0]=card&payment_method_types[1]=link');
+        const bogus = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[0]=card&payment_method_types[1]=credit_card');
+        const err = (r) => r.body.error;
+        const echoed = ok(pi) && JSON.stringify(field(pi, 'payment_method_types')) === '["card"]' && field(pi, 'metadata')?.bookingId === '12'
+            && ok(indexed) && JSON.stringify(field(indexed, 'payment_method_types')) === '["card","us_bank_account"]'
+            && ok(updated) && JSON.stringify(field(updated, 'payment_method_types')) === '["card","link"]';
+        const unknown = bogus.status === 400 && err(bogus)?.param === 'payment_method_types'
+            && err(bogus)?.message === 'The payment method type "credit_card" is invalid. See https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types for the full list of supported payment method types.';
+        // the cut is the removal version, not the served one: a basil/clover pin is taken, a pin at or after the removal refused
+        const clover = await at('2025-09-30.clover', '/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card');
+        const atRemoval = await at('2026-08-26.preview', '/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card');
+        const afterRemoval = await at('2026-09-15.preview', `/v1/payment_intents/${id(pi)}`, 'payment_method_types[0]=card');
+        const cut = ok(clover) && JSON.stringify(field(clover, 'payment_method_types')) === '["card"]'
+            && [atRemoval, afterRemoval].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported');
+        // the served version: gone from create, update and confirm; allowed_payment_method_types names the methods instead
+        const created = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&payment_method_types[]=card' });
+        const upd = await h({ m: 'POST', p: `/v1/payment_intents/${id(pi)}`, b: 'payment_method_types[0]=card' });
+        const conf = await h({ m: 'POST', p: `/v1/payment_intents/${id(pi)}/confirm`, b: 'payment_method=pm_card_visa&payment_method_types[0]=card' });
+        const gone = [created, upd, conf].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported' && err(r)?.param === 'payment_method_types');
+        const allowed = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&allowed_payment_method_types[0]=card' });
+        return echoed && unknown && cut && gone && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["card"]';
+    })),
+    // A confirm with a payment method of a type the intent's caller did not name is refused: "The PaymentMethod provided
+    // (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types:
+    // card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "card_present""
+    // (Stripe's answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745). An intent whose caller named
+    // none takes the method (the twin's default list stands for the account's enabled methods).
+    done('stripe.payment_intents.confirm_method_type_refused', 'payment_intents', 'PaymentIntent confirm with a payment method of a type outside the payment_method_types the caller gave on create or update is refused (the intent stays unpaid)', 'api', 'common', () => withRoot(async (h, root) => {
+        const bank = await h({ m: 'POST', p: '/v1/payment_methods', b: 'type=us_bank_account&us_bank_account[routing_number]=110000000&us_bank_account[account_number]=000123456789&us_bank_account[account_holder_type]=individual&billing_details[name]=Sam' });
+        const cardOnly = await handleStripeTwinRequest({ method: 'POST', path: '/v1/payment_intents', body: 'amount=5000&currency=usd&payment_method_types[]=card', apiVersion: '2020-08-27', root });
+        const refused = await h({ m: 'POST', p: `/v1/payment_intents/${id(cardOnly)}/confirm`, b: `payment_method=${id(bank)}` });
+        const e = refused.body.error;
+        const after = await h({ m: 'GET', p: `/v1/payment_intents/${id(cardOnly)}` });
+        const paid = await h({ m: 'POST', p: `/v1/payment_intents/${id(cardOnly)}/confirm`, b: 'payment_method=pm_card_visa' });
+        // allowed_payment_method_types restricts the same way; an intent naming none takes the bank account
+        const allowed = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&allowed_payment_method_types[0]=card' });
+        const refusedToo = await h({ m: 'POST', p: `/v1/payment_intents/${id(allowed)}/confirm`, b: `payment_method=${id(bank)}` });
+        const open = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd' });
+        const taken = await h({ m: 'POST', p: `/v1/payment_intents/${id(open)}/confirm`, b: `payment_method=${id(bank)}` });
+        // an update naming the methods restricts as a create's does: made naming none, updated to card, then refused a bank account
+        const later = await handleStripeTwinRequest({ method: 'POST', path: '/v1/payment_intents', body: 'amount=5000&currency=usd', apiVersion: '2020-08-27', root });
+        const narrowed = await handleStripeTwinRequest({ method: 'POST', path: `/v1/payment_intents/${id(later)}`, body: 'payment_method_types[0]=card', apiVersion: '2020-08-27', root });
+        const refusedLater = await h({ m: 'POST', p: `/v1/payment_intents/${id(later)}/confirm`, b: `payment_method=${id(bank)}` });
+        return ok(bank) && ok(cardOnly) && refused.status === 400 && e?.param === 'payment_method'
+            && String(e?.message).startsWith('The PaymentMethod provided (us_bank_account) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: card.')
+            && field(after, 'status') === 'requires_payment_method' && field(after, 'payment_method') == null
+            && ok(paid) && field(paid, 'status') === 'succeeded'
+            && refusedToo.status === 400 && ok(taken) && field(taken, 'status') === 'processing'
+            && ok(narrowed) && refusedLater.status === 400 && refusedLater.body.error?.param === 'payment_method';
+    })),
+    // The same parameter on SetupIntents: taken from a caller pinned to an earlier version, gone in the served one, whose
+    // changelog names "the create and update methods on Setup Intents" (payment_method_types_no_longer_supported).
+    done('stripe.setup_intents.payment_method_types', 'payment_methods', 'SetupIntent payment_method_types: taken and echoed for a caller pinned before 2026-08-26.preview (an unknown type refused in Stripe\'s words); refused payment_method_types_no_longer_supported at 2026-08-26.preview or later', 'api', 'common', () => withRoot(async (h, root) => {
+        const at = (v, p, b) => handleStripeTwinRequest({ method: 'POST', path: p, body: b, apiVersion: v, root });
+        const pinned = (p, b) => at('2020-08-27', p, b);
+        const si = await pinned('/v1/setup_intents', 'payment_method_types[]=us_bank_account');
+        const bogus = await pinned('/v1/setup_intents', 'payment_method_types[0]=bank');
+        const atRemoval = await at('2026-08-26.preview', '/v1/setup_intents', 'payment_method_types[]=card');
+        const err = (r) => r.body.error;
+        const created = await h({ m: 'POST', p: '/v1/setup_intents', b: 'payment_method_types[]=card' });
+        const upd = await h({ m: 'POST', p: `/v1/setup_intents/${id(si)}`, b: 'payment_method_types[0]=card' });
+        const allowed = await h({ m: 'POST', p: '/v1/setup_intents', b: 'allowed_payment_method_types[]=us_bank_account' });
+        return ok(si) && JSON.stringify(field(si, 'payment_method_types')) === '["us_bank_account"]'
+            && bogus.status === 400 && err(bogus)?.param === 'payment_method_types'
+            && err(bogus)?.message === 'The payment method type "bank" is invalid. See https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types for the full list of supported payment method types.'
+            && [created, upd, atRemoval].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported')
+            && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["us_bank_account"]';
+    })),
+    // Both ways of choosing methods on one create (payment_method_types with automatic_payment_methods[enabled]=true)
+    // for a caller pinned before the removal: Stripe's documentation states no refusal (docs.stripe.com/api/
+    // payment_intents/create, docs.stripe.com/upgrades/manage-payment-methods, docs.stripe.com/changelog/2023-08-16/
+    // automatic-payment-methods describe each alone), so the twin's answer waits for a captured one.
+    todo('stripe.payment_intents.method_types_with_automatic', 'payment_intents', 'PaymentIntent/SetupIntent create with both payment_method_types and automatic_payment_methods[enabled]=true (pinned before 2026-08-26.preview): Stripe\'s answer (refusal and its words) is undocumented', 'api', 'niche'),
     // PaymentIntent search: GET /v1/payment_intents/search?query=… returns the search_result
     // envelope; supports AND-combined clauses (currency:"usd" AND amount>=num). Missing query 400s.
     done('stripe.payment_intents.search', 'payment_intents', 'PaymentIntent search', 'api', 'common', () => withRoot(async (h) => {
@@ -1945,6 +2044,48 @@ export const STRIPE_CAPABILITIES = [
             && typeof field(sub, 'trial_end') === 'number' && field(sub, 'trial_end') === item?.current_period_end
             && field(sub, 'current_period_end') === undefined;
     })),
+    // A session's payment method types: payment_method_types from a caller pinned to an earlier version ("A list of the
+    // types of payment methods (e.g., `card`) this Checkout Session can accept"), allowed_payment_method_types in the served
+    // version, whose spec takes no payment_method_types on a session's create (an unknown parameter there: the changelog's
+    // payment_method_types_no_longer_supported names only the intents). The PaymentIntent paying makes carries the list.
+    done('stripe.checkout.payment_method_types', 'checkout', 'Checkout Session payment_method_types (earlier version) and allowed_payment_method_types (served) name the session\'s methods and its PaymentIntent\'s; an unknown type refused', 'api', 'common', () => withRoot(async (h, root) => {
+        const line = 'mode=payment&success_url=https://x.test&line_items[0][price_data][currency]=usd&line_items[0][price_data][unit_amount]=5000&line_items[0][price_data][product_data][name]=Consultation&line_items[0][quantity]=1';
+        const pinned = (b) => handleStripeTwinRequest({ method: 'POST', path: '/v1/checkout/sessions', body: `${line}&${b}`, apiVersion: '2020-08-27', root });
+        const cs = await pinned('payment_method_types[0]=card&payment_method_types[1]=link');
+        const bogus = await pinned('payment_method_types[0]=cards');
+        // Checkout's own list: a PaymentMethod type it does not take (in person) is refused, and is not in the list offered
+        const inPerson = await pinned('payment_method_types[0]=card&payment_method_types[1]=card_present');
+        const served = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `${line}&payment_method_types[0]=card` });
+        const allowed = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `${line}&allowed_payment_method_types[0]=card` });
+        await h({ m: 'POST', p: `/c/pay/${id(cs)}`, b: 'email=pay%40twin.test&cardNumber=4242424242424242&cardExpiry=12%2F34&cardCvc=123&billingName=Twin&billingCountry=US&billingPostalCode=94105' });
+        const done = await h({ m: 'GET', p: `/v1/checkout/sessions/${id(cs)}` });
+        const pi = await h({ m: 'GET', p: `/v1/payment_intents/${String(field(done, 'payment_intent'))}` });
+        const err = (r) => r.body.error;
+        return ok(cs) && JSON.stringify(field(cs, 'payment_method_types')) === '["card","link"]'
+            && bogus.status === 400 && err(bogus)?.param === 'payment_method_types[0]' && /^Invalid payment_method_types\[0\]: must be one of acss_debit, .*\bcard\b.*, or zip$/.test(String(err(bogus)?.message))
+            && inPerson.status === 400 && err(inPerson)?.param === 'payment_method_types[1]' && !/card_present|interac_present/.test(String(err(inPerson)?.message))
+            && served.status === 400 && err(served)?.code === 'parameter_unknown'
+            && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["card"]' && JSON.stringify(field(allowed, 'allowed_payment_method_types')) === '["card"]'
+            && ok(pi) && JSON.stringify(field(pi, 'payment_method_types')) === '["card","link"]';
+    })),
+    // Metadata a session passes on is kept as a create's own: "Individual keys can be unset by posting an empty value to
+    // them. All keys can be unset by posting an empty value to `metadata`" (docs.stripe.com/api/metadata). stripe-node
+    // posts a null as `…[metadata][key]=`; the PaymentIntent and the Subscription paying makes hold no such key.
+    done('stripe.checkout.nested_metadata_empty_unset', 'checkout', 'A session\'s payment_intent_data[metadata] and subscription_data[metadata] keys posted empty are not set on the PaymentIntent / Subscription completion makes; metadata posted empty is {}', 'api', 'common', () => withRoot(async (h) => {
+        const pay = (cs) => h({ m: 'POST', p: `/c/pay/${id(cs)}`, b: 'email=pay%40twin.test&cardNumber=4242424242424242&cardExpiry=12%2F34&cardCvc=123&billingName=Twin&billingCountry=US&billingPostalCode=94105' });
+        const cust = await h({ m: 'POST', p: '/v1/customers', b: 'email=md@twin.test' });
+        const item = 'line_items[0][price_data][currency]=usd&line_items[0][price_data][unit_amount]=5000&line_items[0][price_data][product_data][name]=Plan&line_items[0][quantity]=1';
+        const payment = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=payment&success_url=https://x.test&${item}&payment_intent_data[metadata][bookingId]=12&payment_intent_data[metadata][phone]=` });
+        const sub = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=subscription&success_url=https://x.test&customer=${id(cust)}&${item}&line_items[0][price_data][recurring][interval]=month&subscription_data[metadata][teamId]=7&subscription_data[metadata][coupon]=` });
+        const none = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=payment&success_url=https://x.test&${item}&payment_intent_data[metadata]=` });
+        await pay(payment);
+        await pay(sub);
+        await pay(none);
+        const get = async (cs, kind, link) => field(await h({ m: 'GET', p: `/v1/${kind}/${String(field(await h({ m: 'GET', p: `/v1/checkout/sessions/${id(cs)}` }), link))}` }), 'metadata');
+        return JSON.stringify(await get(payment, 'payment_intents', 'payment_intent')) === '{"bookingId":"12"}'
+            && JSON.stringify(await get(sub, 'subscriptions', 'subscription')) === '{"teamId":"7"}'
+            && JSON.stringify(await get(none, 'payment_intents', 'payment_intent')) === '{}';
+    })),
     // A subscription session's customer pays its first invoice on the page: the invoice is paid through a succeeded
     // PaymentIntent and its charge, and the card is the subscription's default payment method
     // (docs.stripe.com/payments/checkout/how-checkout-works).

package/dist/src/stripe-params.d.ts

@@ -1,3 +1,14 @@
 import { type DerivedCall } from '@volter/world-core';
+/** The version that removed payment_method_types from the intents: a caller pinned to it or later is refused. */
+export declare const METHOD_TYPES_REMOVED_IN = "2026-08-26.preview";
+/** Whether a pinned version is at or after the removal: versions order by their date (YYYY-MM-DD). */
+export declare const methodTypesRemoved: (pinned: string) => boolean;
+/** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
+export declare const PAYMENT_METHOD_TYPES: readonly string[];
+/** The payment method types a Checkout Session takes: the vendored spec's (2026-09-30.endive) PostCheckoutSessions
+ *  allowed_payment_method_types item enum, the parameter described as payment_method_types is ("A list of the types of
+ *  payment methods (e.g., `card`) this Checkout Session can accept"). It holds no in-person type (card_present,
+ *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
+export declare const CHECKOUT_METHOD_TYPES: readonly string[];
 /** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
 export declare function refuseParameters(call: DerivedCall): Promise<Response | undefined>;

package/dist/src/stripe-params.js

@@ -7,8 +7,8 @@
 // 2025-09-30.clover) was accepted.
 //
 // Where the evidence stops: the check knows only the served version's parameters (the spec's, surface.version). A
-// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec;
-// nested parameters are not checked.
+// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec, beyond
+// the values of the payment_method_types it still takes (PAYMENT_METHOD_TYPES below); nested parameters are not checked.
 import { readParams, vendorError } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest } from "./manifest.js";
@@ -19,17 +19,87 @@ const DOCUMENTED = {
     // a top-up into the Issuing balance (docs.stripe.com/issuing/funding/balance: "destination_balance=issuing")
     PostTopups: ['destination_balance'],
 };
+// PAYMENT_METHOD_TYPES. The operations that took `payment_method_types` until 2026-08-26.preview, which "Removes
+// `payment_method_types` as a writable parameter from the create, update, and confirm methods on Payment Intents, and
+// from the create and update methods on Setup Intents. Passing `payment_method_types` now returns a 400 error with the
+// code `payment_method_types_no_longer_supported`", for a caller "at 2026-08-26.preview or later"
+// (docs.stripe.com/changelog/dahlia/2026-08-26/removes-payment-method-types-parameter-from-payment-intents-setup-
+// intents). The served spec (2026-09-30.endive) has no such parameter on them, nor on a Checkout Session's create,
+// which the changelog does not name: there it is an unknown parameter for a caller on the served version, and taken
+// from any caller pinned before it.
+// A caller pinned before the removal (stripe-node sends the version it is configured with: Cal.com's 2020-08-27)
+// still sends it, "The list of payment method types (e.g. card) that this PaymentIntent is allowed to use. A
+// comprehensive list of valid payment method types can be found here" (the served spec's payment_intent object, the
+// link being the PaymentMethod object's `type`). A PaymentIntent's or SetupIntent's value outside that list is refused
+// as Stripe refuses one there: "The payment method type "us_bank_account" is invalid. See
+// https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types for the full list of
+// supported payment method types." (a real SetupIntent answer quoted in github.com/stripe/stripe-node/issues/1472).
+// A Checkout Session's value outside its own enum is refused as Stripe refuses any value outside a parameter's enum:
+// "Invalid payment_settings[payment_method_types][1]: must be one of ach_credit_transfer, …, or wechat_pay" (a real
+// answer quoted in github.com/stripe/stripe-node/issues/1755), with no code. Where the evidence stops: the message
+// Stripe gives with payment_method_types_no_longer_supported is not documented (the twin's own words below); the
+// PaymentIntent's link is the SetupIntent's with its own resource (no PaymentIntent answer is quoted), and neither
+// answer's param nor code is quoted (the twin gives param payment_method_types, no code); the lists are the served
+// version's, not the pinned one's.
+/** The version that removed payment_method_types from the intents: a caller pinned to it or later is refused. */
+export const METHOD_TYPES_REMOVED_IN = '2026-08-26.preview';
+/** Whether a pinned version is at or after the removal: versions order by their date (YYYY-MM-DD). */
+export const methodTypesRemoved = (pinned) => pinned.slice(0, 10) >= METHOD_TYPES_REMOVED_IN.slice(0, 10);
+const REMOVED_TYPES = new Set(['PostPaymentIntents', 'PostPaymentIntentsIntent', 'PostPaymentIntentsIntentConfirm', 'PostSetupIntents', 'PostSetupIntentsIntent']);
+const TYPED = new Set([...REMOVED_TYPES, 'PostCheckoutSessions']);
+/** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
+export const PAYMENT_METHOD_TYPES = surface.resources.find((r) => r.name === 'payment_method')?.fields.find((f) => f.name === 'type')?.enum ?? [];
+/** The payment method types a Checkout Session takes: the vendored spec's (2026-09-30.endive) PostCheckoutSessions
+ *  allowed_payment_method_types item enum, the parameter described as payment_method_types is ("A list of the types of
+ *  payment methods (e.g., `card`) this Checkout Session can accept"). It holds no in-person type (card_present,
+ *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
+export const CHECKOUT_METHOD_TYPES = ['acss_debit', 'affirm', 'afterpay_clearpay', 'alipay', 'alma', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'billie', 'bizum', 'blik', 'boleto', 'card', 'cashapp', 'crypto', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'kakao_pay', 'klarna', 'konbini', 'kr_card', 'link', 'mb_way', 'mobilepay', 'multibanco', 'naver_pay', 'nz_bank_account', 'oxxo', 'p24', 'pay_by_bank', 'payco', 'paynow', 'paypal', 'paypay', 'payto', 'pix', 'promptpay', 'revolut_pay', 'samsung_pay', 'satispay', 'scalapay', 'sepa_debit', 'sequra', 'sofort', 'sunbit', 'swish', 'twint', 'upi', 'us_bank_account', 'wechat_pay', 'zip'];
+/** The create page each intent's refusal links to. */
+const TYPES_DOC = {
+    payment_intents: 'https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types',
+    setup_intents: 'https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types',
+};
+/** An enum's values as Stripe lists them in a refusal: "a, b, or c". */
+const oneOf = (values) => (values.length > 1 ? `${values.slice(0, -1).join(', ')}, or ${values.at(-1)}` : values.join(''));
+/** An earlier version's payment_method_types refused: the first value that names no payment method type the
+ *  operation takes, in the intent's words or (a Checkout Session) the enum's. */
+function unknownMethodType(opId, given) {
+    const values = Array.isArray(given) ? given : given && typeof given === 'object' ? Object.values(given) : [given];
+    const checkout = opId === 'PostCheckoutSessions';
+    const known = checkout ? CHECKOUT_METHOD_TYPES : PAYMENT_METHOD_TYPES;
+    const i = values.findIndex((v) => !known.includes(String(v)));
+    if (i < 0)
+        return undefined;
+    if (checkout) {
+        const param = `payment_method_types[${i}]`;
+        return vendorError(manifest, { status: 400, param, message: `Invalid ${param}: must be one of ${oneOf(known)}` });
+    }
+    const doc = TYPES_DOC[opId.startsWith('PostSetupIntents') ? 'setup_intents' : 'payment_intents'];
+    return vendorError(manifest, { status: 400, param: 'payment_method_types', message: `The payment method type "${String(values[i])}" is invalid. See ${doc} for the full list of supported payment method types.` });
+}
+/** payment_method_types refused where the caller's version removed it. */
+const noLongerSupported = (version) => vendorError(manifest, { status: 400, code: 'payment_method_types_no_longer_supported', param: 'payment_method_types', message: `payment_method_types is no longer supported in API version ${version}. Use allowed_payment_method_types, or dynamic payment methods, instead.` });
 /** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
 export async function refuseParameters(call) {
     const op = OPS.get(call.operation.id);
     if (!op)
         return undefined;
     const pinned = call.request.headers.get('stripe-version');
-    if (pinned && pinned < SERVED_VERSION)
-        return undefined;
+    if (pinned && pinned < SERVED_VERSION) {
+        if (!TYPED.has(op.id))
+            return undefined;
+        const earlier = await readParams(manifest, call.request.clone(), call.operation);
+        if (earlier.payment_method_types === undefined)
+            return undefined;
+        if (REMOVED_TYPES.has(op.id) && methodTypesRemoved(pinned))
+            return noLongerSupported(pinned);
+        return unknownMethodType(op.id, earlier.payment_method_types);
+    }
     const method = call.request.method.toUpperCase();
     const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
     const params = await readParams(manifest, call.request.clone(), call.operation);
+    if (REMOVED_TYPES.has(op.id) && params.payment_method_types !== undefined)
+        return noLongerSupported(pinned ?? SERVED_VERSION);
     for (const name of Object.keys(params)) {
         if (!known.has(name))
             return vendorError(manifest, { status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });

package/dist/src/stripe-server.js

@@ -346,6 +346,34 @@ export async function createStripeTwinServer(options) {
     });
     return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }
+/** A create's `metadata` holds no key posted empty. "Individual keys can be unset by posting an empty value to them. All
+ *  keys can be unset by posting an empty value to `metadata`" (every metadata parameter of docs.stripe.com/api): an empty
+ *  value is the absence of the key, on a create as on an update, so an object never holds a key set to "". Clients post
+ *  one without meaning to: stripe-node encodes a `null` value as `metadata[key]=` (Cal.com's PaymentIntent metadata
+ *  carries `bookerPhoneNumber: null` for a guest who gave no phone). The request is rewritten as JSON without them. */
+async function createMetadata(request, path) {
+    const op = CREATES.find((c) => c.re.test(path))?.op;
+    if (!op)
+        return request;
+    const params = await readParams(manifest, request.clone(), op);
+    if (!('metadata' in params))
+        return request;
+    const given = params.metadata;
+    let metadata;
+    if (given === '')
+        metadata = {};
+    else if (given && typeof given === 'object' && !Array.isArray(given) && Object.values(given).includes('')) {
+        metadata = Object.fromEntries(Object.entries(given).filter(([, v]) => v !== ''));
+    }
+    else
+        return request;
+    const headers = new Headers(request.headers);
+    headers.set('content-type', 'application/json');
+    return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...params, metadata }) });
+}
+// the create operations, by their path as a pattern, for createMetadata
+const CREATES = surface.operations.filter((o) => o.class === 'create' && o.method.toUpperCase() === 'POST')
+    .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
 // the update operations, by their path as a pattern, for mergeMetadata
 const UPDATES = surface.operations.filter((o) => o.class === 'update' && o.method.toUpperCase() === 'POST')
     .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
@@ -371,7 +399,9 @@ async function mergeMetadata(request, coreMerges, scope) {
             break;
         }
     }
-    if (!op?.resource)
+    if (!op)
+        return createMetadata(request, path);
+    if (!op.resource)
         return request;
     const params = await readParams(manifest, request.clone(), op);
     if (!('metadata' in params))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-stripe",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Local Stripe twin — a faithful, stateful local Stripe API your real `stripe` SDK talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -56,15 +56,15 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "dependencies": {
-    "@volter/world-ui": "0.1.2",
+    "@volter/world-ui": "0.1.3",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.2"
+    "@volter/world-core": "2.0.3"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.2",
+    "@volter/world-core": "2.0.3",
     "@volter/world-tooling": "0.1.0",
     "@types/bun": "^1.2.20",
     "@types/node": "^24.0.0",

package/src/semantics/checkout.ts

@@ -67,6 +67,28 @@ function sessionTrialRefusal(ctx: SemanticsContext, param: 'trial_end' | 'trial_
   return ctx.refuse({ status: 400, param: `subscription_data[${param}]`, message });
 }
 
+/** The payment method types a session takes: the list a caller pinned to an earlier version gives as
+ *  payment_method_types ("A list of the types of payment methods (e.g., `card`) this Checkout Session can accept", the
+ *  parameter the served version's allowed_payment_method_types is described against: "Unlike `payment_method_types`,
+ *  this acts as a filter on the dynamically computed set of eligible payment methods", docs.stripe.com/api/checkout/
+ *  sessions/create), else the allowed_payment_method_types of the served one, else card. Where the documentation stops
+ *  and the twin decides: an allowed list is answered whole (the twin does not compute eligibility), and without one the
+ *  session takes card (the account's enabled methods are not modelled). */
+function sessionMethodTypes(params: Row): string[] {
+  const given = Array.isArray(params.payment_method_types) ? params.payment_method_types : params.allowed_payment_method_types;
+  return Array.isArray(given) && given.length ? given.map(String) : ['card'];
+}
+
+/** Metadata passed on to what a session makes (payment_intent_data[metadata], subscription_data[metadata]) as a
+ *  create's own is kept: "Individual keys can be unset by posting an empty value to them. All keys can be unset by
+ *  posting an empty value to `metadata`" (every metadata parameter, docs.stripe.com/api/metadata), so a key posted
+ *  empty is not set, and metadata posted empty is {} (stripe-server.ts createMetadata, the top-level case). */
+export function nestedMetadata(given: unknown): Row | undefined {
+  if (given === '') return {};
+  if (!given || typeof given !== 'object' || Array.isArray(given)) return undefined;
+  return Object.fromEntries(Object.entries(given as Row).filter(([, v]) => v !== ''));
+}
+
 const create: Semantics = async (ctx) => {
   const params = ctx.params;
   const mode = typeof params.mode === 'string' ? params.mode : 'payment';
@@ -99,8 +121,9 @@ const create: Semantics = async (ctx) => {
     customer_creation: mode === 'payment' ? (params.customer_creation === 'always' ? 'always' : 'if_required') : null,
     amount_subtotal: entries.length ? items.reduce((s, it) => s + it.amount_subtotal, 0) : null,
     amount_total: entries.length ? items.reduce((s, it) => s + it.amount_total, 0) - off : null,
-    currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: ['card'], expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
+    currency: items[0]?.currency ?? (entries.length ? sessionCurrency : null), line_items: { object: 'list', data: items, has_more: false, url: `/v1/checkout/sessions/${id}/line_items` }, payment_intent: null, subscription: null, setup_intent: null, invoice: null, payment_method_types: sessionMethodTypes(params), expires_at: now + 24 * 3600, custom_fields: [], shipping_options: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null }, automatic_tax: { enabled: false, liability: null, status: null, provider: null }, total_details: { amount_discount: off, amount_shipping: 0, amount_tax: 0 },
     discounts: discount ? [{ coupon: String(discount.coupon.id), promotion_code: discount.promotion ?? null }] : [],
+    ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: params.allowed_payment_method_types.map(String) } : {}),
     metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {}, livemode: false,
     // "Details on the state of phone number collection for the session" (docs.stripe.com/api/checkout/sessions/object),
     // off unless the create enables it
@@ -179,10 +202,10 @@ async function complete(ctx: SemanticsContext, id: string, existing: Row, card?:
       ...(typeof pid.description === 'string' ? { description: pid.description } : {}),
       // the session's setup_future_usage is its PaymentIntent's (payment_intent_data: "A subset of parameters to be passed to PaymentIntent creation")
       ...(typeof pid.setup_future_usage === 'string' ? { setup_future_usage: pid.setup_future_usage } : {}),
-      ...(pid.metadata && typeof pid.metadata === 'object' ? { metadata: pid.metadata } : {}),
+      ...(nestedMetadata(pid.metadata) ? { metadata: nestedMetadata(pid.metadata) } : {}),
     };
     const fields = { amount, currency, id: piId, ...(customer ? { customer } : {}), ...(pm ? { payment_method: pm.id } : {}), ...connect };
-    await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: ['card'] });
+    await created(ctx, 'payment_intent', fields, { status: 'succeeded', amount_received: amount, client_secret: mintClientSecret(piId), livemode: false, payment_method_types: Array.isArray(existing.payment_method_types) ? existing.payment_method_types : ['card'] });
     const charge = await mintCharge(ctx, piId, fields, amount);
     await ctx.write('payment_intent', piId, { latest_charge: charge }, 'payment_intent.succeeded');
     link.payment_intent = piId;
@@ -204,7 +227,7 @@ async function complete(ctx: SemanticsContext, id: string, existing: Row, card?:
       // the session's view never carries its create-only subscription_data: read the stored row
       const raw = ctx.row(CS, id)?._subscription_data;
       const subData = (raw && typeof raw === 'object' ? raw : {}) as Row;
-      const subMetadata = subData.metadata && typeof subData.metadata === 'object' ? (subData.metadata as Row) : {};
+      const subMetadata = nestedMetadata(subData.metadata) ?? {};
       // a trial of `trial_period_days` from now, or to `trial_end` (docs.stripe.com/payments/checkout/free-trials)
       const trialEnd = resolveTrial(subData, now)?.end ?? null;
       const sub = await created(ctx, 'subscription', { customer, id: subId }, {

package/src/semantics/payment-intents.ts

@@ -23,6 +23,17 @@ import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMetho
 import { at_, confirmOnly, created, fail, finder, search, type Row } from './shared.ts';
 
 const PI = 'payment_intent';
+/** Bookkeeping: the intents whose caller named the methods (payment_method_types, allowed_payment_method_types) on
+ *  create. The twin's default list (['card']) stands for Stripe's choice and restricts nothing, so only a named list
+ *  refuses a confirm with a method of another type. Kept apart from the intent: a `_` subject is never pushed
+ *  (world-core isTwinBookkeeping). */
+const TYPES_GIVEN = '_payment_intent_types_given';
+/** Whether the intent's caller named its methods: on create (TYPES_GIVEN), or by an update that set its
+ *  payment_method_types ("Alternatively, update the allowed payment_method_types for this PaymentIntent",
+ *  methodNotAllowed below), which the generic update writes as given, so the intent's history holds it. */
+const typesGiven = (ctx: SemanticsContext, id: string): boolean =>
+  ctx.tree().some((r) => r.type === TYPES_GIVEN && r.id === id)
+  || ctx.history(PI, id).some((e) => e.operation !== 'payment_intent.create' && Array.isArray(e.fields?.payment_method_types));
 
 const send = (ctx: SemanticsContext, r: StripeResponse): Response => ctx.reply(r.body, r.status);
 
@@ -165,6 +176,7 @@ const create: Semantics = async (ctx) => {
     },
     'payment_intent.create',
   );
+  if (Array.isArray(given)) await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
   if (asBool(confirmNow)) return confirmIntent(ctx, body, {});
   return ctx.reply(ctx.expand(PI, body));
 };
@@ -178,6 +190,35 @@ const confirm: Semantics = async (ctx) => {
   return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
 };
 
+/** The type of the payment method an intent is paid with: its PaymentMethod's, or a documented test name's (pm_card_*,
+ *  tok_* a card; pm_usBankAccount_* a US bank account), else unknown. */
+function methodType(ctx: SemanticsContext, method: unknown): string | undefined {
+  if (typeof method !== 'string' || !method) return undefined;
+  const row = ctx.get('payment_method', method);
+  if (row) return typeof row.type === 'string' ? row.type : undefined;
+  if (/^pm_us_?bank_?account/i.test(method)) return 'us_bank_account';
+  if (/^(pm_card_|tok_)/.test(method)) return 'card';
+  return undefined;
+}
+
+/** A confirm with a payment method of a type the intent's caller did not allow, refused as Stripe refuses it: "The
+ *  PaymentMethod provided (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of
+ *  the following types: card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include
+ *  "card_present"" (a real answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745, an intent made
+ *  with payment_method_types ['card']). Only a list the caller gave restricts: without one Stripe offers the methods
+ *  the account enables, which the twin does not model. Where the evidence stops: that answer's code is not quoted; the
+ *  twin answers payment_intent_invalid_parameter ("One or more provided parameters wasn't allowed for the given
+ *  operation on the PaymentIntent", docs.stripe.com/error-codes), param payment_method. */
+function methodNotAllowed(ctx: SemanticsContext, existing: Row, params: Row): Response | undefined {
+  const types = Array.isArray(params.payment_method_types) ? params.payment_method_types.map(String)
+    : Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types.map(String)
+    : typesGiven(ctx, String(existing.id)) && Array.isArray(existing.payment_method_types) ? (existing.payment_method_types as unknown[]).map(String) : undefined;
+  if (!types) return undefined;
+  const type = methodType(ctx, params.payment_method ?? existing.payment_method);
+  if (!type || types.includes(type)) return undefined;
+  return ctx.refuse({ status: 400, code: 'payment_intent_invalid_parameter', param: 'payment_method', message: `The PaymentMethod provided (${type}) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: ${types.join(', ')}. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "${type}"` });
+}
+
 /** Confirm an intent the confirm machine allows to move: the confirm action, and a create with `confirm=true`. */
 async function confirmIntent(ctx: SemanticsContext, existing: Record<string, unknown>, params: Record<string, unknown>): Promise<Response> {
   const id = String(existing.id);
@@ -187,6 +228,8 @@ async function confirmIntent(ctx: SemanticsContext, existing: Record<string, unk
   // (docs.stripe.com/error-codes)
   const named = typeof params.mandate === 'string' ? params.mandate : typeof existing.mandate === 'string' ? existing.mandate : undefined;
   if (named && ctx.get('mandate', named)?.status !== 'active') return fail(ctx, 'The provided mandate is invalid and can\'t be used for the payment intent.', 400, 'payment_intent_mandate_invalid');
+  const notAllowed = methodNotAllowed(ctx, existing, params);
+  if (notAllowed) return notAllowed;
   // a declining test card leaves the intent needing a payment method, with the error on it and a 402
   const decline = declineFor(finder(ctx), params, existing);
   if (decline) {

package/src/stripe-capabilities.ts

@@ -256,6 +256,22 @@ export const STRIPE_CAPABILITIES: CapabilitySpec[] = [
       return ok(g) && id(g) === id(c) && ok(u) && field(u, 'name') === 'Ada Lovelace' && field(l, 'object') === 'list';
     }),
   ),
+  // stripe-node posts a null metadata value as `metadata[key]=` (Cal.com's PaymentIntent metadata, a guest with no phone)
+  done('stripe.metadata.create_empty_value_unset', 'metadata', 'A create\'s metadata key posted empty is not set (an empty value unsets a key); metadata posted empty is {}', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/customers', b: 'email=sam@twin.test&metadata[identifier]=cal.com&metadata[bookerPhoneNumber]=' });
+      const pi = await h({ m: 'POST', p: '/v1/payment_intents', b: `amount=5000&currency=usd&customer=${id(c)}&metadata[bookingId]=12&metadata[calAccountId]=` });
+      const none = await h({ m: 'POST', p: '/v1/products', b: 'name=Consultation&metadata=' });
+      const got = await h({ m: 'GET', p: `/v1/payment_intents/${id(pi)}` });
+      const md = (r: StripeResponse) => (r.body as Body).metadata as Body;
+      return ok(c) && JSON.stringify(md(c)) === JSON.stringify({ identifier: 'cal.com' })
+        && ok(pi) && JSON.stringify(md(pi)) === JSON.stringify({ bookingId: '12' }) && JSON.stringify(md(got)) === JSON.stringify({ bookingId: '12' })
+        && ok(none) && JSON.stringify(md(none)) === '{}';
+    }),
+  ),
+  // Objects on a connected account are that account's: Stripe answers a retrieve of one without its Stripe-Account
+  // header (or with another account's) 404 resource_missing. The twin keeps one store for the platform and its accounts.
+  todo('stripe.connect.account_scoped_objects', 'connect', 'Objects made with a Stripe-Account header are visible only as that account (retrieve/list/update from the platform or another account is resource_missing)', 'api', 'common'),
   done('stripe.customers.list_filter', 'customers', 'Customer list filter by email', 'api', 'core', () =>
     withRoot(async (h) => {
       await h({ m: 'POST', p: '/v1/customers', b: 'email=match@twin.test' });
@@ -558,6 +574,97 @@ export const STRIPE_CAPABILITIES: CapabilitySpec[] = [
       return field(plain, 'automatic_payment_methods') === null;
     }),
   ),
+  // payment_method_types: a caller pinned before 2026-08-26.preview (stripe-node sends the version it is configured
+  // with; Cal.com's paid booking posts payment_method_types[]=card under 2020-08-27) names the methods and the intent
+  // echoes them; a value naming no payment method type is refused in the intents' words ("The payment method type "…"
+  // is invalid. See … for the full list of supported payment method types.", stripe-node issues/1472). From the removal
+  // on the parameter is gone: "Passing `payment_method_types` now returns a 400 error with the code
+  // `payment_method_types_no_longer_supported`", "at 2026-08-26.preview or later" (docs.stripe.com/changelog/dahlia/
+  // 2026-08-26/removes-payment-method-types-parameter-from-payment-intents-setup-intents), on create, update and confirm.
+  done('stripe.payment_intents.payment_method_types', 'payment_intents', 'PaymentIntent payment_method_types: taken and echoed on create/update for a caller pinned before 2026-08-26.preview (an unknown type refused); refused payment_method_types_no_longer_supported at 2026-08-26.preview or later', 'api', 'core', () =>
+    withRoot(async (h, root) => {
+      const at = (v: string, p: string, b: string) => handleStripeTwinRequest({ method: 'POST', path: p, body: b, apiVersion: v, root });
+      const pinned = (p: string, b: string) => at('2020-08-27', p, b);
+      const pi = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card&metadata[bookingId]=12');
+      const indexed = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[0]=card&payment_method_types[1]=us_bank_account');
+      const updated = await pinned(`/v1/payment_intents/${id(pi)}`, 'payment_method_types[0]=card&payment_method_types[1]=link');
+      const bogus = await pinned('/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[0]=card&payment_method_types[1]=credit_card');
+      const err = (r: StripeResponse) => (r.body as Body).error as Body | undefined;
+      const echoed = ok(pi) && JSON.stringify(field(pi, 'payment_method_types')) === '["card"]' && (field(pi, 'metadata') as Body)?.bookingId === '12'
+        && ok(indexed) && JSON.stringify(field(indexed, 'payment_method_types')) === '["card","us_bank_account"]'
+        && ok(updated) && JSON.stringify(field(updated, 'payment_method_types')) === '["card","link"]';
+      const unknown = bogus.status === 400 && err(bogus)?.param === 'payment_method_types'
+        && err(bogus)?.message === 'The payment method type "credit_card" is invalid. See https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types for the full list of supported payment method types.';
+      // the cut is the removal version, not the served one: a basil/clover pin is taken, a pin at or after the removal refused
+      const clover = await at('2025-09-30.clover', '/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card');
+      const atRemoval = await at('2026-08-26.preview', '/v1/payment_intents', 'amount=5000&currency=usd&payment_method_types[]=card');
+      const afterRemoval = await at('2026-09-15.preview', `/v1/payment_intents/${id(pi)}`, 'payment_method_types[0]=card');
+      const cut = ok(clover) && JSON.stringify(field(clover, 'payment_method_types')) === '["card"]'
+        && [atRemoval, afterRemoval].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported');
+      // the served version: gone from create, update and confirm; allowed_payment_method_types names the methods instead
+      const created = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&payment_method_types[]=card' });
+      const upd = await h({ m: 'POST', p: `/v1/payment_intents/${id(pi)}`, b: 'payment_method_types[0]=card' });
+      const conf = await h({ m: 'POST', p: `/v1/payment_intents/${id(pi)}/confirm`, b: 'payment_method=pm_card_visa&payment_method_types[0]=card' });
+      const gone = [created, upd, conf].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported' && err(r)?.param === 'payment_method_types');
+      const allowed = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&allowed_payment_method_types[0]=card' });
+      return echoed && unknown && cut && gone && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["card"]';
+    }),
+  ),
+  // A confirm with a payment method of a type the intent's caller did not name is refused: "The PaymentMethod provided
+  // (card_present) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types:
+  // card. Alternatively, update the allowed payment_method_types for this PaymentIntent to include "card_present""
+  // (Stripe's answer quoted in github.com/stripe/stripe-terminal-react-native/issues/745). An intent whose caller named
+  // none takes the method (the twin's default list stands for the account's enabled methods).
+  done('stripe.payment_intents.confirm_method_type_refused', 'payment_intents', 'PaymentIntent confirm with a payment method of a type outside the payment_method_types the caller gave on create or update is refused (the intent stays unpaid)', 'api', 'common', () =>
+    withRoot(async (h, root) => {
+      const bank = await h({ m: 'POST', p: '/v1/payment_methods', b: 'type=us_bank_account&us_bank_account[routing_number]=110000000&us_bank_account[account_number]=000123456789&us_bank_account[account_holder_type]=individual&billing_details[name]=Sam' });
+      const cardOnly = await handleStripeTwinRequest({ method: 'POST', path: '/v1/payment_intents', body: 'amount=5000&currency=usd&payment_method_types[]=card', apiVersion: '2020-08-27', root });
+      const refused = await h({ m: 'POST', p: `/v1/payment_intents/${id(cardOnly)}/confirm`, b: `payment_method=${id(bank)}` });
+      const e = (refused.body as Body).error as Body | undefined;
+      const after = await h({ m: 'GET', p: `/v1/payment_intents/${id(cardOnly)}` });
+      const paid = await h({ m: 'POST', p: `/v1/payment_intents/${id(cardOnly)}/confirm`, b: 'payment_method=pm_card_visa' });
+      // allowed_payment_method_types restricts the same way; an intent naming none takes the bank account
+      const allowed = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd&allowed_payment_method_types[0]=card' });
+      const refusedToo = await h({ m: 'POST', p: `/v1/payment_intents/${id(allowed)}/confirm`, b: `payment_method=${id(bank)}` });
+      const open = await h({ m: 'POST', p: '/v1/payment_intents', b: 'amount=5000&currency=usd' });
+      const taken = await h({ m: 'POST', p: `/v1/payment_intents/${id(open)}/confirm`, b: `payment_method=${id(bank)}` });
+      // an update naming the methods restricts as a create's does: made naming none, updated to card, then refused a bank account
+      const later = await handleStripeTwinRequest({ method: 'POST', path: '/v1/payment_intents', body: 'amount=5000&currency=usd', apiVersion: '2020-08-27', root });
+      const narrowed = await handleStripeTwinRequest({ method: 'POST', path: `/v1/payment_intents/${id(later)}`, body: 'payment_method_types[0]=card', apiVersion: '2020-08-27', root });
+      const refusedLater = await h({ m: 'POST', p: `/v1/payment_intents/${id(later)}/confirm`, b: `payment_method=${id(bank)}` });
+      return ok(bank) && ok(cardOnly) && refused.status === 400 && e?.param === 'payment_method'
+        && String(e?.message).startsWith('The PaymentMethod provided (us_bank_account) is not allowed for this PaymentIntent. Please attach a PaymentMethod of one of the following types: card.')
+        && field(after, 'status') === 'requires_payment_method' && field(after, 'payment_method') == null
+        && ok(paid) && field(paid, 'status') === 'succeeded'
+        && refusedToo.status === 400 && ok(taken) && field(taken, 'status') === 'processing'
+        && ok(narrowed) && refusedLater.status === 400 && ((refusedLater.body as Body).error as Body | undefined)?.param === 'payment_method';
+    }),
+  ),
+  // The same parameter on SetupIntents: taken from a caller pinned to an earlier version, gone in the served one, whose
+  // changelog names "the create and update methods on Setup Intents" (payment_method_types_no_longer_supported).
+  done('stripe.setup_intents.payment_method_types', 'payment_methods', 'SetupIntent payment_method_types: taken and echoed for a caller pinned before 2026-08-26.preview (an unknown type refused in Stripe\'s words); refused payment_method_types_no_longer_supported at 2026-08-26.preview or later', 'api', 'common', () =>
+    withRoot(async (h, root) => {
+      const at = (v: string, p: string, b: string) => handleStripeTwinRequest({ method: 'POST', path: p, body: b, apiVersion: v, root });
+      const pinned = (p: string, b: string) => at('2020-08-27', p, b);
+      const si = await pinned('/v1/setup_intents', 'payment_method_types[]=us_bank_account');
+      const bogus = await pinned('/v1/setup_intents', 'payment_method_types[0]=bank');
+      const atRemoval = await at('2026-08-26.preview', '/v1/setup_intents', 'payment_method_types[]=card');
+      const err = (r: StripeResponse) => (r.body as Body).error as Body | undefined;
+      const created = await h({ m: 'POST', p: '/v1/setup_intents', b: 'payment_method_types[]=card' });
+      const upd = await h({ m: 'POST', p: `/v1/setup_intents/${id(si)}`, b: 'payment_method_types[0]=card' });
+      const allowed = await h({ m: 'POST', p: '/v1/setup_intents', b: 'allowed_payment_method_types[]=us_bank_account' });
+      return ok(si) && JSON.stringify(field(si, 'payment_method_types')) === '["us_bank_account"]'
+        && bogus.status === 400 && err(bogus)?.param === 'payment_method_types'
+        && err(bogus)?.message === 'The payment method type "bank" is invalid. See https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types for the full list of supported payment method types.'
+        && [created, upd, atRemoval].every((r) => r.status === 400 && err(r)?.code === 'payment_method_types_no_longer_supported')
+        && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["us_bank_account"]';
+    }),
+  ),
+  // Both ways of choosing methods on one create (payment_method_types with automatic_payment_methods[enabled]=true)
+  // for a caller pinned before the removal: Stripe's documentation states no refusal (docs.stripe.com/api/
+  // payment_intents/create, docs.stripe.com/upgrades/manage-payment-methods, docs.stripe.com/changelog/2023-08-16/
+  // automatic-payment-methods describe each alone), so the twin's answer waits for a captured one.
+  todo('stripe.payment_intents.method_types_with_automatic', 'payment_intents', 'PaymentIntent/SetupIntent create with both payment_method_types and automatic_payment_methods[enabled]=true (pinned before 2026-08-26.preview): Stripe\'s answer (refusal and its words) is undocumented', 'api', 'niche'),
   // PaymentIntent search: GET /v1/payment_intents/search?query=… returns the search_result
   // envelope; supports AND-combined clauses (currency:"usd" AND amount>=num). Missing query 400s.
   done('stripe.payment_intents.search', 'payment_intents', 'PaymentIntent search', 'api', 'common', () =>
@@ -1956,6 +2063,50 @@ export const STRIPE_CAPABILITIES: CapabilitySpec[] = [
         && field(sub, 'current_period_end') === undefined;
     }),
   ),
+  // A session's payment method types: payment_method_types from a caller pinned to an earlier version ("A list of the
+  // types of payment methods (e.g., `card`) this Checkout Session can accept"), allowed_payment_method_types in the served
+  // version, whose spec takes no payment_method_types on a session's create (an unknown parameter there: the changelog's
+  // payment_method_types_no_longer_supported names only the intents). The PaymentIntent paying makes carries the list.
+  done('stripe.checkout.payment_method_types', 'checkout', 'Checkout Session payment_method_types (earlier version) and allowed_payment_method_types (served) name the session\'s methods and its PaymentIntent\'s; an unknown type refused', 'api', 'common', () =>
+    withRoot(async (h, root) => {
+      const line = 'mode=payment&success_url=https://x.test&line_items[0][price_data][currency]=usd&line_items[0][price_data][unit_amount]=5000&line_items[0][price_data][product_data][name]=Consultation&line_items[0][quantity]=1';
+      const pinned = (b: string) => handleStripeTwinRequest({ method: 'POST', path: '/v1/checkout/sessions', body: `${line}&${b}`, apiVersion: '2020-08-27', root });
+      const cs = await pinned('payment_method_types[0]=card&payment_method_types[1]=link');
+      const bogus = await pinned('payment_method_types[0]=cards');
+      // Checkout's own list: a PaymentMethod type it does not take (in person) is refused, and is not in the list offered
+      const inPerson = await pinned('payment_method_types[0]=card&payment_method_types[1]=card_present');
+      const served = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `${line}&payment_method_types[0]=card` });
+      const allowed = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `${line}&allowed_payment_method_types[0]=card` });
+      await h({ m: 'POST', p: `/c/pay/${id(cs)}`, b: 'email=pay%40twin.test&cardNumber=4242424242424242&cardExpiry=12%2F34&cardCvc=123&billingName=Twin&billingCountry=US&billingPostalCode=94105' });
+      const done = await h({ m: 'GET', p: `/v1/checkout/sessions/${id(cs)}` });
+      const pi = await h({ m: 'GET', p: `/v1/payment_intents/${String(field(done, 'payment_intent'))}` });
+      const err = (r: StripeResponse) => (r.body as Body).error as Body | undefined;
+      return ok(cs) && JSON.stringify(field(cs, 'payment_method_types')) === '["card","link"]'
+        && bogus.status === 400 && err(bogus)?.param === 'payment_method_types[0]' && /^Invalid payment_method_types\[0\]: must be one of acss_debit, .*\bcard\b.*, or zip$/.test(String(err(bogus)?.message))
+        && inPerson.status === 400 && err(inPerson)?.param === 'payment_method_types[1]' && !/card_present|interac_present/.test(String(err(inPerson)?.message))
+        && served.status === 400 && err(served)?.code === 'parameter_unknown'
+        && ok(allowed) && JSON.stringify(field(allowed, 'payment_method_types')) === '["card"]' && JSON.stringify(field(allowed, 'allowed_payment_method_types')) === '["card"]'
+        && ok(pi) && JSON.stringify(field(pi, 'payment_method_types')) === '["card","link"]';
+    }),
+  ),
+  // Metadata a session passes on is kept as a create's own: "Individual keys can be unset by posting an empty value to
+  // them. All keys can be unset by posting an empty value to `metadata`" (docs.stripe.com/api/metadata). stripe-node
+  // posts a null as `…[metadata][key]=`; the PaymentIntent and the Subscription paying makes hold no such key.
+  done('stripe.checkout.nested_metadata_empty_unset', 'checkout', 'A session\'s payment_intent_data[metadata] and subscription_data[metadata] keys posted empty are not set on the PaymentIntent / Subscription completion makes; metadata posted empty is {}', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const pay = (cs: StripeResponse) => h({ m: 'POST', p: `/c/pay/${id(cs)}`, b: 'email=pay%40twin.test&cardNumber=4242424242424242&cardExpiry=12%2F34&cardCvc=123&billingName=Twin&billingCountry=US&billingPostalCode=94105' });
+      const cust = await h({ m: 'POST', p: '/v1/customers', b: 'email=md@twin.test' });
+      const item = 'line_items[0][price_data][currency]=usd&line_items[0][price_data][unit_amount]=5000&line_items[0][price_data][product_data][name]=Plan&line_items[0][quantity]=1';
+      const payment = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=payment&success_url=https://x.test&${item}&payment_intent_data[metadata][bookingId]=12&payment_intent_data[metadata][phone]=` });
+      const sub = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=subscription&success_url=https://x.test&customer=${id(cust)}&${item}&line_items[0][price_data][recurring][interval]=month&subscription_data[metadata][teamId]=7&subscription_data[metadata][coupon]=` });
+      const none = await h({ m: 'POST', p: '/v1/checkout/sessions', b: `mode=payment&success_url=https://x.test&${item}&payment_intent_data[metadata]=` });
+      await pay(payment); await pay(sub); await pay(none);
+      const get = async (cs: StripeResponse, kind: 'payment_intents' | 'subscriptions', link: string) => field(await h({ m: 'GET', p: `/v1/${kind}/${String(field(await h({ m: 'GET', p: `/v1/checkout/sessions/${id(cs)}` }), link))}` }), 'metadata');
+      return JSON.stringify(await get(payment, 'payment_intents', 'payment_intent')) === '{"bookingId":"12"}'
+        && JSON.stringify(await get(sub, 'subscriptions', 'subscription')) === '{"teamId":"7"}'
+        && JSON.stringify(await get(none, 'payment_intents', 'payment_intent')) === '{}';
+    }),
+  ),
   // A subscription session's customer pays its first invoice on the page: the invoice is paid through a succeeded
   // PaymentIntent and its charge, and the card is the subscription's default payment method
   // (docs.stripe.com/payments/checkout/how-checkout-works).

package/src/stripe-params.ts

@@ -7,8 +7,8 @@
 // 2025-09-30.clover) was accepted.
 //
 // Where the evidence stops: the check knows only the served version's parameters (the spec's, surface.version). A
-// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec;
-// nested parameters are not checked.
+// request pinning an earlier version with Stripe-Version is not checked, since the pack holds no earlier spec, beyond
+// the values of the payment_method_types it still takes (PAYMENT_METHOD_TYPES below); nested parameters are not checked.
 import { readParams, vendorError, type DerivedCall } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest } from './manifest.ts';
@@ -24,15 +24,87 @@ const DOCUMENTED: Record<string, string[]> = {
   PostTopups: ['destination_balance'],
 };
 
+// PAYMENT_METHOD_TYPES. The operations that took `payment_method_types` until 2026-08-26.preview, which "Removes
+// `payment_method_types` as a writable parameter from the create, update, and confirm methods on Payment Intents, and
+// from the create and update methods on Setup Intents. Passing `payment_method_types` now returns a 400 error with the
+// code `payment_method_types_no_longer_supported`", for a caller "at 2026-08-26.preview or later"
+// (docs.stripe.com/changelog/dahlia/2026-08-26/removes-payment-method-types-parameter-from-payment-intents-setup-
+// intents). The served spec (2026-09-30.endive) has no such parameter on them, nor on a Checkout Session's create,
+// which the changelog does not name: there it is an unknown parameter for a caller on the served version, and taken
+// from any caller pinned before it.
+// A caller pinned before the removal (stripe-node sends the version it is configured with: Cal.com's 2020-08-27)
+// still sends it, "The list of payment method types (e.g. card) that this PaymentIntent is allowed to use. A
+// comprehensive list of valid payment method types can be found here" (the served spec's payment_intent object, the
+// link being the PaymentMethod object's `type`). A PaymentIntent's or SetupIntent's value outside that list is refused
+// as Stripe refuses one there: "The payment method type "us_bank_account" is invalid. See
+// https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types for the full list of
+// supported payment method types." (a real SetupIntent answer quoted in github.com/stripe/stripe-node/issues/1472).
+// A Checkout Session's value outside its own enum is refused as Stripe refuses any value outside a parameter's enum:
+// "Invalid payment_settings[payment_method_types][1]: must be one of ach_credit_transfer, …, or wechat_pay" (a real
+// answer quoted in github.com/stripe/stripe-node/issues/1755), with no code. Where the evidence stops: the message
+// Stripe gives with payment_method_types_no_longer_supported is not documented (the twin's own words below); the
+// PaymentIntent's link is the SetupIntent's with its own resource (no PaymentIntent answer is quoted), and neither
+// answer's param nor code is quoted (the twin gives param payment_method_types, no code); the lists are the served
+// version's, not the pinned one's.
+/** The version that removed payment_method_types from the intents: a caller pinned to it or later is refused. */
+export const METHOD_TYPES_REMOVED_IN = '2026-08-26.preview';
+/** Whether a pinned version is at or after the removal: versions order by their date (YYYY-MM-DD). */
+export const methodTypesRemoved = (pinned: string): boolean => pinned.slice(0, 10) >= METHOD_TYPES_REMOVED_IN.slice(0, 10);
+const REMOVED_TYPES = new Set(['PostPaymentIntents', 'PostPaymentIntentsIntent', 'PostPaymentIntentsIntentConfirm', 'PostSetupIntents', 'PostSetupIntentsIntent']);
+const TYPED = new Set([...REMOVED_TYPES, 'PostCheckoutSessions']);
+type Resource = { name: string; fields: Array<{ name: string; enum?: string[] }> };
+/** The payment method types there are: the PaymentMethod object's `type` in the served spec. */
+export const PAYMENT_METHOD_TYPES: readonly string[] = (surface.resources as Resource[]).find((r) => r.name === 'payment_method')?.fields.find((f) => f.name === 'type')?.enum ?? [];
+/** The payment method types a Checkout Session takes: the vendored spec's (2026-09-30.endive) PostCheckoutSessions
+ *  allowed_payment_method_types item enum, the parameter described as payment_method_types is ("A list of the types of
+ *  payment methods (e.g., `card`) this Checkout Session can accept"). It holds no in-person type (card_present,
+ *  interac_present) and no `custom`. The surface keeps no request enums, so it is copied here. */
+export const CHECKOUT_METHOD_TYPES: readonly string[] = ['acss_debit', 'affirm', 'afterpay_clearpay', 'alipay', 'alma', 'amazon_pay', 'au_becs_debit', 'bacs_debit', 'bancontact', 'billie', 'bizum', 'blik', 'boleto', 'card', 'cashapp', 'crypto', 'customer_balance', 'eps', 'fpx', 'giropay', 'grabpay', 'ideal', 'kakao_pay', 'klarna', 'konbini', 'kr_card', 'link', 'mb_way', 'mobilepay', 'multibanco', 'naver_pay', 'nz_bank_account', 'oxxo', 'p24', 'pay_by_bank', 'payco', 'paynow', 'paypal', 'paypay', 'payto', 'pix', 'promptpay', 'revolut_pay', 'samsung_pay', 'satispay', 'scalapay', 'sepa_debit', 'sequra', 'sofort', 'sunbit', 'swish', 'twint', 'upi', 'us_bank_account', 'wechat_pay', 'zip'];
+/** The create page each intent's refusal links to. */
+const TYPES_DOC: Record<string, string> = {
+  payment_intents: 'https://stripe.com/docs/api/payment_intents/create#create_payment_intent-payment_method_types',
+  setup_intents: 'https://stripe.com/docs/api/setup_intents/create#create_setup_intent-payment_method_types',
+};
+
+/** An enum's values as Stripe lists them in a refusal: "a, b, or c". */
+const oneOf = (values: readonly string[]): string => (values.length > 1 ? `${values.slice(0, -1).join(', ')}, or ${values.at(-1)}` : values.join(''));
+
+/** An earlier version's payment_method_types refused: the first value that names no payment method type the
+ *  operation takes, in the intent's words or (a Checkout Session) the enum's. */
+function unknownMethodType(opId: string, given: unknown): Response | undefined {
+  const values = Array.isArray(given) ? given : given && typeof given === 'object' ? Object.values(given) : [given];
+  const checkout = opId === 'PostCheckoutSessions';
+  const known = checkout ? CHECKOUT_METHOD_TYPES : PAYMENT_METHOD_TYPES;
+  const i = values.findIndex((v) => !known.includes(String(v)));
+  if (i < 0) return undefined;
+  if (checkout) {
+    const param = `payment_method_types[${i}]`;
+    return vendorError(manifest, { status: 400, param, message: `Invalid ${param}: must be one of ${oneOf(known)}` });
+  }
+  const doc = TYPES_DOC[opId.startsWith('PostSetupIntents') ? 'setup_intents' : 'payment_intents'];
+  return vendorError(manifest, { status: 400, param: 'payment_method_types', message: `The payment method type "${String(values[i])}" is invalid. See ${doc} for the full list of supported payment method types.` });
+}
+
+/** payment_method_types refused where the caller's version removed it. */
+const noLongerSupported = (version: string): Response =>
+  vendorError(manifest, { status: 400, code: 'payment_method_types_no_longer_supported', param: 'payment_method_types', message: `payment_method_types is no longer supported in API version ${version}. Use allowed_payment_method_types, or dynamic payment methods, instead.` });
+
 /** Stripe's refusal of a request whose top-level parameters the operation does not take, or undefined. */
 export async function refuseParameters(call: DerivedCall): Promise<Response | undefined> {
   const op = OPS.get(call.operation.id);
   if (!op) return undefined;
   const pinned = call.request.headers.get('stripe-version');
-  if (pinned && pinned < SERVED_VERSION) return undefined;
+  if (pinned && pinned < SERVED_VERSION) {
+    if (!TYPED.has(op.id)) return undefined;
+    const earlier = await readParams(manifest, call.request.clone(), call.operation);
+    if (earlier.payment_method_types === undefined) return undefined;
+    if (REMOVED_TYPES.has(op.id) && methodTypesRemoved(pinned)) return noLongerSupported(pinned);
+    return unknownMethodType(op.id, earlier.payment_method_types);
+  }
   const method = call.request.method.toUpperCase();
   const known = new Set([...(op.query ?? []), ...(op.body ?? [])].map((p) => p.name).concat(DOCUMENTED[op.id] ?? []));
   const params = await readParams(manifest, call.request.clone(), call.operation);
+  if (REMOVED_TYPES.has(op.id) && params.payment_method_types !== undefined) return noLongerSupported(pinned ?? SERVED_VERSION);
   for (const name of Object.keys(params)) {
     if (!known.has(name)) return vendorError(manifest, { status: 400, code: 'parameter_unknown', param: name, message: `Received unknown parameter: ${name}` });
   }

package/src/stripe-server.ts

@@ -327,6 +327,31 @@ export async function createStripeTwinServer(options: StripeTwinOptions): Promis
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }
 
+/** A create's `metadata` holds no key posted empty. "Individual keys can be unset by posting an empty value to them. All
+ *  keys can be unset by posting an empty value to `metadata`" (every metadata parameter of docs.stripe.com/api): an empty
+ *  value is the absence of the key, on a create as on an update, so an object never holds a key set to "". Clients post
+ *  one without meaning to: stripe-node encodes a `null` value as `metadata[key]=` (Cal.com's PaymentIntent metadata
+ *  carries `bookerPhoneNumber: null` for a guest who gave no phone). The request is rewritten as JSON without them. */
+async function createMetadata(request: Request, path: string): Promise<Request> {
+  const op = CREATES.find((c) => c.re.test(path))?.op;
+  if (!op) return request;
+  const params = await readParams(manifest, request.clone(), op);
+  if (!('metadata' in params)) return request;
+  const given = params.metadata;
+  let metadata: Record<string, unknown>;
+  if (given === '') metadata = {};
+  else if (given && typeof given === 'object' && !Array.isArray(given) && Object.values(given).includes('')) {
+    metadata = Object.fromEntries(Object.entries(given as Record<string, unknown>).filter(([, v]) => v !== ''));
+  } else return request;
+  const headers = new Headers(request.headers);
+  headers.set('content-type', 'application/json');
+  return new Request(request.url, { method: request.method, headers, body: JSON.stringify({ ...params, metadata }) });
+}
+
+// the create operations, by their path as a pattern, for createMetadata
+const CREATES = (surface.operations as Array<DerivedCall['operation']>).filter((o) => o.class === 'create' && o.method.toUpperCase() === 'POST')
+  .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
+
 // the update operations, by their path as a pattern, for mergeMetadata
 const UPDATES = (surface.operations as Array<DerivedCall['operation']>).filter((o) => o.class === 'update' && o.method.toUpperCase() === 'POST')
   .map((op) => ({ op, re: new RegExp(`^${op.path.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\\{[^}]+\\\}|\{[^}]+\}/g, '([^/]+)')}/?$`) }));
@@ -345,7 +370,8 @@ async function mergeMetadata(request: Request, coreMerges: (op: DerivedCall['ope
   let op: DerivedCall['operation'] | undefined;
   let id = '';
   for (const u of UPDATES) { const m = u.re.exec(path); if (m) { op = u.op; id = decodeURIComponent(m.at(-1) ?? ''); break; } }
-  if (!op?.resource) return request;
+  if (!op) return createMetadata(request, path);
+  if (!op.resource) return request;
   const params = await readParams(manifest, request.clone(), op);
   if (!('metadata' in params)) return request;
   const given = params.metadata;