@volter/twin-stripe 0.1.2 → 2.0.1

package/src/semantics/payment-intents.ts

@@ -0,0 +1,420 @@
+// PaymentIntent semantics. The machine in ../manifest.ts says which moves of `status` are legal and
+// what Stripe answers otherwise; these handlers compute what each move does. List, retrieve and
+// update are the derived core's; search is Stripe's query language over the intents.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  asBool,
+  cardError,
+  chargeDefaults,
+  declineFor,
+  microdepositsNextAction,
+  mintClientSecret,
+  requiresAuthentication,
+  requiresMicrodeposits,
+  threeDsNextAction,
+  validateMoney,
+  verifyMicrodeposits,
+  type StripeResponse,
+} from '../stripe-twin.ts';
+import { afterCharge, mintMandate } from './after-payment.ts';
+import { cancelAuthorization, captureAuthorization } from './charges.ts';
+import { settleCharge } from './ledger.ts';
+import { materializeTestMethod, methodFromData, microdepositsAsked, paymentMethodDetails } from './payment-methods.ts';
+import { at_, confirmOnly, created, fail, finder, search, type Row } from './shared.ts';
+
+const PI = 'payment_intent';
+
+const send = (ctx: SemanticsContext, r: StripeResponse): Response => ctx.reply(r.body, r.status);
+
+// ── THE MONEY MODEL, continued: a succeeded intent has a Charge ──
+//
+// Real Stripe always materializes a Charge when a PaymentIntent succeeds and points the intent's
+// `latest_charge` at it: the charge is what a refund lands on, so an intent that succeeds without
+// one cannot answer "refund this payment" at all. Idempotent against a repeated confirm: an intent
+// that already names a successful charge keeps it (a second one would double the money collected); a
+// declined attempt's failed charge is history, and the payment that succeeds makes its own. The id is
+// returned so the caller folds `latest_charge` into the same intent write (one write, one event). The
+// charge is written as the event Stripe sends for it, `charge.succeeded` ("Occurs whenever a charge is
+// successful", docs.stripe.com/api/events/types); Stripe has no `charge.created`.
+/** What every charge an intent makes carries of it: its transfer_group, which "identifies the resulting payment as part
+ *  of a group" (docs.stripe.com/api/payment_intents/object), its description and its metadata. */
+function intentCarries(pi: Row): Row {
+  return {
+    ...(typeof pi.transfer_group === 'string' ? { transfer_group: pi.transfer_group } : {}),
+    ...(typeof pi.description === 'string' ? { description: pi.description } : {}),
+    // "When a PaymentIntent creates a Charge, the metadata copies to the Charge in a one-time snapshot"
+    // (docs.stripe.com/metadata, "Copy metadata to another object")
+    ...(pi.metadata && typeof pi.metadata === 'object' ? { metadata: { ...(pi.metadata as Row) } } : {}),
+  };
+}
+
+export async function mintCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string> {
+  const already = ctx.get(PI, piId)?.latest_charge;
+  if (typeof already === 'string' && ctx.get('charge', already)?.status === 'succeeded') return already;
+  const chargeId = ctx.mint('charge');
+  const bt = await settleCharge(ctx, chargeId, amount, String(pi.currency ?? 'usd'), typeof pi.payment_method === 'string' ? pi.payment_method : undefined);
+  await created(ctx, 'charge', {
+    id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+    ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+    ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+    ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+    ...intentCarries(pi),
+  }, { ...chargeDefaults(chargeId, amount, true, ctx.occurredAt), balance_transaction: bt, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+  await afterCharge(ctx, chargeId, { amount, currency: String(pi.currency ?? 'usd'), payment_intent: piId, application_fee_amount: pi.application_fee_amount, destination: (pi.transfer_data as Row | undefined)?.destination }, pi.payment_method);
+  return chargeId;
+}
+
+/** A manual-capture intent's authorization: "Separate payment authorization and capture to create a charge now, but
+ *  capture funds later", and on capture "A partial capture automatically releases the remaining amount"
+ *  (docs.stripe.com/payments/place-a-hold-on-a-payment-method). The charge succeeded and is not captured, holding the
+ *  amount until capture_before, with nothing on the balance yet. Written as
+ *  charge.succeeded, as a charge made with capture=false is (charges.ts); its capture writes charge.captured
+ *  (captureAuthorization). Where the documentation stops and the twin decides: the events page names no event for an
+ *  authorization of its own, so the authorized charge sends charge.succeeded, its status being succeeded. */
+export async function authorizeCharge(ctx: SemanticsContext, piId: string, pi: Row, amount: number): Promise<string> {
+  const chargeId = ctx.mint('charge');
+  await created(ctx, 'charge', {
+    id: chargeId, amount, currency: pi.currency ?? 'usd', payment_intent: piId,
+    ...(typeof pi.customer === 'string' ? { customer: pi.customer } : {}),
+    ...(typeof pi.payment_method === 'string' ? { payment_method: pi.payment_method } : {}),
+    ...(typeof pi.invoice === 'string' ? { invoice: pi.invoice } : {}),
+    ...intentCarries(pi),
+  }, { ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), balance_transaction: null, payment_method_details: paymentMethodDetails(ctx, pi.payment_method) ?? null }, { operation: 'charge.succeeded' });
+  return chargeId;
+}
+
+/**
+ * An intent an invoice collects through succeeded (the default_incomplete subscription flow: create
+ * now, confirm client-side): its invoice is paid and, when it is a subscription's first, the
+ * subscription leaves incomplete for active. Both are moves the invoice and subscription machines
+ * declare under the confirming operation. No-op when the intent names no invoice, or the invoice is
+ * already paid (a duplicate confirm) or void (voiding ends what it collects).
+ */
+async function payInvoiceOf(ctx: SemanticsContext, pi: Row, operationId: string, actor?: 'vendor'): Promise<void> {
+  const invoiceId = typeof pi.invoice === 'string' ? pi.invoice : undefined;
+  const invoice = invoiceId ? ctx.get('invoice', invoiceId) : undefined;
+  if (!invoiceId || !invoice || invoice.status === 'paid' || invoice.status === 'void') return;
+  if (ctx.legal('invoice', 'status', operationId, invoice.status, 'paid', invoiceId, actor)) return;
+  const amount = Number(invoice.total ?? invoice.amount_due) || 0;
+  // `invoice.pay` is the event the standalone pay action sends: invoice.paid
+  await ctx.write('invoice', invoiceId, {
+    status: 'paid', paid: true, amount_paid: amount, amount_remaining: 0,
+    status_transitions: { ...((invoice.status_transitions as object) ?? {}), paid_at: ctx.now() },
+  }, 'invoice.pay');
+  const subId = typeof invoice.subscription === 'string' ? invoice.subscription : undefined;
+  const sub = subId ? ctx.get('subscription', subId) : undefined;
+  if (subId && sub && sub.status === 'incomplete' && !ctx.legal('subscription', 'status', operationId, sub.status, 'active', subId, actor)) {
+    await ctx.write('subscription', subId, { status: 'active' }, 'subscription.update');
+  }
+}
+
+/** The intent the path names, and the machine's refusal when this operation may not move it. */
+function load(ctx: SemanticsContext, operationId: string): { pi: Record<string, unknown> } | { answer: Response } {
+  const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
+  if (!pi) return { answer: ctx.notFound(PI, String(ctx.id)) };
+  const refusal = ctx.legal(PI, 'status', operationId, pi.status);
+  return refusal ? { answer: ctx.refuse(refusal) } : { pi };
+}
+
+const create: Semantics = async (ctx) => {
+  const params = ctx.params;
+  const bad = validateMoney(params);
+  if (bad) return send(ctx, bad);
+  // what describes a confirmation needs one: error_on_requires_action, mandate, mandate_data, off_session and return_url
+  // are each, in the served spec, a parameter that "can only be used with `confirm=true`" (shared.ts confirmOnly)
+  const unconfirmed = confirmOnly(ctx, ['error_on_requires_action', 'mandate', 'mandate_data', 'off_session', 'return_url'], asBool(params.confirm));
+  if (unconfirmed) return unconfirmed;
+  // automatic_payment_methods: when enabled, Stripe selects eligible methods and answers the
+  // normalized { enabled, allow_redirects } object
+  const apmIn = params.automatic_payment_methods;
+  const apmEnabled = apmIn && typeof apmIn === 'object' ? asBool((apmIn as Record<string, unknown>).enabled) : false;
+  const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: ((apmIn as Record<string, unknown>).allow_redirects as string) ?? 'always' } : null;
+  // the methods it may be paid with: allowed_payment_method_types in the served version, payment_method_types for a
+  // caller pinned to an earlier one (docs.stripe.com/api/payment_intents/create)
+  const given = Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types : params.payment_method_types;
+  const payment_method_types = Array.isArray(given) ? given.map(String) : ['card'];
+  // `confirm` is an instruction, not a field: `confirm=true` attempts to confirm the intent at once
+  // (https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm)
+  const { automatic_payment_methods: _a, payment_method_types: _p, allowed_payment_method_types: _ap, id: provided, expand: _e, confirm: confirmNow, payment_method_data: data, mandate_data: _mandate, ...rest } = params;
+  // a create's payment_method_data makes its method, as a confirm's does (payment-methods.ts methodFromData)
+  const made = await methodFromData(ctx, data);
+  if (made) rest.payment_method = made;
+  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
+  const id = typeof provided === 'string' && provided ? provided : ctx.mint(PI);
+  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
+  const hasMethod = typeof rest.payment_method === 'string' && rest.payment_method !== '';
+  if (hasMethod) ctx.legal(PI, 'status', 'PostPaymentIntents', 'requires_payment_method', 'requires_confirmation', id);
+  const body = await ctx.write(
+    PI,
+    id,
+    {
+      object: 'payment_intent',
+      created: ctx.now(),
+      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method',
+      client_secret: mintClientSecret(id),
+      livemode: false,
+      capture_method: 'automatic',
+      amount_capturable: 0,
+      amount_received: 0,
+      next_action: null,
+      automatic_payment_methods,
+      payment_method_types,
+      ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
+      payment_method_options: (params.payment_method_options as object) ?? {},
+      ...rest,
+    },
+    'payment_intent.create',
+  );
+  if (asBool(confirmNow)) return confirmIntent(ctx, body, {});
+  return ctx.reply(ctx.expand(PI, body));
+};
+
+const confirm: Semantics = async (ctx) => {
+  const loaded = load(ctx, 'PostPaymentIntentsIntentConfirm');
+  if ('answer' in loaded) return loaded.answer;
+  const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = ctx.params;
+  // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
+  const made = await methodFromData(ctx, data);
+  return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
+};
+
+/** 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);
+  // a payment names a mandate only an active one authorizes: an inactive mandate "was rejected, revoked, or previously
+  // used, and may not be used to initiate future payments" (docs.stripe.com/api/mandates/object), refused as
+  // payment_intent_mandate_invalid, "The provided mandate is invalid and can't be used for the payment intent"
+  // (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');
+  // 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) {
+    // Stripe records the attempt: a failed charge the intent's latest_charge names, the declined card on
+    // last_payment_error (a test name made a real PaymentMethod), and no payment_method left on the intent
+    // (docs.stripe.com/payments/paymentintents/lifecycle, docs.stripe.com/declines)
+    const ref = params.payment_method ?? existing.payment_method;
+    let pmId = typeof ref === 'string' ? ref : undefined;
+    if (pmId && !ctx.get('payment_method', pmId) && pmId.startsWith('pm_card_')) pmId = String((await materializeTestMethod(ctx, pmId, typeof existing.customer === 'string' ? existing.customer : null)).id);
+    const pm = pmId ? ctx.get('payment_method', pmId) : undefined;
+    const amount = Number(params.amount ?? existing.amount) || 0;
+    const chargeId = ctx.mint('charge');
+    await created(ctx, 'charge', {
+      id: chargeId, amount, currency: existing.currency ?? 'usd', payment_intent: id,
+      ...(typeof existing.customer === 'string' ? { customer: existing.customer } : {}),
+      ...(pmId ? { payment_method: pmId } : {}),
+      ...intentCarries({ ...existing, ...params }),
+    }, {
+      ...chargeDefaults(chargeId, amount, false, ctx.occurredAt), status: 'failed', paid: false, captured: false, capture_before: null,
+      failure_code: decline.code, failure_message: decline.message, balance_transaction: null,
+      outcome: { type: 'issuer_declined', network_status: 'declined_by_network', reason: decline.decline_code ?? decline.code, risk_level: 'normal', seller_message: 'The bank did not return any further details with this decline.' },
+      payment_method_details: pmId ? paymentMethodDetails(ctx, pmId) ?? null : null,
+    }, { operation: 'charge.failed' }); // "Occurs whenever a failed charge attempt occurs." (docs.stripe.com/api/events/types)
+    const { payment_method: _pm, ...rest } = params;
+    const last_payment_error = { type: 'card_error', code: decline.code, ...(decline.decline_code ? { decline_code: decline.decline_code } : {}), message: decline.message, param: 'card', charge: chargeId, payment_method: pm ?? null };
+    const failed = await ctx.write(PI, id, { ...rest, payment_method: null, latest_charge: chargeId, status: 'requires_payment_method', last_payment_error }, 'payment_intent.payment_failed');
+    return send(ctx, cardError(decline, { payment_intent: failed, charge: chargeId }));
+  }
+  // a bank debit that needs micro-deposit verification waits in requires_action
+  const method = typeof params.payment_method === 'string' ? params.payment_method : typeof existing.payment_method === 'string' ? existing.payment_method : undefined;
+  // a bank transfer is paid from the customer's cash balance, or waits for the transfer (fundFromCashBalance)
+  if (method && ctx.get('payment_method', method)?.type === 'customer_balance') return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, { ...existing, ...params }, params)));
+  if (requiresMicrodeposits(params, existing) || microdepositsAsked(ctx, params, existing, method)) {
+    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: microdepositsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+  }
+  // 3DS: the first confirm asks for authentication; a second one completes it
+  if (existing.status !== 'requires_action' && requiresAuthentication(params, existing)) {
+    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_action', next_action: threeDsNextAction(), last_payment_error: null }, 'payment_intent.requires_action')));
+  }
+  // manual capture authorizes and waits for /capture: the authorization is a charge, succeeded and not captured, the
+  // intent's latest_charge
+  if ((params.capture_method ?? existing.capture_method) === 'manual') {
+    const amount = Number(existing.amount ?? params.amount ?? 0);
+    const charge = await authorizeCharge(ctx, id, { ...existing, ...params }, amount);
+    return ctx.reply(ctx.expand(PI, await ctx.write(PI, id, { ...params, status: 'requires_capture', amount_capturable: amount, amount_received: 0, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.amount_capturable_updated')));
+  }
+  // a bank debit is submitted and settles later (beginBankDebit)
+  if (isBankDebit(ctx, method)) return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, id, params)));
+  const amount = Number(existing.amount ?? params.amount ?? 0);
+  // a succeeded intent has a Charge, and latest_charge names it: what a refund of it lands on
+  const charge = await mintCharge(ctx, id, { ...existing, ...params }, amount);
+  const body = await ctx.write(PI, id, { ...params, status: 'succeeded', amount_received: amount, next_action: null, last_payment_error: null, latest_charge: charge }, 'payment_intent.confirm');
+  await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentConfirm');
+  return ctx.reply(ctx.expand(PI, body));
+}
+
+const capture: Semantics = async (ctx) => {
+  const loaded = load(ctx, 'PostPaymentIntentsIntentCapture');
+  if ('answer' in loaded) return loaded.answer;
+  const pi = loaded.pi;
+  const authorized = Number(pi.amount_capturable ?? pi.amount ?? 0);
+  // amount_to_capture lowers the captured amount (a partial capture); it never raises it
+  const asked = ctx.params.amount_to_capture !== undefined ? Math.max(0, Math.trunc(Number(ctx.params.amount_to_capture) || 0)) : authorized;
+  const captured = Math.min(asked, authorized);
+  // the authorization confirm made is captured; an intent authorized before it was kept is charged as before
+  const auth = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
+  const held = auth && auth.status === 'succeeded' && auth.captured === false ? auth : undefined;
+  if (held) {
+    const refused = ctx.legal('charge', 'captured', 'PostPaymentIntentsIntentCapture', 'false', 'true', String(held.id));
+    if (refused) return ctx.refuse(refused);
+    await captureAuthorization(ctx, held, captured, 'PostPaymentIntentsIntentCapture');
+    await afterCharge(ctx, String(held.id), { amount: captured, currency: String(pi.currency ?? 'usd'), payment_intent: String(pi.id), application_fee_amount: pi.application_fee_amount, destination: (pi.transfer_data as Row | undefined)?.destination }, pi.payment_method);
+  }
+  const charge = held ? String(held.id) : await mintCharge(ctx, String(pi.id), pi, captured);
+  const body = await ctx.write(PI, String(pi.id), { status: 'succeeded', amount_received: captured, amount_capturable: 0, latest_charge: charge }, 'payment_intent.succeeded');
+  await payInvoiceOf(ctx, body, 'PostPaymentIntentsIntentCapture');
+  return ctx.reply(ctx.expand(PI, body));
+};
+
+/** An increment that does not raise the authorization. */
+function incrementTooSmall(ctx: SemanticsContext): Response {
+  return ctx.refuse({ status: 400, code: 'parameter_invalid_integer', message: 'The new amount must be greater than the current amount of the PaymentIntent.' });
+}
+
+const incrementAuthorization: Semantics = async (ctx) => {
+  const loaded = load(ctx, 'PostPaymentIntentsIntentIncrementAuthorization');
+  if ('answer' in loaded) return loaded.answer;
+  const pi = loaded.pi;
+  if (ctx.params.amount === undefined) return ctx.refuse({ status: 400, code: 'parameter_missing', message: 'Missing required param: amount.' });
+  const amount = Math.trunc(Number(ctx.params.amount) || 0);
+  if (!Number.isInteger(amount) || amount <= Number(pi.amount ?? 0)) return incrementTooSmall(ctx);
+  // the authorization the charge holds grows with it: "If the incremental authorization fails ... no other fields on
+  // the PaymentIntent or Charge update" (docs.stripe.com/api/payment_intents/increment_authorization), so on success the
+  // charge's amount is the new authorized amount. Where the documentation stops and the twin decides: the charge's
+  // update sends no event of its own (the events page names none for it).
+  const held = typeof pi.latest_charge === 'string' ? ctx.get('charge', pi.latest_charge) : undefined;
+  if (held && held.captured === false) await ctx.write('charge', String(held.id), { amount }, 'charge.authorization_incremented');
+  return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(pi.id), { amount, amount_capturable: amount }, 'payment_intent.amount_capturable_updated')));
+};
+
+const cancel: Semantics = async (ctx) => {
+  const loaded = load(ctx, 'PostPaymentIntentsIntentCancel');
+  if ('answer' in loaded) return loaded.answer;
+  const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'requested_by_customer';
+  // "For PaymentIntents with a `status` of `requires_capture`, the remaining `amount_capturable` is automatically
+  // refunded" (docs.stripe.com/api/payment_intents/cancel): the authorization is released (charges.ts)
+  const held = loaded.pi.status === 'requires_capture' && typeof loaded.pi.latest_charge === 'string' ? ctx.get('charge', loaded.pi.latest_charge) : undefined;
+  if (held && held.captured === false && held.refunded !== true) await cancelAuthorization(ctx, held);
+  return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
+};
+
+const verifyMicrodepositsHandler: Semantics = async (ctx) => {
+  const pi = ctx.id ? ctx.get(PI, ctx.id) : undefined;
+  if (!pi) return ctx.notFound(PI, String(ctx.id));
+  // the deposit amounts are checked before the intent's state, as Stripe does
+  const wrong = verifyMicrodeposits(ctx.params, pi);
+  if (wrong) return send(ctx, wrong);
+  const refusal = ctx.legal(PI, 'status', 'PostPaymentIntentsIntentVerifyMicrodeposits', pi.status);
+  if (refusal) return ctx.refuse(refusal);
+  const amount = Number(pi.amount) || 0;
+  // a debit saved for reuse ("If you want to reuse the payment method in the future, provide the setup_future_usage
+  // parameter with the value of off_session", the ACH page) is authorized for many payments (multi_use, "Represents
+  // permission given for multiple payments"); else for this one (single_use, "a one-time permission given for a single
+  // payment", docs.stripe.com/api/mandates/object)
+  const reuse = pi.setup_future_usage === 'off_session' || pi.setup_future_usage === 'on_session';
+  const mandate = reuse ? await mintMandate(ctx, pi.payment_method, 'multi_use') : await mintMandate(ctx, pi.payment_method, 'single_use', amount, String(pi.currency ?? 'usd'));
+  // "When the bank account is successfully verified, Stripe returns the PaymentIntent object with a status of
+  // `processing`" (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api)
+  return ctx.reply(ctx.expand(PI, await beginBankDebit(ctx, String(pi.id), { mandate })));
+};
+
+// ── a bank debit is submitted, and settles ──
+//
+// ACH Direct Debit "is a delayed notification payment method ... The PaymentIntent you create initially has a status
+// of `processing`. After the payment has succeeded, the PaymentIntent status is updated from `processing` to
+// `succeeded`"; verification by micro-deposits returns "a status of `processing`, and sends a payment_intent.processing
+// webhook event"; and, the twin being a test-mode account: "Test transactions settle instantly and are added to your
+// available test balance. This behavior differs from live mode, where transactions can take multiple days to settle"
+// (docs.stripe.com/payments/ach-direct-debit/accept-a-payment?payment-ui=direct-api). A confirm answers processing; the
+// debit succeeds at that same instant of the World's clock, caught up before the next request is answered (as
+// renewals and payouts are). The page's test accounts give each debit its outcome: pm_usBankAccount_success
+// (000123456789) "The payment succeeds"; pm_usBankAccount_processing (000000000009) "The payment stays in processing
+// indefinitely". Where the documentation stops and the twin decides: its Charge is made when it succeeds (the page
+// names none while it processes); the failing test accounts (closed, no account, insufficient funds, debit not
+// authorized, invalid currency, dispute, weekly limit, Radar block) are not modelled and succeed.
+
+/** Whether the method an intent is confirmed with is a bank debit: a us_bank_account PaymentMethod, or one of Stripe's
+ *  test bank accounts named as one (pm_usBankAccount_*, pm_us_bank_account). */
+export function isBankDebit(ctx: SemanticsContext, method: unknown): boolean {
+  if (typeof method !== 'string') return false;
+  return ctx.get('payment_method', method)?.type === 'us_bank_account' || /^pm_us_?bank_?account/i.test(method);
+}
+
+/** Whether a bank debit stays processing: the page's pm_usBankAccount_processing, or its account 000000000009. */
+function staysProcessing(ctx: SemanticsContext, method: unknown): boolean {
+  if (method === 'pm_usBankAccount_processing') return true;
+  const bank = typeof method === 'string' ? (ctx.get('payment_method', method)?.us_bank_account as Row | undefined) : undefined;
+  return bank?.last4 === '0009';
+}
+
+/** A bank debit submitted: the intent processes, nothing received yet, sent as payment_intent.processing; it is due to
+ *  settle at this instant, unless its test account stays processing. */
+async function beginBankDebit(ctx: SemanticsContext, id: string, fields: Row): Promise<Row> {
+  const method = fields.payment_method ?? ctx.get(PI, id)?.payment_method;
+  return ctx.write(PI, id, { ...fields, status: 'processing', amount_received: 0, next_action: null, last_payment_error: null, _settles_at: staysProcessing(ctx, method) ? null : Number(ctx.now()) }, 'payment_intent.processing');
+}
+
+/** Time's settling of bank debits, caught up to the World's clock: each processing debit whose moment has come succeeds
+ *  then, its Charge made (naming the mandate it ran under) and the invoice it collects for paid. */
+export async function settleBankDebits(ctx: SemanticsContext): Promise<void> {
+  const now = Number(ctx.now());
+  const due = ctx.rowsRaw(PI).filter((p) => p.status === 'processing' && typeof p._settles_at === 'number' && p._settles_at <= now).sort((a, b) => Number(a._settles_at) - Number(b._settles_at));
+  for (const pi of due) {
+    const id = String(pi.id);
+    const c = await at_(ctx)(Number(pi._settles_at));
+    c.legal(PI, 'status', ctx.call.operation.id, 'processing', 'succeeded', id, 'vendor');
+    const amount = Number(pi.amount) || 0;
+    const charge = await mintCharge(c, id, pi, amount);
+    // the charge names the mandate its bank debit ran under (payment_method_details.us_bank_account.mandate)
+    const details = (c.get('charge', charge)?.payment_method_details ?? null) as Row | null;
+    const kind = typeof details?.type === 'string' ? details.type : undefined;
+    if (details && kind && typeof pi.mandate === 'string') await c.write('charge', charge, { payment_method_details: { ...details, [kind]: { ...((details[kind] as Row | undefined) ?? {}), mandate: pi.mandate } } }, 'charge.mandate');
+    const body = await c.write(PI, id, { status: 'succeeded', amount_received: amount, latest_charge: charge, _settles_at: null }, 'payment_intent.succeeded');
+    // a single-use mandate is spent by its payment: "previously used, and may not be used to initiate future payments"
+    const used = typeof pi.mandate === 'string' ? c.get('mandate', pi.mandate) : undefined;
+    if (used && used.type === 'single_use' && used.status === 'active') {
+      c.legal('mandate', 'status', ctx.call.operation.id, 'active', 'inactive', String(used.id), 'vendor');
+      await c.write('mandate', String(used.id), { status: 'inactive' }, 'mandate.updated');
+    }
+    await payInvoiceOf(c, body, ctx.call.operation.id, 'vendor');
+  }
+}
+
+/** A customer_balance intent funded from the customer's cash balance: paid when the balance covers it ("If the customer
+ *  already has a balance high enough to cover the payment amount, the PaymentIntent immediately succeeds"), else
+ *  waiting for a transfer: "If the customer balance isn’t high enough to cover the request amount, the PaymentIntent
+ *  shows a requires_action status ... next_action ... display_bank_transfer_instructions" with the amount_remaining
+ *  (docs.stripe.com/payments/bank-transfers/accept-a-payment). Answers the intent as written. */
+async function fundFromCashBalance(ctx: SemanticsContext, pi: Row, fields: Row = {}): Promise<Row> {
+  const customer = typeof pi.customer === 'string' ? pi.customer : '';
+  const currency = String(pi.currency ?? 'usd');
+  // what the customer's funded cash balance holds in this currency, from its ledger
+  const available = customer ? ctx.rows('customer_cash_balance_transaction').filter((t) => t.customer === customer && String(t.currency) === currency).reduce((n, t) => n + (Number(t.net_amount) || 0), 0) : 0;
+  const amount = Number(pi.amount) || 0;
+  if (available >= amount) {
+    // the balance pays the intent: its ledger records what was applied
+    await created(ctx, 'customer_cash_balance_transaction', { customer }, { currency, type: 'applied_to_payment', net_amount: -amount, ending_balance: available - amount, applied_to_payment: { payment_intent: String(pi.id) }, livemode: false });
+    const charge = await mintCharge(ctx, String(pi.id), { ...pi, ...fields }, amount);
+    return ctx.write(PI, String(pi.id), { ...fields, status: 'succeeded', next_action: null, amount_received: amount, last_payment_error: null, latest_charge: charge }, 'payment_intent.succeeded');
+  }
+  // not enough yet: the intent waits for the rest, with the instructions to send it
+  const next_action = { type: 'display_bank_transfer_instructions', display_bank_transfer_instructions: { amount_remaining: amount - available, currency, type: 'us_bank_transfer' } };
+  return ctx.write(PI, String(pi.id), { ...fields, status: 'requires_action', next_action }, 'payment_intent.requires_action');
+}
+
+const applyCustomerBalance: Semantics = async (ctx) => {
+  const loaded = load(ctx, 'PostPaymentIntentsIntentApplyCustomerBalance');
+  if ('answer' in loaded) return loaded.answer;
+  return ctx.reply(ctx.expand(PI, await fundFromCashBalance(ctx, loaded.pi)));
+};
+
+export const paymentIntents: Record<string, Semantics> = {
+  PostPaymentIntents: create,
+  GetPaymentIntentsSearch: async (ctx) => search(ctx, PI),
+  PostPaymentIntentsIntentConfirm: confirm,
+  PostPaymentIntentsIntentCapture: capture,
+  PostPaymentIntentsIntentIncrementAuthorization: incrementAuthorization,
+  PostPaymentIntentsIntentCancel: cancel,
+  PostPaymentIntentsIntentVerifyMicrodeposits: verifyMicrodepositsHandler,
+  PostPaymentIntentsIntentApplyCustomerBalance: applyCustomerBalance,
+};

package/src/semantics/payment-links.ts

@@ -0,0 +1,148 @@
+// Payment Link and Quote semantics. Both carry line items resolved from existing prices. A payment
+// link is a reusable hosted-checkout URL, active until switched off; a quote moves draft → open
+// (finalize) → accepted or canceled, the machine in ../manifest.ts. Link retrieve and update
+// (`active`, its machine), quote retrieve and the quote list are the derived core's.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { asBool, lineItemEntries, paginate, resolveLineItem, type CheckoutItem } from '../stripe-twin.ts';
+import { draftInvoiceFor } from './invoices.ts';
+import { at, created, fail, finder, list, newest, path, where, type Row } from './shared.ts';
+
+/** The request's line items resolved against their prices, or the refusal for a missing price. */
+function resolved(ctx: SemanticsContext): CheckoutItem[] | Response {
+  const entries = lineItemEntries(ctx.params);
+  const items: CheckoutItem[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const { item, priceMissing } = resolveLineItem(entries[i]!, i, 'usd', finder(ctx));
+    if (priceMissing) return fail(ctx, `No such price: '${priceMissing}'`, 400, 'resource_missing');
+    items.push(item);
+  }
+  return items;
+}
+
+/** A page of the line items a stored object carries. */
+function linePage(ctx: SemanticsContext, holder: Row): Response {
+  const li = holder.line_items as { data?: Row[] } | undefined;
+  const { page, hasMore } = paginate(Array.isArray(li?.data) ? li!.data! : [], ctx.params);
+  return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
+}
+
+const PL = 'payment_link';
+const linkMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such payment link: '${id}'`, 404, 'resource_missing');
+
+const createLink: Semantics = async (ctx) => {
+  if (lineItemEntries(ctx.params).length === 0) return fail(ctx, 'Missing required param: line_items.', 400, 'parameter_missing');
+  const items = resolved(ctx);
+  if (items instanceof Response) return items;
+  const id = ctx.mint(PL);
+  const { line_items: _li, ...rest } = ctx.params;
+  return ctx.reply(
+    await created(ctx, PL, { ...rest, id }, {
+      active: ctx.params.active !== undefined ? asBool(ctx.params.active) : true,
+      url: `https://buy.twin.local/${id}`, livemode: false, metadata: {},
+      // Stripe's defaults for what the link was not given (docs.stripe.com/api/payment-link/create)
+      allow_promotion_codes: false, automatic_tax: { enabled: false, liability: null }, billing_address_collection: 'auto',
+      custom_fields: [], custom_text: { after_submit: null, shipping_address: null, submit: null, terms_of_service_acceptance: null },
+      customer_creation: 'if_required', payment_method_collection: 'always', phone_number_collection: { enabled: false },
+      shipping_options: [], submit_type: 'auto', tax_id_collection: { enabled: false, required: 'never' },
+      line_items: { object: 'list', data: items, has_more: false, url: `/v1/payment_links/${id}/line_items` },
+      currency: items[0]?.currency ?? 'usd',
+      after_completion: { type: 'redirect', redirect: typeof ctx.params.after_completion === 'object' ? ctx.params.after_completion : null },
+    }),
+  );
+};
+
+const listLinks: Semantics = async (ctx) => list(ctx, PL, where(ctx, newest(ctx, PL), { active: (p, v) => asBool(p.active) === asBool(v) }));
+
+const linkLines: Semantics = async (ctx) => {
+  const p = ctx.get(PL, at(ctx, 'payment_link'));
+  return p ? linePage(ctx, p) : linkMissing(ctx, at(ctx, 'payment_link'));
+};
+
+// ── quotes ──
+
+const quoteMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such quote: '${id}'`, 404, 'resource_missing');
+
+const createQuote: Semantics = async (ctx) => {
+  const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+  if (!ctx.row('customer', customer, { withDeleted: true })) return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
+  const items = resolved(ctx);
+  if (items instanceof Response) return items;
+  const subtotal = items.reduce((s, it) => s + it.amount_subtotal, 0);
+  const id = ctx.mint('quote');
+  const { line_items: _li, ...rest } = ctx.params;
+  return ctx.reply(
+    await created(ctx, 'quote', { ...rest, id }, {
+      status: 'draft', customer, currency: items[0]?.currency ?? 'usd', livemode: false, metadata: {},
+      amount_subtotal: subtotal, amount_total: subtotal,
+      // Stripe's defaults (docs.stripe.com/api/quotes/create); what is paid up front is the whole quote, and the twin bills in classic mode
+      automatic_tax: { enabled: false, liability: null, provider: null, status: null }, collection_method: 'charge_automatically', discounts: [],
+      invoice_settings: { days_until_due: null, issuer: { type: 'self' } },
+      subscription_data: { billing_mode: { type: 'classic' }, description: null, effective_date: null, metadata: null, trial_period_days: null },
+      computed: { recurring: null, upfront: { amount_subtotal: subtotal, amount_total: subtotal, total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 } } },
+      line_items: { object: 'list', data: items, has_more: false, url: `/v1/quotes/${id}/line_items` },
+      total_details: { amount_discount: 0, amount_shipping: 0, amount_tax: 0 },
+      expires_at: Number(ctx.now()) + 30 * 24 * 3600,
+      number: null, invoice: null, subscription: null,
+      status_transitions: { accepted_at: null, canceled_at: null, finalized_at: null },
+    }),
+  );
+};
+
+const quoteLines: Semantics = async (ctx) => {
+  const q = ctx.get('quote', at(ctx, 'quote'));
+  return q ? linePage(ctx, q) : quoteMissing(ctx, at(ctx, 'quote'));
+};
+
+// Stripe streams the PDF; the twin answers a stable reference to it
+const pdf: Semantics = async (ctx) => {
+  const id = at(ctx, 'quote');
+  if (!ctx.get('quote', id)) return quoteMissing(ctx, id);
+  return ctx.reply({ object: 'quote_pdf', url: `https://files.twin.local/quotes/${id}.pdf` });
+};
+
+function move(action: 'finalize' | 'accept' | 'cancel', operationId: string): Semantics {
+  return async (ctx) => {
+    const id = at(ctx, 'quote');
+    const q = ctx.get('quote', id);
+    if (!q) return quoteMissing(ctx, id);
+    const refused = ctx.legal('quote', 'status', operationId, q.status, undefined, id);
+    if (refused) return ctx.refuse(refused);
+    const now = ctx.now();
+    const stamp = action === 'finalize' ? { finalized_at: now } : action === 'accept' ? { accepted_at: now } : { canceled_at: now };
+    // "Accepted quotes automatically generate an invoice, subscription, or subscription schedule"; "Quotes without
+    // recurring prices: A draft invoice is created with auto_advance set to false" (docs.stripe.com/quotes/overview),
+    // the quote its parent ("Details about the quote that generated this invoice", the served spec). Where the
+    // documentation stops and the twin decides: a quote with recurring prices makes no subscription yet.
+    let made: Row = {};
+    if (action === 'accept') {
+      const lines = ((q.line_items as Row | undefined)?.data as Row[] | undefined) ?? [];
+      const recurring = lines.some((l) => l.price && typeof l.price === 'object' && (l.price as Row).recurring);
+      if (!recurring && typeof q.customer === 'string') {
+        const invoice = await draftInvoiceFor(ctx, q.customer, String(q.currency ?? 'usd'), { type: 'quote_details', quote_details: { quote: id }, subscription_details: null }, lines.map((l) => ({ price: l.price, quantity: Number(l.quantity) || 1, amount: Number(l.amount_subtotal ?? l.amount_total) || 0, description: l.description })));
+        made = { invoice };
+      }
+    }
+    return ctx.reply(
+      await ctx.write('quote', id, {
+        status: action === 'finalize' ? 'open' : action === 'accept' ? 'accepted' : 'canceled',
+        status_transitions: { ...((q.status_transitions as Row) ?? {}), ...stamp },
+        ...(action === 'finalize' ? { number: `QT-${id.toUpperCase()}` } : {}),
+        ...made,
+      }, `quote.${action}`),
+    );
+  };
+}
+
+export const paymentLinks: Record<string, Semantics> = {
+  PostPaymentLinks: createLink,
+  GetPaymentLinks: listLinks,
+  GetPaymentLinksPaymentLinkLineItems: linkLines,
+  PostQuotes: createQuote,
+  GetQuotesQuoteLineItems: quoteLines,
+  GetQuotesQuoteComputedUpfrontLineItems: quoteLines,
+  GetQuotesQuotePdf: pdf,
+  PostQuotesQuoteFinalize: move('finalize', 'PostQuotesQuoteFinalize'),
+  PostQuotesQuoteAccept: move('accept', 'PostQuotesQuoteAccept'),
+  PostQuotesQuoteCancel: move('cancel', 'PostQuotesQuoteCancel'),
+};