@volter/twin-stripe 3.0.2 → 3.0.4

package/README.md

@@ -5,20 +5,24 @@ application sends a person through, and Stripe.js, over one state.
 
 ## Use with an existing app
 
+Use Node 22.6 or newer.
+
 In an app that already uses this vendor, install this exact release and the product CLI:
 
 ```console
-npm install --save-dev --save-exact @volter/world@3.0.68 @volter/twin-stripe@3.0.2
-npx volter world init --name my-app --twins stripe --source stripe=@volter/twin-stripe
+npm install --save-dev --save-exact @volter/world@3.0.147 @volter/twin-stripe@3.0.4
+./node_modules/.bin/volter world init --name my-app --twins stripe --source stripe=@volter/twin-stripe
 ```
 
+Run the local executable from this app’s folder; if it is missing, complete the installation here before continuing.
+
 Review the detected vendor and generated bindings before booting. Read the credential names and limitations below; the World supplies throwaway credentials. Then run your app's own command through the World:
 
 ```console
-npx volter world up
-npx volter world run -- npm test
-npx volter world log
-npx volter world down
+./node_modules/.bin/volter world up
+./node_modules/.bin/volter world run -- npm test
+./node_modules/.bin/volter world log
+./node_modules/.bin/volter world down
 ```
 
 Here `npm test` is your app's existing command; replace it with your app or test command. `down` retains state.
@@ -47,9 +51,10 @@ vendor-backed World's refresh; each served operation is decided in `journeys/dec
 - **Catalog**: products and prices created and listed, prices retrieved, coupons and promotion codes managed. Product search and administrative product/price updates answer the gap.
 - **Checkout Sessions** and the customer portal (sessions and configurations): pay, add a card, pay an open invoice,
   cancel at the period's end or at once.
-- **Subscriptions**: created (charged at once, trialing, `default_incomplete` or `error_if_incomplete`), updated (items,
-  discounts, a trial ended early or added), searched, canceled; their items, schedules (made, updated, released),
-  renewals on the World clock, and a renewal declined and paid later.
+- **Subscriptions**: created by hosted Checkout (including trials), read, updated (items, discounts, a trial
+  ended early or added) and canceled, with renewals on the World clock. Direct `POST /v1/subscriptions` is outside
+  the declared application demand and returns the gap; use the release operation table to check other subscription
+  and schedule endpoints before choosing this twin.
 - **Invoices**: invoice items, drafts, finalize, pay (a draft is finalized on the way), void, delete, lines,
   previews and their payments. Invoice lines are read in the invoice; the standalone lines endpoint answers the gap.
 - **Intents**: payment and setup intents, confirmed on the server or by Stripe.js with the publishable key and the
@@ -98,30 +103,22 @@ SDK's `constructEvent` verifies) and delivers to the account's enabled webhook e
   (`STRIPE_CONNECT_WEBHOOK_SECRET`), the same on every boot; an endpoint made on the Webhooks page (a door) is signed
   with the one of its kind. The twin reads no env.
 
+The documented card-brand samples keep their brand and credit/debit/prepaid funding type when saved
+through Checkout or the portal. Other raw numbers retain synthetic Visa metadata; the twin does not
+look up a real card issuer.
+
 ## Screens
 
-Stripe's own pages, at their vendor urls (`src/screens/`):
-
-- **Checkout** (`checkout.stripe.com/c/pay/{session}`): the customer pays; the session completes and
-  `checkout.session.completed` fires.
-- **Customer portal** (`billing.stripe.com/p/session/{session}`): cancel or renew a plan, update the card, pay an
-  open invoice.
-- **Connect onboarding** (`connect.stripe.com/setup/…`): an Account Link's hosted onboarding.
-- **Connect OAuth** (`connect.stripe.com/oauth/authorize`, `/oauth/token`, `/oauth/deauthorize`; Standard accounts,
-  docs.stripe.com/connect/oauth-reference). The platform's client_id is `ca_twin_self` in every World (a test
-  client_id; the platform account is `acct_twin_self`), shown on the Dashboard's Connect OAuth settings page in
-  `<code data-testid="connect-client-id">`. OAuth starts off: a runner POSTs that page as a browser does,
-  `oauth_enabled=on&redirect_uris=<one per line>`. The authorize page offers the test-mode **Skip this form** (a new
-  Standard account, connected) and **Deny access**; the token endpoint exchanges a code once, within 5 minutes (a
-  reused code revokes the connection), and refreshes to an equal or lesser scope; after a deauthorization the
-  account's `Stripe-Account` header is refused 403 `account_invalid`. The deprecated `access_token` and
-  `stripe_publishable_key` act as the connected account. Not modelled: connecting an existing Stripe account, the full
-  account application, holding a `read_only` connection to reads.
-- **Stripe.js** (`js.stripe.com/v3/`, `/v3/stripe.js`, `/<release train>/stripe.js`): `redirectToCheckout({ sessionId })`
-  goes to the hosted Checkout page; any other member
-  throws, naming itself.
-- **Dashboard** (`dashboard.stripe.com/settings/public`, `/settings/connect/onboarding-options/oauth`): Public details
-  (the business name Checkout and the portal show) and the Connect OAuth settings.
+Authored pages and content at the declared vendor URLs (`src/screens/`):
+
+- **Checkout** (`checkout.stripe.com/c/pay/{session}`): payment, setup and subscription sessions, including trials.
+- **Customer portal** (`billing.stripe.com/p/session/{session}`): cancel or renew a plan, update the card and pay an open invoice.
+- **Connect onboarding** (`connect.stripe.com/setup/…`): the Account Link's business, identity, payout and agreement form.
+- **Stripe.js** (`js.stripe.com/v3/`, `/v3/stripe.js`, `/<release train>/stripe.js`): `redirectToCheckout({ sessionId })` opens the hosted session. Unsupported members refuse.
+- **Checkout client wire** (`api.stripe.com/v1/payment_pages/{session}`): the authored session operations used by Stripe.js CheckoutProvider.
+- **Dashboard** (`dashboard.stripe.com/customers`, `/customers/{customer}`, `/settings/public`, `/radar/lists`, `/test/issuing/balance`): inspect SDK-created customers and their stored subscriptions, payments, payment methods, invoices and metadata; set the public business name, create Radar lists and fund test Issuing. The workspace opens Public details; choose Customers in its sidebar to inspect a record. Customer pages are read-only. Search matches name, email, id or description; dates are UTC. Dashboard customer creation/editing, exports, guest-customer grouping and global search are unavailable.
+
+Page actions use the same stored resources as the API. Public screen references and authored choices are in [spec/SOURCE.md](./spec/SOURCE.md).
 
 ## Doors
 

package/dist/journeys/customer-life.json

@@ -646,6 +646,51 @@
       ],
       "evidence": "Dub: apps/web/app/api/workspaces/[idOrSlug]/billing/payment-methods/route.ts:66"
     },
+    {
+      "name": "Femke finds the SDK-created customer in the Dashboard",
+      "method": "GET",
+      "path": "https://dashboard.stripe.com/customers?q=billing%40ravel.test",
+      "status": 200,
+      "expect": [
+        {
+          "path": "",
+          "contains": "billing@ravel.test"
+        },
+        {
+          "path": "",
+          "contains": "/customers/{ravel}"
+        }
+      ],
+      "evidence": "World first-use customer inspection; https://support.stripe.com/questions/export-customer-data-without-the-payment-details"
+    },
+    {
+      "name": "Femke opens Ravel's stored customer profile",
+      "method": "GET",
+      "path": "https://dashboard.stripe.com/customers/{ravel}",
+      "status": 200,
+      "expect": [
+        {
+          "path": "",
+          "contains": "billing@ravel.test"
+        },
+        {
+          "path": "",
+          "contains": "Subscriptions"
+        },
+        {
+          "path": "",
+          "contains": "Metadata"
+        }
+      ],
+      "evidence": "World first-use customer inspection; https://support.stripe.com/questions/updates-to-the-customer-detail-page"
+    },
+    {
+      "name": "A missing customer profile stays missing",
+      "method": "GET",
+      "path": "https://dashboard.stripe.com/customers/cus_missing",
+      "status": 404,
+      "evidence": "The Dashboard reads an existing customer only"
+    },
     {
       "name": "Twenty\u2019s app health check reads its Stripe account with the user-supplied key",
       "method": "GET",
@@ -2183,7 +2228,11 @@
       "expect": [
         {
           "path": "",
-          "contains": "Radar Lists"
+          "contains": "Payments / Radar"
+        },
+        {
+          "path": "",
+          "contains": "New list"
         }
       ],
       "evidence": "Stripe: https://docs.stripe.com/radar/lists"
@@ -2690,7 +2739,11 @@
       "expect": [
         {
           "path": "",
-          "contains": "Test Issuing balance"
+          "contains": "Issuing balance"
+        },
+        {
+          "path": "",
+          "contains": "Add test funds before creating test Issuing transactions."
         }
       ],
       "evidence": "Stripe: https://docs.stripe.com/issuing/testing"

package/dist/journeys/customer-life.outline.md

@@ -55,6 +55,9 @@ Elapsed: 120m.
 - and every customer — GET /v1/customers?limit=100. Volter Harness: container/retake/stack/app/src/app.py:116
 - The sample shop's seeder looks its first customer up by email before seeding — GET /v1/customers?email=billing%40ravel.test. Twin: apps/platform/src/sample.ts:40
 - Dub reads Ravel’s billing customer — GET /v1/customers/{ravel}. Dub: apps/web/app/api/workspaces/[idOrSlug]/billing/payment-methods/route.ts:66
+- Femke opens Customers to inspect the SDK-created billing customer — GET https://dashboard.stripe.com/customers?q=billing%40ravel.test. World first-use customer inspection; Stripe: https://support.stripe.com/questions/export-customer-data-without-the-payment-details
+- Femke opens Ravel's profile and sees the stored subscriptions and billing details — GET https://dashboard.stripe.com/customers/{ravel}. World first-use customer inspection; Stripe: https://support.stripe.com/questions/updates-to-the-customer-detail-page
+- A missing customer profile is not an invented customer — GET https://dashboard.stripe.com/customers/cus_missing. The profile reads the existing customer view only.
 - Twenty’s app health check reads its Stripe account with the user-supplied key — GET /v1/account. Twenty: packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx:850 (GET, Authorization only)
 - Twenty’s invoice workflow creates the quote invoice for Ravel — POST /v1/invoices. Twenty: packages/twenty-docs/user-guide/workflows/how-tos/connect-to-other-tools/generate-quote-or-invoice-from-twenty.mdx:101; packages/twenty-server/src/modules/workflow/workflow-executor/workflow-actions/http-request/http-request.workflow-action.ts:28
 - The invoice workflow reads the saved draft — GET /v1/invoices/{workflow_invoice}. Postiz: libraries/nestjs-libraries/src/services/stripe.service.ts; Stripe: pinned API and Stripe.js Checkout contract

package/dist/journeys/decisions.json

@@ -1,5 +1,5 @@
 {
-  "about": "Stripe operations served for the application calls at the cited lines in demand.json and for the resource refresh reads declared in src/manifest.ts. All other operations answer the gap. Each decision names its caller or refresh and its implementation.",
+  "about": "Stripe operations served for the application calls at the cited lines in demand.json and for the resource refresh reads declared in src/manifest.ts. The Dashboard customer pages read those same resource views, as declared in src/manifest.ts and customer-life.outline.md. All other operations answer the gap. Each decision names its caller or refresh and its implementation.",
   "decisions": [
     {
       "operation": "DeleteAccountsAccount",

package/dist/journeys/demand.json

@@ -1,5 +1,5 @@
 {
-  "measured": "Applications are read at the scanned commits below. Demand includes SDK methods, delegated Stripe.js calls, raw URLs and API-path strings, and shipped guides that use a shipped feature. Credentials authorize a feature; they do not opt into it. Postiz ships Stripe as its web billing provider. Twenty workflow HTTP actions and enterprise website billing are independent of the server billing flag (which defaults false). Cal payment/OAuth needs an app-store install; its metadata installed flag makes the catalog entry available, while the user install requires a credential created by the install callback. All products in generated/DEMAND.md’s Volter column were searched, including their own World scenarios and seeds; none calls a removed operation. The launch does not name Stripe. Separately invoked Rallly billing CLI and Dub maintenance scripts are outside the running products. Dub’s raw GET /v1/mandates, POST /v1/fx_quotes and v2 calls remain outside the pinned v1 document and answer the vendor gap; their demand is retained, not classified optional.",
+  "measured": "Applications are read at the scanned commits below. Demand includes SDK methods, delegated Stripe.js calls, raw URLs and API-path strings, and shipped guides that use a shipped feature. Credentials authorize a feature; they do not opt into it. Postiz ships Stripe as its web billing provider. Twenty workflow HTTP actions and enterprise website billing are independent of the server billing flag (which defaults false). Cal payment/OAuth needs an app-store install; its metadata installed flag makes the catalog entry available, while the user install requires a credential created by the install callback. All products in generated/DEMAND.md\u2019s Volter column were searched, including their own World scenarios and seeds; none calls a removed operation. The launch does not name Stripe. Separately invoked Rallly billing CLI and Dub maintenance scripts are outside the running products. Dub\u2019s raw GET /v1/mandates, POST /v1/fx_quotes and v2 calls remain outside the pinned v1 document and answer the vendor gap; their demand is retained, not classified optional.",
   "applications": [
     {
       "name": "Open Autonomy",
@@ -65,7 +65,7 @@
       "client": "fetch (the platform's sample World seeder)",
       "backend": [
         {
-          "call": "call('stripe', '/v1/customers?email=…')",
+          "call": "call('stripe', '/v1/customers?email=\u2026')",
           "operation": "GetCustomers",
           "evidence": "apps/platform/src/sample.ts:40"
         },
@@ -687,6 +687,18 @@
         }
       ],
       "gate": "The shipped website enterprise checkout directly uses Stripe independently of the server IS_BILLING_ENABLED=false switch (packages/twenty-website/src/app/api/enterprise/checkout/route.ts:7-19,51)."
+    },
+    {
+      "name": "World first-use",
+      "commit": "7638d09b23a3bb36067a607e0fd19898b0a5b624",
+      "client": "Real Stripe SDK customer workflow and normal browser inspection",
+      "frontend": [
+        {
+          "call": "Customers sidebar \u2192 SDK-created customer profile",
+          "operation": "GET https://dashboard.stripe.com/customers; GET https://dashboard.stripe.com/customers/{customer}",
+          "evidence": "twin-world/docs/contributing/first-use.md:39; twin-world/docs/getting-started.md:158"
+        }
+      ]
     }
   ],
   "optional": [

package/dist/spec/SOURCE.md

@@ -8,6 +8,15 @@
 
 The pack serves this document's version (`SERVED_VERSION` in `src/engine/version.ts`).
 
+Customer Dashboard references, read 2026-10-09: [Export customer data](https://support.stripe.com/questions/export-customer-data-without-the-payment-details)
+establishes the Customers section at `/customers`. [Updates to the Customer details page](https://support.stripe.com/questions/updates-to-the-customer-detail-page)
+establishes dynamic payments, invoices and subscriptions in the primary column, with details and metadata on the right.
+[Manage customer information](https://support.stripe.com/questions/manage-a-customer-s-information-and-payments)
+names the customer profile and payment-method modules; its older left-details layout is superseded by the update article.
+The pages publish no version date. The authored list and read-only detail use stored API views, UTC dates and an explicitly
+limited name/email/id/description search. Dashboard create/edit actions, exports and guest-customer grouping are outside this scope.
+Only public documentation was read; no vendor sign-in, upstream DOM, script or image is shipped.
+
 - **Published examples:** `fixtures3.json.gz`, gzip of Stripe's `openapi/fixtures3.json` (one sample object per resource,
   the objects Stripe's API reference shows), from commit `0d98342fc985dc7710a44be25e8528dd8e099bc2` (2026-09-23).
   SHA-256 of the uncompressed file: `e6822f7ee6fd71bdde6228537368aafcfb7191109340fe119d9aca27c6e9396d`.
@@ -16,3 +25,7 @@ The pack serves this document's version (`SERVED_VERSION` in `src/engine/version
   publish (its testing page's cards, the payment lifecycle's states, each reference page's stated rule), each with its
   page's URL and the page's words for what it does, read with twin-standard's `read-page`. **Read by:**
   `bun scripts/vendor-examples.ts stripe`.
+
+Screen references, read 2026-10-08: [Stripe's hosted-onboarding guide](https://docs.stripe.com/connect/hosted-onboarding), its hosted_onboarding_form.e59ba8300f563e43489953f06127f52c.png image, supplies the two-column layout, progress and sequential form. The image's example platform branding is configurable; this screen retains the Stripe skin. Back/Continue keep local form answers; only the existing final submit changes the connected account. The existing US requirements and refusal behavior remain the contract. No upstream page, image or script is shipped.
+
+Dashboard references, read 2026-10-08: [the Web Dashboard guide](https://docs.stripe.com/dashboard/basics) supplies the primary sidebar categories, Shortcuts and Settings. The public [Stripe Apps testing guide](https://docs.stripe.com/stripe-apps/test-app), image `test-app-uninstall.710b89177767cff3a7f53de749558d88.png`, illustrates the earlier horizontal navigation, settings breadcrumbs, form density and type; its publication date is unspecified, and it is not a current Public details screenshot. The authored shell follows the current documented sidebar, while the controls remain the existing public business name, Radar list creation and test Issuing funding. The declared root opens Public details; other Dashboard products are unavailable, and there are no invented analytics. [Radar Lists](https://docs.stripe.com/radar/lists) supplies New, name, alias, type and Add. No upstream image, DOM, script or account sign-in is shipped.

package/dist/spec/sources.json

@@ -302,5 +302,13 @@
     "quotes": {
       "Unrecognized request URL (GET: /v1/test).": true
     }
+  },
+  "https://support.stripe.com/questions/export-customer-data-without-the-payment-details": {
+    "status": 200,
+    "checked": "2026-10-09"
+  },
+  "https://support.stripe.com/questions/updates-to-the-customer-detail-page": {
+    "status": 200,
+    "checked": "2026-10-09"
   }
 }

package/dist/src/engine/stripe.js

@@ -672,6 +672,27 @@ export function disputeEvidence() {
     };
 }
 const subParams = (params, k) => (params[k] && typeof params[k] === 'object' ? params[k] : {});
+// source: https://docs.stripe.com/testing
+// The documented brand cards keep their brand and funding type when Checkout or the portal saves them.
+// Where the documentation stops and the twin decides: other numbers retain the existing synthetic Visa default.
+const TEST_CARD_PROFILES = {
+    '4000056655665556': { brand: 'visa', funding: 'debit' },
+    '5555555555554444': { brand: 'mastercard', funding: 'credit' },
+    '2223003122003222': { brand: 'mastercard', funding: 'credit' },
+    '5200828282828210': { brand: 'mastercard', funding: 'debit' },
+    '5105105105105100': { brand: 'mastercard', funding: 'prepaid' },
+    '378282246310005': { brand: 'amex', funding: 'credit' },
+    '371449635398431': { brand: 'amex', funding: 'credit' },
+    '6011111111111117': { brand: 'discover', funding: 'credit' },
+    '6011000990139424': { brand: 'discover', funding: 'credit' },
+    '6011981111111113': { brand: 'discover', funding: 'debit' },
+    '3056930009020004': { brand: 'diners', funding: 'credit' },
+    '36227206271667': { brand: 'diners', funding: 'credit' },
+    '3566002020360505': { brand: 'jcb', funding: 'credit' },
+    '6200000000000005': { brand: 'unionpay', funding: 'credit' },
+    '6200000000000047': { brand: 'unionpay', funding: 'debit' },
+    '6205500000000000004': { brand: 'unionpay', funding: 'credit' },
+};
 /** A card's own sub-object, from the number and expiry given. */
 function cardSubObject(params) {
     const c = subParams(params, 'card');
@@ -680,15 +701,16 @@ function cardSubObject(params) {
     // produces its real last4 instead of silently falling back to the '4242' default.
     const number = typeof c.number === 'string' ? c.number.replace(/\D/g, '')
         : typeof c.number === 'number' ? String(c.number).replace(/\D/g, '') : '';
+    const profile = TEST_CARD_PROFILES[number] ?? { brand: 'visa', funding: 'credit' };
     return { card: {
-            brand: 'visa', last4: number ? number.slice(-4) : '4242',
+            brand: profile.brand, last4: number ? number.slice(-4) : '4242',
             exp_month: Number(c.exp_month) || 12, exp_year: Number(c.exp_year) || 2034,
-            funding: 'credit', country: 'US',
+            funding: profile.funding, country: 'US',
             // source: spec:/components/schemas/payment_method_card/properties/fingerprint/description "Uniquely identifies this particular card number."
             // The synthetic fingerprint is stable for a number; Stripe's opaque fingerprint algorithm is not published.
             fingerprint: digest('sha256', number || '4242424242424242').slice(0, 16),
             checks: { address_line1_check: null, address_postal_code_check: null, cvc_check: 'pass' },
-            networks: { available: ['visa'], preferred: null },
+            networks: { available: [profile.brand], preferred: null },
             three_d_secure_usage: { supported: true }, wallet: null,
         } };
 }

package/dist/src/manifest.js

@@ -359,7 +359,7 @@ export const manifest = {
         hosts: [
             { host: 'api.stripe.com' }, { host: 'checkout.stripe.com', pathPattern: '^/c/pay/' }, { host: 'billing.stripe.com', pathPattern: '^/p/session/' },
             { host: 'connect.stripe.com', pathPattern: '^/setup/' },
-            { host: 'dashboard.stripe.com', pathPattern: '^/radar/lists(?:/[^/]+)?/?$|^/test/issuing/balance/?$|^/settings/public/?$' },
+            { host: 'dashboard.stripe.com', pathPattern: '^/customers(?:/[^/]+)?/?$|^/radar/lists(?:/[^/]+)?/?$|^/test/issuing/balance/?$|^/settings/public/?$' },
             { host: 'verify.stripe.com', pathPattern: '^/start/' },
             { host: 'js.stripe.com', pathPattern: '^/v3/?$|^/(v3|[a-z]+)/stripe\\.js$' },
         ],
@@ -405,8 +405,8 @@ export const manifest = {
         },
         {
             id: 'dashboard', kind: 'workspace', host: 'dashboard.stripe.com', path: '/', status: 'done',
-            demand: 'Operator setup for the cited application calls: Public details; Radar lists for Dub add-to-stripe-fraud-value-lists.ts:3-7; sandbox funding for Open Autonomy world/model/scenario.ts:60,62',
-            controls: ['Business name', 'Save', 'New list', 'Name', 'Alias', 'List type', 'Add', 'Add test funds', 'Amount'], source: 'https://docs.stripe.com/dashboard/basics',
+            demand: 'World first-use customer inspection (twin-world/docs/contributing/first-use.md); operator setup: Public details; Radar lists for Dub add-to-stripe-fraud-value-lists.ts:3-7; sandbox funding for Open Autonomy world/model/scenario.ts:60,62',
+            controls: ['Customers', 'Search customers', 'Search', 'Business name', 'Save', 'New list', 'Name', 'Alias', 'List type', 'Add', 'Add test funds', 'Amount'], source: 'https://docs.stripe.com/dashboard/basics',
         },
     ],
     resources: {

package/dist/src/screens/billing-portal.js

@@ -56,8 +56,8 @@ function page(ctx, id, session, problem) {
             badge: s.status === 'trialing' ? 'Trial' : s.status === 'past_due' ? 'Past due' : ending ? 'Cancels' : undefined,
             note: ending ? `Your plan will be canceled on ${day(s.current_period_end)}.` : s.status === 'trialing' ? `Trial ends ${day(s.trial_end)}.` : `Renews on ${day(s.current_period_end)}.`,
             actions: ending
-                ? [{ label: 'Renew plan', action: `/p/session/${id}/renew`, fields: { subscription: String(s.id) }, tone: 'primary' }]
-                : features.cancel.enabled ? [{ label: 'Cancel plan', action: `/p/session/${id}/cancel`, fields: { subscription: String(s.id) }, tone: 'danger' }] : [],
+                ? [{ label: 'Renew plan', action: `${ctx.publicBase}/p/session/${id}/renew`, fields: { subscription: String(s.id) }, tone: 'primary' }]
+                : features.cancel.enabled ? [{ label: 'Cancel plan', action: `${ctx.publicBase}/p/session/${id}/cancel`, fields: { subscription: String(s.id) }, tone: 'danger' }] : [],
         };
     });
     const defaultPm = customer.invoice_settings?.default_payment_method ?? undefined;
@@ -72,7 +72,7 @@ function page(ctx, id, session, problem) {
         ? ctx.rows('invoice').filter((i) => i.customer === session.customer && i.status !== 'draft').sort((a, b) => Number(b.created) - Number(a.created))
             .map((i) => ({
             title: day(i.created), detail: money(i.amount_due ?? i.total, i.currency), badge: String(i.status ?? '').replace(/^./, (c) => c.toUpperCase()),
-            ...(i.status === 'open' && i.collection_method !== 'send_invoice' ? { actions: [{ label: 'Pay', action: `/p/session/${id}/pay`, fields: { invoice: String(i.id) }, tone: 'primary' }] } : {}),
+            ...(i.status === 'open' && i.collection_method !== 'send_invoice' ? { actions: [{ label: 'Pay', action: `${ctx.publicBase}/p/session/${id}/pay`, fields: { invoice: String(i.id) }, tone: 'primary' }] } : {}),
         }))
         : [];
     const back = typeof session.return_url === 'string' ? session.return_url : undefined;
@@ -95,7 +95,7 @@ function page(ctx, id, session, problem) {
         title: 'Billing',
         css: [PORTAL_CSS, SKIN],
         ...(problem ? { status: 402 } : {}),
-        body: (_jsx(Portal, { merchant: merchant, ...(problem ? { notice: problem.error } : {}), ...(features.paymentMethod ? { forms: [{ heading: pm ? 'Update payment method' : 'Add payment method', action: `/p/session/${id}/payment_method`, fields: cardFields, submit: { label: pm ? 'Update' : 'Add' } }] } : {}), ...(back ? { back: { href: back, label: `← Return to ${merchant}` } } : {}), sections: [
+        body: (_jsx(Portal, { merchant: merchant, ...(problem ? { notice: problem.error } : {}), ...(features.paymentMethod ? { forms: [{ heading: pm ? 'Update payment method' : 'Add payment method', action: `${ctx.publicBase}/p/session/${id}/payment_method`, fields: cardFields, submit: { label: pm ? 'Update' : 'Add' } }] } : {}), ...(back ? { back: { href: back, label: `← Return to ${merchant}` } } : {}), sections: [
                 { heading: 'Current plan', items: plans, empty: 'You have no active plans.' },
                 { heading: 'Payment method', items: methods, empty: 'No payment method on file.' },
                 { heading: 'Billing information', items: details },
@@ -108,7 +108,7 @@ async function move(ctx, id, session, subscription, kind) {
     const sub = resourceView(ctx, SUB, subscription);
     if (!sub || sub.customer !== session.customer || sub.status === 'canceled')
         return gone();
-    const back = new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+    const back = new Response(null, { status: 303, headers: { location: `${ctx.publicBase}/p/session/${id}` } });
     if (kind === 'renew') {
         await ctx.write(SUB, subscription, { cancel_at_period_end: false, cancel_at: null, canceled_at: null, cancellation_details: { comment: null, feedback: null, reason: null } }, 'subscription.update');
         return back;
@@ -149,7 +149,7 @@ async function updatePaymentMethod(ctx, id, session, v) {
     for (const sub of ctx.rows(SUB).map((s) => ctx.expand(SUB, s)).filter((s) => s.customer === customer && s.status !== 'canceled' && s.status !== 'incomplete_expired')) {
         await ctx.write(SUB, String(sub.id), { default_payment_method: pm.id }, 'subscription.update');
     }
-    return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+    return new Response(null, { status: 303, headers: { location: `${ctx.publicBase}/p/session/${id}` } });
 }
 /** The customer pays one of their open invoices with the card on file. */
 async function payInvoice(ctx, id, session, invoiceId) {
@@ -164,7 +164,7 @@ async function payInvoice(ctx, id, session, invoiceId) {
     const declined = await payOpenInvoice(ctx, invoiceId, pm);
     if (declined)
         return page(ctx, id, session, { error: declined.message, values: {} });
-    return new Response(null, { status: 303, headers: { location: `/p/session/${id}` } });
+    return new Response(null, { status: 303, headers: { location: `${ctx.publicBase}/p/session/${id}` } });
 }
 /** billing.stripe.com's portal pages, or undefined for any other request. */
 export async function screen(ctx) {

package/dist/src/screens/checkout.js

@@ -66,7 +66,7 @@ function customerEmailOf(session) {
     const email = session._customer?.email;
     return typeof email === 'string' && EMAIL.test(email) ? email : undefined;
 }
-function page(session, id, now, values = {}, error) {
+function page(publicBase, session, id, now, values = {}, error) {
     const lines = ((session.line_items?.data) ?? []).map((item) => ({
         name: String(item.description ?? 'Item'),
         amount: money(item.amount_total, item.currency ?? session.currency),
@@ -95,7 +95,7 @@ function page(session, id, now, values = {}, error) {
         title: 'Checkout',
         css: [PAYMENT_CSS, SKIN],
         status: error ? 402 : 200,
-        body: (_jsx(Payment, { merchant: merchant, lines: lines, ...(trialText ? { total: trialText.lead, note: trialText.note } : session.amount_total !== null && session.amount_total !== undefined ? { total: { label: mode === 'subscription' ? 'Subscribe' : `Pay ${merchant}`, amount: money(session.amount_total, session.currency) } } : {}), action: `/c/pay/${id}`, sections: [{ heading: 'Contact information', fields: contact }, { heading: 'Payment method', fields: card }], submit: { label: submit, testId: 'hosted-payment-submit-button' }, ...(typeof session.cancel_url === 'string' ? { back: { href: session.cancel_url, label: '← Back' } } : {}), ...(error ? { error } : {}) })),
+        body: (_jsx(Payment, { merchant: merchant, lines: lines, ...(trialText ? { total: trialText.lead, note: trialText.note } : session.amount_total !== null && session.amount_total !== undefined ? { total: { label: mode === 'subscription' ? 'Subscribe' : `Pay ${merchant}`, amount: money(session.amount_total, session.currency) } } : {}), action: `${publicBase}/c/pay/${id}`, sections: [{ heading: 'Contact information', fields: contact }, { heading: 'Payment method', fields: card }], submit: { label: submit, testId: 'hosted-payment-submit-button' }, ...(typeof session.cancel_url === 'string' ? { back: { href: session.cancel_url, label: '← Back' } } : {}), ...(error ? { error } : {}) })),
     });
 }
 const gone = () => flowPage({ title: 'Checkout', status: 404, css: [PAYMENT_CSS, SKIN], body: _jsx("main", { className: "pay-form", children: _jsx("h1", { children: "This Checkout Session is no longer active." }) }) });
@@ -104,14 +104,14 @@ async function pay(ctx, id, session, v) {
     const email = onFile ?? (typeof session.customer_email === 'string' ? session.customer_email : (v.email ?? '').trim());
     if (session.mode !== 'setup' || !session.customer) {
         if (!EMAIL.test(email))
-            return page(session, id, nowUnix(ctx.occurredAt), v, 'Your email address is incomplete.');
+            return page(ctx.publicBase, session, id, nowUnix(ctx.occurredAt), v, 'Your email address is incomplete.');
     }
     // a trial charges nothing now unless a one-time price is on the first invoice
     const oneTimeDue = ((session.line_items?.data) ?? []).some((it, i) => isOneTime(it, inlineOf(session, i)));
     const chargesNow = session.mode === 'payment' || (session.mode === 'subscription' && (!trialOf(session, nowUnix(ctx.occurredAt)) || oneTimeDue));
     const refused = cardAnswer(v, nowUnix(ctx.occurredAt), chargesNow);
     if (refused)
-        return page(session, id, nowUnix(ctx.occurredAt), v, refused);
+        return page(ctx.publicBase, session, id, nowUnix(ctx.occurredAt), v, refused);
     let existing = session;
     // Checkout always makes a customer for a subscription; a payment makes one only when the session asks
     if (!session.customer && (session.mode === 'subscription' || session.customer_creation === 'always')) {
@@ -162,5 +162,5 @@ export async function screen(ctx) {
     const stored = ctx.row(CS, id) ?? {};
     const coupon = stored._discount?.coupon;
     const full = { ...session, _subscription_data: stored._subscription_data, _price_data: stored._price_data, _merchant: merchantOf(ctx, stored), _coupon: typeof coupon === 'string' ? ctx.get('coupon', coupon) : undefined, _customer: typeof session.customer === 'string' ? ctx.get('customer', session.customer) : undefined };
-    return request.method === 'GET' ? page(full, id, nowUnix(ctx.occurredAt)) : pay(ctx, id, full, values);
+    return request.method === 'GET' ? page(ctx.publicBase, full, id, nowUnix(ctx.occurredAt)) : pay(ctx, id, full, values);
 }

package/dist/src/screens/connect-onboarding.d.ts

@@ -1,3 +1,3 @@
-import type { HandlerContext } from '@volter/world-core';
+import { type HandlerContext } from '@volter/world-core';
 /** connect.stripe.com's onboarding pages, or undefined for any other request. */
 export declare function screen(ctx: HandlerContext): Promise<Response>;

package/dist/src/screens/connect-onboarding.js

@@ -1,4 +1,31 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// STRIPE CONNECT HOSTED ONBOARDING — a hosted flow (docs/contributing/architecture.md, "Screens"): a platform
+// creates an Account Link for a connected account and sends the account's owner to its `url`. The link is a
+// single-use entry point: visiting it takes the owner to their onboarding session, and visiting it again, or after it
+// expires, sends them to refresh_url, where the platform makes a new one (docs.stripe.com/connect/hosted-onboarding).
+// At the session's own address they give Stripe what it requires, and Stripe sends them to return_url. Submitting is
+// the owner's move, not an API call. Authored from @volter/world-ui's payment piece and Stripe's published visual
+// example; the form moves through one section at a time, retaining answers until the final submit.
+//
+// The page asks for exactly what Stripe requires before a US Express account with card_payments and transfers can
+// take card payments (docs.stripe.com/connect/required-verification-information; the set is the one Stripe's
+// requirements endpoint answers, docs.stripe.com/_endpoint/get-requirements-for-setups with apiVersion=v1,
+// platformCountry=US, accountCountry=US, dashboardType=express, tosType=full, capabilities card_payments and transfers):
+// thirty requirements for a company (the business profile, the statement descriptor, the company with its tax id,
+// phone and address, its owners, its representative with their title and address, the agreement and the payout bank
+// account) and eighteen for an individual. A submit that leaves any out is refused with what is missing. The account's
+// requirements.currently_due lists what is still missing, and charges and payouts are enabled, and its requested
+// capabilities become active (Stripe's move on the capability machine), only once none is. The agreement is the
+// page's own checkbox, recorded as tos_acceptance with the request's address and the time.
+//
+// Where the documentation stops and the twin decides: only these two US sets are modelled; an account elsewhere, or
+// of another business type, is told its requirements are not modelled. Test mode verifies at once whatever is
+// submitted (docs.stripe.com/connect/testing lists the values that pass: date of birth 1901-01-01, SSN last four
+// 0000, tax id 000000000, routing 110000000, account 000123456789); the industries offered are Stripe's supported
+// merchant category codes as its list gives them (./industries.ts), and an industry the page does not offer leaves
+// business_profile.mcc due; the states are the fifty and the District of Columbia; a request with no forwarded address
+// records 127.0.0.1. An update link (account_update) shows the same page.
+import { twinVendorUrl } from '@volter/world-core';
 import { CONSENT_CSS, flowPage, Payment, PAYMENT_CSS } from '@volter/world-ui';
 import { nowUnix } from "../engine/stripe.js";
 import { formOf, notFound, seeOther, STRIPE_CONSENT_SKIN } from "./shared.js";
@@ -58,9 +85,9 @@ function page(ctx, sessionUrl, link, kind, values = {}, error) {
         : [{ heading: 'Business details', fields: business }, { heading: 'About you', fields: person }, { heading: 'Payout account', fields: payout }, { heading: 'Agreement', fields: agreement }];
     return flowPage({
         title: 'Stripe · Account onboarding',
-        css: [PAYMENT_CSS],
+        css: [ONBOARDING_CSS],
         ...(error ? { status: 400 } : {}),
-        body: (_jsx(Payment, { merchant: `Verify your ${kind === 'company' ? 'company' : 'business'} with Stripe · ${String(link.account)} · test mode`, lines: [], action: sessionUrl, sections: sections, submit: { label: 'Submit' }, back: { href: String(link.return_url), label: '← Return to platform' }, ...(error ? { error } : {}) })),
+        body: (_jsx(ConnectOnboarding, { merchant: "Stripe", account: String(link.account), checked: ['owners_provided', 'tos'].filter(name => v[name] === (name === 'tos' ? 'accepted' : 'provided')), lines: sections.map(section => ({ name: section.heading, amount: '' })), action: sessionUrl, sections: sections, submit: { label: 'Submit' }, back: { href: String(link.return_url), label: '← Return to platform' }, ...(error ? { error } : {}) })),
     });
 }
 /** An account whose requirements the twin does not model: outside the US, or of another business type. */
@@ -124,7 +151,7 @@ async function visit(ctx, id) {
         return seeOther(String(link.refresh_url));
     const session = `onbs_${id.replace(/^acctlink_/, '')}`;
     await ctx.write(LINK, id, { used: true, _session: session }, 'account_link.used');
-    return seeOther(`${SESSIONS}${session}`);
+    return seeOther(twinVendorUrl(ctx.call.request, `${SESSIONS}${session}`));
 }
 /** connect.stripe.com's onboarding pages, or undefined for any other request. */
 export async function screen(ctx) {
@@ -143,7 +170,7 @@ export async function screen(ctx) {
     const link = stored ? ctx.get(LINK, String(stored.id)) : undefined;
     if (!stored || !link)
         return gone();
-    const sessionUrl = `${SESSIONS}${sid}`;
+    const sessionUrl = twinVendorUrl(request, `${SESSIONS}${sid}`);
     const account = ctx.get('account', String(link.account)) ?? {};
     const kind = kindOf(account);
     if (!kind)
@@ -157,3 +184,50 @@ export async function screen(ctx) {
     await submit(ctx, link, kind, form, request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || '127.0.0.1');
     return seeOther(String(link.return_url));
 }
+// Visual reference: Stripe's own hosted onboarding example, read 2026-10-08:
+// https://docs.stripe.com/connect/hosted-onboarding
+// hosted_onboarding_form.e59ba8300f563e43489953f06127f52c.png. Platform branding
+// in that example is configurable; this twin uses its existing Stripe skin.
+const ONBOARDING_CSS = PAYMENT_CSS + `
+*{box-sizing:border-box}body{color:#30313d;background:#fff;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+.pay{grid-template-columns:minmax(280px,40%) minmax(0,60%)}.pay-summary{background:#f7f7f9;padding:48px max(32px,calc((100vw - 1000px)/2));padding-right:40px;position:relative}
+.pay-back{color:#596171;font-size:13px;margin-bottom:40px}.pay-merchant{color:#635bff;font-size:30px;font-weight:700;letter-spacing:-1px;margin-bottom:32px}
+.pay-lines{counter-reset:step;max-width:280px}.pay-line{counter-increment:step;display:block;position:relative;padding:12px 0 12px 38px;color:#687385;font-size:14px}
+.pay-line::before{content:counter(step);position:absolute;left:0;top:11px;width:24px;height:24px;line-height:22px;text-align:center;border:1px solid #d8dee4;border-radius:50%;background:#fff;font-size:12px}
+.pay-line[aria-current=step]{color:#30313d;font-weight:600}.pay-line[aria-current=step]::before{border-color:#635bff;color:#635bff}.pay-line.is-complete::before{background:#635bff;border-color:#635bff;color:#fff}
+.pay-form{padding:56px 48px;max-width:620px;width:100%}.pay-section legend{font-size:26px;letter-spacing:-.6px;font-weight:600;margin-bottom:24px}.pay-field{margin-bottom:22px}
+.pay-field span{font-size:14px;margin-bottom:8px;font-weight:500}.pay-field input,.pay-field select{background:#fff;border-color:#d8dee4;border-radius:6px;padding:10px 12px;box-shadow:0 1px 2px #00000005;color:#30313d}
+.pay-field input:focus,.pay-field select:focus{outline:2px solid #a5a0ff;outline-offset:1px}
+.pay-field:has(input[type=checkbox]){display:flex;align-items:flex-start;gap:10px}.pay-field:has(input[type=checkbox]) span{order:2;font-weight:400}.pay-field input[type=checkbox]{width:16px;height:16px;flex:none;margin-top:3px;accent-color:#635bff}
+.pay-submit,.connect-next{background:#635bff;color:#fff;border:0;border-radius:6px;font-size:14px;font-weight:600;cursor:pointer;padding:12px 16px}
+.connect-actions{display:flex;justify-content:space-between;gap:16px;margin-top:32px}.connect-back{color:#596171;background:transparent;border:0;cursor:pointer;padding:12px 0;font:inherit}.connect-next{min-width:140px;flex:1}
+.pay-error{border:1px solid #f1c2c2;padding:12px;border-radius:6px;color:#b52e2e;background:#fff7f7;font-size:13px;white-space:normal;overflow-wrap:anywhere}
+.connect-progress{height:3px;background:#ececf1;margin:0 0 36px;border-radius:2px;overflow:hidden}.connect-progress div{height:100%;background:#635bff;transition:width .15s}
+.connect-context{position:absolute;bottom:40px;left:32px;color:#687385;font-size:12px}.connect-context strong{display:block;font-weight:500;color:#30313d}
+.connect-ready .pay-section[hidden],.connect-ready .pay-submit[hidden],.connect-actions [hidden]{display:none}
+@media(max-width:800px){.pay{grid-template-columns:1fr}.pay-summary{padding:24px}.pay-back{margin-bottom:20px}.pay-merchant{font-size:24px;margin-bottom:0}.pay-lines{display:none}.connect-context{position:static;padding:0 24px;background:#f7f7f9}.pay-form{padding:32px 24px;max-width:100%}.pay-section legend{font-size:24px}}
+`;
+// Progressive enhancement only: Back/Continue move through the existing form.
+// No account state is written until its existing Submit operation succeeds.
+const STEPS = `(function(){
+var root=document.querySelector('.connect-onboarding'),form=root.querySelector('form'),groups=Array.from(form.querySelectorAll('.pay-section')),items=Array.from(root.querySelectorAll('.pay-line')),submit=form.querySelector('.pay-submit');
+var progress=document.createElement('div');progress.className='connect-progress';progress.setAttribute('role','progressbar');progress.setAttribute('aria-label','Onboarding progress');progress.setAttribute('aria-valuemin','0');progress.setAttribute('aria-valuemax',String(groups.length));
+var bar=document.createElement('div');progress.append(bar);form.before(progress);
+var controls=document.createElement('div');controls.className='connect-actions';
+var back=document.createElement('button');back.type='button';back.className='connect-back';back.textContent='Back';
+var next=document.createElement('button');next.type='button';next.className='connect-next';next.textContent='Continue';
+controls.append(back,next);form.append(controls);
+var checked=JSON.parse(root.getAttribute('data-checked-fields')||'[]');
+groups.forEach(function(group){group.querySelectorAll('input,select').forEach(function(input){input.required=true;if(input.type==='checkbox')input.checked=checked.includes(input.name);if(input.name==='ssn_last_4'){input.pattern='[0-9]{4}';input.inputMode='numeric';input.maxLength=4;}});});
+var index=0;
+function show(i){index=i;groups.forEach(function(group,n){group.hidden=n!==i;});items.forEach(function(item,n){if(n===i)item.setAttribute('aria-current','step');else item.removeAttribute('aria-current');item.classList.toggle('is-complete',n<i);});back.hidden=i===0;next.hidden=i===groups.length-1;submit.hidden=i!==groups.length-1;bar.style.width=((i+1)/groups.length*100)+'%';progress.setAttribute('aria-valuenow',String(i+1));progress.setAttribute('aria-valuetext',groups[i].querySelector('legend').textContent);root.classList.add('connect-ready');}
+function invalid(group){return Array.from(group.querySelectorAll('input,select')).find(function(input){return !input.checkValidity();});}
+back.addEventListener('click',function(){show(index-1);});
+next.addEventListener('click',function(){var field=invalid(groups[index]);if(field){field.reportValidity();return;}show(index+1);groups[index].querySelector('input,select')?.focus();});
+form.noValidate=true;
+form.addEventListener('submit',function(event){for(var i=0;i<groups.length;i++){var field=invalid(groups[i]);if(field){event.preventDefault();show(i);field.reportValidity();return;}}});
+if(form.querySelector('.pay-error')){var first=groups.findIndex(function(group){return invalid(group);});show(first<0?groups.length-1:first);}else show(0);
+})();`;
+function ConnectOnboarding(props) {
+    return _jsxs("div", { className: "connect-onboarding", "data-checked-fields": JSON.stringify(props.checked), children: [_jsx(Payment, { ...props }), _jsxs("div", { className: "connect-context", children: [_jsx("strong", { children: "Test mode" }), props.account] }), _jsx("script", { dangerouslySetInnerHTML: { __html: STEPS } })] });
+}

package/dist/src/screens/dashboard.d.ts

@@ -1,3 +1,3 @@
 import type { HandlerContext } from '@volter/world-core';
-/** Dashboard settings, Radar list creation and test Issuing funding; other pages answer Stripe's 404. */
+/** Dashboard customer inspection, settings, Radar lists and test Issuing funding. */
 export declare function screen(ctx: HandlerContext): Promise<Response>;