@agent-cards/checkout 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+- Complete a merchant-confirmed payment when the merchant supplies no order or receipt ID. Return `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }` from the merchant resolver using the current checkout authorization. The resolver must verify the original payment request, amount, currency, selected card and merchant success; HTTP 200 or a success page alone is insufficient. The completed state carries `confirmation` without inventing `orderId`, clears stale reasons and continues to block another payment. Existing completion results with a genuine `orderId` keep working.
+
+- Approve a Recurly checkout before its native card request starts. Call `prepare` with `psp: 'recurly'` and `environment: 'shared'`, then submit the merchant's form once. The same selected card and approved purchase bind a new-card POST on the US or EU endpoint. The matching API, database migration and Vault release are required. Token issuance and merchant payment completion remain separate results.
+
 - Keep the selected card's issuer in guest Mercado Pago Checkout Pro in Mexico. The Vault resolves the card's eight-digit prefix against the merchant's captured checkout configuration over browser TLS. The SDK returns the original card-token response and corrects one native card association. Missing configuration, ambiguous issuers, changed checkout context, and a different card brand or type stop continuation. The matching API, Vault and encrypted relay release is required. Other Mercado Pago checkout families and merchant payment completion need separate validation.
 
 - Prepare controlled hosted Stripe Checkout in TEST mode with an explicit `stripeCheckout` attachment option and Autopilot grant. Dummy tokenization stays local; the browser's native final confirmation uses the generated shared core and enclave execution path. The matching backend and executor flags default off. This does not enable production Autopilot or establish a completed merchant order.

package/PREFLIGHT.md

@@ -208,7 +208,7 @@ Declare processor support and flow support separately. A flow entry cannot estab
 
 Take PSP identifiers, payment modes, flow identifiers, operation identifiers, and operation revisions from the packaged catalog. Verify each combination against the named adapter version before adding a `supported` entry. Use `unsupported` only for a known exclusion. A profile with a wrong schema, incompatible catalog, mismatched adapter version, or expired timestamp preserves `unknown`.
 
-The JSON contract uses `schema_version: 1`. The catalog bundled with this release uses `catalog_version: "2026-09-11.2"`. Keep the snapshot, classifier, and profile on the same catalog version. Re-normalize observations with the installed package after changing the catalog. Review the adapter declarations before issuing a compatible profile; changing the version string alone does not validate new behavior.
+The JSON contract uses `schema_version: 1`. The catalog bundled with this release uses `catalog_version: "2026-09-14.1"`. Keep the snapshot, classifier, and profile on the same catalog version. Re-normalize observations with the installed package after changing the catalog. Review the adapter declarations before issuing a compatible profile; changing the version string alone does not validate new behavior.
 
 Kernel can integrate the JSON contract immediately and supply its validated native capabilities later. No deployed Agentcard endpoint or payment request is required for that work.
 

package/README.md

@@ -134,7 +134,7 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 | Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms read the intent's amount back from Stripe; a hint sent as `amount` + `currency` must agree with it. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
 | Braintree card tokenization | Prepared checkout supported; one live Haymarket Books ebook purchase with SDK `0.5.0` confirmed merchant fulfillment and SDK `completed` using a merchant receipt resolver. Independent processor capture/settlement, live 3DS and PayPal wallet flows remain unverified. |
 | Checkout.com | supported |
-| Mercado Pago | Card tokenization and prepared checkout are implemented. Guest Checkout Pro in Mexico also corrects the issuer for one native card association when the selected card has the same brand and type. A completed merchant payment remains unverified. |
+| Mercado Pago | Card tokenization and prepared checkout are implemented. Guest Checkout Pro in Mexico also corrects the issuer for one native card association when the selected card has the same brand and type. One live MXN 40 Lotería Chida purchase with published SDK 0.10.0 completed automatically through Pay; the merchant confirmed paid status and PDF fulfillment. The historical SDK result remains unknown because the private receipt adapter rejected a relative download URL; a separate read with the corrected adapter confirms that same paid receipt. Independent processor capture/settlement and other country or integration paths remain unverified. |
 | VGS Collect (Very Good Security; Wolt) | not supported: VGS's proxy aliases only submissions from its own iframe, so a replay from the cardholder's device is refused by the merchant (verified on Wolt, 2026-09-03). Not recognized, so the agent's browser is not paused there |
 | Adyen | supported (mode `cse`): the vault encrypts the card for Adyen on the cardholder's device and your browser sends it |
 | Tranzila | supported (mode `hosted_form`): the cardholder finishes on Tranzila's own page; the paused form navigation resolves to a synthetic page, and you poll the merchant's order state |
@@ -367,17 +367,56 @@ const checkout = await attachToPlaywright(page, {
 
 // Your existing agent dispatches checkout. Later, once the paused request resumes:
 const state = await checkout.reconcile();
-if (state.status === 'completed' && state.orderId) await finishAgentTask(state.orderId);
+if (state.status === 'completed') await finishAgentTask(state);
 ```
 
-`resolveMerchantResult` must read an authoritative merchant order/receipt tied
-to this attempt. It returns one of:
+`resolveMerchantResult` must verify the merchant's result for the original
+payment attempt. It returns one of:
 
-- `{ status: 'completed', orderId }`: merchant-confirmed success.
+- `{ status: 'completed', orderId }`: merchant-confirmed success with a genuine order or receipt ID. Existing integrations keep this form.
+- `{ status: 'completed', confirmation: { kind: 'merchant_payment', authorizationId } }`: merchant-confirmed payment when no order or receipt ID is available. The ID must match the current checkout authorization.
 - `{ status: 'failed' }`: merchant confirmed the attempt failed; no successful payment/order exists.
 - `{ status: 'pending' }` or `{ status: 'unknown' }`: keep waiting or reconcile; never click Pay again.
 - `{ status: 'requires_user_action', reason: '3ds' | 'redirect' | 'other' }`: deliver your own browser live view or supported challenge UI to the user.
 
+For a merchant that confirms payment without returning an order ID, your
+resolver can return the explicit payment confirmation:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user, merchant, amount, currency,
+  requireMerchantResult: true,
+  resolveMerchantResult: async state => {
+    const payment = await readOriginalMerchantPayment(state);
+    if (!payment.confirmed || !state.authorizationId) return { status: 'unknown' };
+    return {
+      status: 'completed',
+      confirmation: {
+        kind: 'merchant_payment',
+        authorizationId: state.authorizationId,
+      },
+    };
+  },
+});
+```
+
+`readOriginalMerchantPayment` is your merchant-specific check. The check must
+match the original payment request, amount, currency and selected card, and
+verify authoritative merchant success for that attempt. HTTP 200 alone, a card
+token, a success URL or text that anyone can open does not establish payment.
+Copying `state.authorizationId` without checking the payment is insufficient.
+The SDK checks the authorization binding; it does not independently authenticate
+the merchant evidence supplied by your resolver.
+
+Return one completion form at a time. The payment-confirmation form leaves
+`state.orderId` absent and exposes `state.confirmation` with the exported
+`MerchantPaymentConfirmation` type. Your consumer should finish on
+`state.status === 'completed'` and treat `orderId` as optional. A missing or
+mismatched authorization, or `{ status: 'completed' }` without either completion
+form, leaves the outcome unknown. Confirmed completion clears stale failure or
+authentication reasons and continues to block further payment submissions.
+Never invent an order ID from a token or authorization ID.
+
 The SDK does not infer order success from `authorized` or a tokenization reply,
 and does not claim to detect or solve arbitrary 3DS challenges. Your merchant
 resolver (or `checkout.requestUserAction('3ds')` when your browser observes it)
@@ -388,22 +427,29 @@ isolated from the payment handoff.
 Native Stripe Checkout emits `checkout_blocked` before the existing `blocked`
 event when its local preparation rejects a request. Its
 `StripeCheckoutBlockedDetail` contains only fixed codes: `version: 1`,
-`processor: 'stripe'`, endpoint family, phase, stage, reason, gate state, and
-disposition. It contains no URLs, identifiers, request fields, or exception text.
+`processor: 'stripe'`, endpoint family, phase, stage, reason, optional validation code, gate state, and
+disposition. It contains no URLs, identifiers, request-derived field names or values, or exception text.
 
 | Field | Values |
 | --- | --- |
 | `endpoint_family` | `payment_methods`, `payment_page_confirm`, `other` |
 | `phase` | `tokenization`, `final`, `unknown` |
 | `stage` | `request_read`, `classification`, `claim`, `readiness`, `document`, `stub_response` |
+| `validation_code` | Shared-core `StripeCheckoutValidationCode`; present only for `request_validation_failed` |
 | `gate_state` | `fresh`, `stubbed`, `submitted`, `stopped` |
 | `disposition` | `active_claim_preserved`, `checkout_stopped` |
 
 `reason` is the exported `StripeCheckoutBlockReason` union. It identifies SDK
 claim and readiness failures, such as `duplicate_confirmation`, `document_changed`,
-or `attachment_not_ready`. The shared core's rejection is
-`request_validation_failed` with phase `unknown`; this event does not infer which
-core predicate failed. `gate_state` records the state before the adapter handles
+or `attachment_not_ready`. A shared-core rejection reports
+`request_validation_failed` and a fixed `validation_code` identifying the failed
+check, or `unclassified` when no recognized code is available. Initial request
+classification uses phase `unknown`; a billing capture rejection uses
+`tokenization`, and a billing attachment rejection uses `final`.
+For example, `form_field_unknown` identifies an allowlist rejection without
+revealing the field name or value. Identifying that field requires a separate
+reviewed synthetic fixture; the code alone does not establish or fix a processor
+schema mismatch. `gate_state` records the state before the adapter handles
 the failure, though document validation may already have stopped the gate.
 
 `active_claim_preserved` means a valid duplicate was refused without invalidating
@@ -467,8 +513,17 @@ await page.getByRole('button', { name: 'Pay', exact: true }).click();
 | Worldpay | `production` or `sandbox` | Matching Access Worldpay host and `/sessions/card` |
 | Bambora | `shared` | `/scripts/tokenization/tokens` on `api.bam.shift4api.net` or `api.na.bambora.com` |
 | Mercado Pago | `shared` | `api.mercadopago.com/v1/card_tokens` with a fresh card body |
+| Recurly | `shared` | Form-encoded POST to `/js/v1/token` on `api.recurly.com` or `api.eu.recurly.com` |
+
+Use `environment: 'shared'` for Bambora, Mercado Pago and Recurly because the same endpoint serves test and live requests. Agentcard cannot establish the processor's test mode from that URL or a credential prefix. Configure test mode through the merchant's processor account when testing. Agentcard's own `sandbox` flag remains separate. Prepared Worldpay, Bambora, Mercado Pago and Recurly requests reject saved-card and recurring request bodies; a refused request retires the local preparation. Reconcile any existing merchant attempt before creating a new attachment.
 
-Use `environment: 'shared'` for Bambora and Mercado Pago because the same endpoint serves test and live requests. Agentcard cannot establish the processor's test mode from that URL or a credential prefix. Configure test mode through the merchant's processor account when testing. Agentcard's own `sandbox` flag remains separate. Prepared Worldpay, Bambora and Mercado Pago requests reject saved-card and recurring request bodies; a refused request retires the local preparation. Reconcile any existing merchant attempt before creating a new attachment.
+Prepare Recurly before clicking the merchant's payment button:
+
+```ts
+await controller.prepare({ psp: 'recurly', environment: 'shared' });
+```
+
+After approval, submit the merchant's form once. Recurly's native request timer starts with that submission. The SDK preserves the captured US or EU endpoint and accepts a new-card form only. Legacy JSONP, saved tokens, bank accounts, alternative payments and proactive authentication requests require separate support. Prepared requests also refuse nonempty Worldpay or Cybersource risk results because those sessions can depend on the original card. A nonempty co-badged network preference is also refused until the selected card’s supported networks can be checked. A card token does not confirm a donation, subscription or purchase; confirm the merchant's result before reporting payment success.
 
 ### Use Checkout Pro in Mexico
 
@@ -570,10 +625,12 @@ When the cardholder has enabled an eligible spending rule in their vault, the sa
 
 Use `executionMode: 'user_approval'` to require the existing confirmation flow. Without a selected card or grant, the backend can use exactly one eligible rule; ambiguous card selection keeps confirmation. A `grantId` restricts selection to that rule. The initial executor supports only the configured controlled Stripe test flow, and production remains disabled.
 
-For the controlled hosted Stripe Checkout TEST integration, both attachment functions accept `stripeCheckout: { sessionId, publishableKey }`. This requires a `cs_test_` Session, its `pk_test_` key, `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that Session on `checkout.stripe.com`.
+For controlled hosted Stripe Checkout, both attachment functions accept `stripeCheckout: { sessionId, publishableKey, environment? }`. The default is TEST, requiring `cs_test_` and `pk_test_`. LIVE requires explicit `environment: 'production'`, a `cs_live_` Session and its `pk_live_` key. Both modes require `executionMode: 'autopilot'`, an explicit `grantId`, and a positive numeric USD `amount` in cents. The top-level document must be that exact Session on `https://checkout.stripe.com`, at `/c/pay/{sessionId}`, `/pay/{sessionId}`, `/g/pay/{sessionId}`, or `/f/pay/{sessionId}`. The SDK validates the existing URL without rewriting or navigating it. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
 
 The SDK answers dummy-card tokenization locally, then sends the browser's final native confirmation through the shared core and enclave. The local response is preparation only: it creates no authorization and makes no processor request. The final result includes `checkoutSessionId` only after the selected grant, restricted terminal response, and captured amount have been checked. Continue to confirm the merchant order through the checkout controller.
 
-This integration requires matching backend and measured executor releases, with separate TEST flags explicitly enabled. An unavailable prepared request is declined or held for reconciliation; it cannot switch to human approval. LIVE Sessions, subscriptions, saved-card flows, and authentication continuations are not supported by this option. It cannot enable production Autopilot.
+The shared core carries a validated billing email from that tokenization request into the final confirmation before authorization. The email stays bound to the same Session and local PaymentMethod reference. Missing email stays missing; duplicate or conflicting values are refused. The SDK does not fill an email from the Agentcard account or invent one for the merchant.
+
+This integration requires matching backend and measured executor releases. TEST and LIVE have separate admission controls. LIVE also requires a newly authorized production grant on the selected real card, a fixed merchant account/profile with exactly one complete fixed-price USD line item and an independently reviewed operation qualification reference; the SDK option supplies none of these. LIVE deployment remains unqualified and disabled until that evidence exists. Exact observed totals do not establish atomic amount enforcement by Stripe. Subscriptions, saved-card flows and authentication continuations remain excluded. An unavailable preparation or uncertain result is declined or held for reconciliation; it cannot switch to a competing human-approval payment.
 
 The adapters also send the observed top-level HTTPS `merchantOrigin`, such as `https://shop.example`, without a path, query or trailing slash. Direct `authorize()` callers can supply that origin explicitly. It is a routing hint; the protected adapter independently verifies the processor account, payee and amount. If a browser cannot provide its top-level URL, an explicit `merchantOrigin` option can supply the hint; otherwise the regular approval path remains available.

package/dist/cdp.js

@@ -711,6 +711,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 cardId: preparation?.cardId ?? opts.cardId,
                 executionMode: opts.executionMode,
                 grantId: opts.grantId,
+                stripeCheckoutEnvironment: opts.stripeCheckout?.environment,
                 merchantOrigin,
                 pageOrigin,
                 pageAmount,
@@ -1076,6 +1077,7 @@ export async function attachToPlaywright(page, opts) {
                     cardId: preparation?.cardId ?? opts.cardId,
                     executionMode: opts.executionMode,
                     grantId: opts.grantId,
+                    stripeCheckoutEnvironment: opts.stripeCheckout?.environment,
                     merchantOrigin,
                     pageOrigin,
                     pageAmount,

package/dist/client.d.ts

@@ -166,6 +166,8 @@ export declare class CheckoutPreparationError extends Error {
     constructor(preparationId: string | null, reason: string);
 }
 export interface AuthorizeInput extends ExecutionMetadata {
+    /** Native Checkout defaults to TEST; LIVE requires this explicit opt-in. */
+    stripeCheckoutEnvironment?: 'test' | 'production';
     /** Observed top-level HTTPS merchant origin; a routing hint, never payment authority. */
     merchantOrigin?: string;
     /** Your identifier for the person whose card should pay. */

package/dist/client.js

@@ -520,14 +520,16 @@ export class VaultClient {
             || input.executionMode === 'autopilot' || input.grantId))
             throw new Error('mercado_checkout_context_invalid');
         const nativeCheckout = hasStripeCheckoutMarker(input.request);
+        if (input.stripeCheckoutEnvironment !== undefined && !nativeCheckout)
+            throw new Error('Native Stripe Checkout environment requires its bound request.');
         const checkoutContext = nativeCheckout ? parseStripeCheckoutContext(input.request) : null;
         if (nativeCheckout) {
             if (!checkoutContext || input.preparation || input.executionMode !== 'autopilot' || !input.grantId
                 || !Number.isSafeInteger(input.amount) || Number(input.amount) <= 0 || input.currency !== 'usd'
                 || input.merchantOrigin !== 'https://checkout.stripe.com')
-                throw new Error('Native Stripe Checkout requires an explicit TEST autopilot configuration.');
+                throw new Error('Native Stripe Checkout requires an explicit mode-bound autopilot configuration.');
             const phase = classifyStripeCheckoutRequest(input.request, {
-                sessionId: checkoutContext.session_id, syntheticPaymentMethodId: checkoutContext.synthetic_payment_method_id,
+                environment: input.stripeCheckoutEnvironment, sessionId: checkoutContext.session_id, syntheticPaymentMethodId: checkoutContext.synthetic_payment_method_id,
                 amountCents: input.amount,
             });
             if (phase?.phase !== 'final')
@@ -814,7 +816,7 @@ export class VaultClient {
                     if (checkoutContext) {
                         let receipt;
                         try {
-                            receipt = parseStripeCheckoutResponse(JSON.parse(response.body), { sessionId: checkoutContext.session_id });
+                            receipt = parseStripeCheckoutResponse(JSON.parse(response.body), { environment: input.stripeCheckoutEnvironment, sessionId: checkoutContext.session_id });
                         }
                         catch { /* Never return an unvalidated processor body to the page. */ }
                         if (response.status !== 200 || !receipt || s.amount_verified !== true

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted
 export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';
 export type { Recognizer, CheckoutMode } from './registry.js';
-export type { CheckoutController, CheckoutState, MerchantResult, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';
+export type { CheckoutController, CheckoutState, MerchantResult, MerchantPaymentConfirmation, UserAction, LifecycleOptions, PaymentEndpointGuard } from './lifecycle.js';

package/dist/lifecycle.d.ts

@@ -1,9 +1,19 @@
 import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
 import type { CheckoutMode } from './registry.js';
-/** A processor approval is not an order. Only the merchant can confirm this result. */
+/** The application's resolver confirmed the payment for this checkout authorization. */
+export interface MerchantPaymentConfirmation {
+    kind: 'merchant_payment';
+    authorizationId: string;
+}
+/** Only authoritative merchant evidence can confirm completion; a processor token is insufficient. */
 export type MerchantResult = {
     status: 'completed';
     orderId: string;
+    confirmation?: never;
+} | {
+    status: 'completed';
+    confirmation: MerchantPaymentConfirmation;
+    orderId?: never;
 } | {
     status: 'failed';
 } | {
@@ -18,6 +28,7 @@ export interface CheckoutState {
     preparationId?: string;
     mode?: CheckoutMode;
     orderId?: string;
+    confirmation?: MerchantPaymentConfirmation;
     /** Stable SDK category; never includes a request body, processor response, or approval link. */
     reason?: string;
 }
@@ -30,7 +41,7 @@ export interface UserAction {
 export interface LifecycleOptions {
     onStateChange?: (state: Readonly<CheckoutState>) => void;
     onUserAction?: (action: UserAction) => void | Promise<void>;
-    /** Read authoritative merchant order state; do not click Pay or initiate a new charge here. */
+    /** Read authoritative merchant payment or order state; do not click Pay or initiate a new charge here. */
     resolveMerchantResult?: (state: Readonly<CheckoutState>) => Promise<MerchantResult>;
     /** Hold further card requests after handoff until the merchant result is reconciled. Default false for compatibility. */
     requireMerchantResult?: boolean;

package/dist/lifecycle.js

@@ -17,7 +17,9 @@ export class CheckoutLifecycle {
     constructor(options) {
         this.options = options;
     }
-    getState() { return { ...this.state }; }
+    getState() {
+        return { ...this.state, ...(this.state.confirmation ? { confirmation: { ...this.state.confirmation } } : {}) };
+    }
     setPreparationHandler(handler) { this.preparationHandler = handler; }
     prepare(options) {
         if (!this.preparationHandler)
@@ -195,14 +197,28 @@ export class CheckoutLifecycle {
         catch {
             result = { status: 'unknown' };
         }
-        if (!result || typeof result !== 'object')
+        if (!result || typeof result !== 'object' || Array.isArray(result))
             result = { status: 'unknown' };
-        if (result.status === 'completed' && typeof result.orderId === 'string' && result.orderId.length > 0) {
+        // The resolver is trusted application code: it must check the original
+        // request, amount, currency, selected card and authoritative merchant
+        // result. The SDK binds its explicit confirmation to this authorization;
+        // it does not turn an HTTP response or a success URL into payment proof.
+        const orderConfirmed = result.status === 'completed' && result.confirmation === undefined
+            && typeof result.orderId === 'string' && result.orderId.length > 0;
+        const paymentConfirmed = result.status === 'completed' && result.orderId === undefined
+            && result.confirmation && typeof result.confirmation === 'object' && !Array.isArray(result.confirmation)
+            && result.confirmation.kind === 'merchant_payment'
+            && typeof this.state.authorizationId === 'string' && this.state.authorizationId.length > 0
+            && result.confirmation.authorizationId === this.state.authorizationId;
+        if (result.status === 'completed' && (orderConfirmed || paymentConfirmed)) {
             this.held = true;
-            // Merchant completion supersedes the earlier failure or user-action
-            // reason; keep the authorization and preparation context for observers.
-            const { reason: _previousReason, ...context } = this.state;
-            this.set({ ...context, status: 'completed', orderId: result.orderId });
+            // Completion supersedes an earlier failure/challenge, while retaining
+            // preparation and authorization context. Never copy arbitrary evidence
+            // into public state or release the hold on additional payment requests.
+            const { reason: _previousReason, orderId: _previousOrder, confirmation: _previousConfirmation, ...context } = this.state;
+            this.set({ ...context, status: 'completed', ...(orderConfirmed
+                    ? { orderId: result.orderId }
+                    : { confirmation: { kind: 'merchant_payment', authorizationId: this.state.authorizationId } }) });
         }
         else if (result.status === 'failed') {
             // Keep the guard armed until the application deliberately starts another attempt.

package/dist/preflight-capabilities.generated.d.ts

@@ -51,7 +51,7 @@ export declare const CHECKOUT_PREFLIGHT_CAPABILITIES: {
         readonly mode: "token";
         readonly operations: readonly [{
             readonly id: "stripe.device_checkout_confirm.v1";
-            readonly path_pattern: "^/v1/payment_pages/cs_test_[A-Za-z0-9]+/confirm$";
+            readonly path_pattern: "^/v1/payment_pages/cs_(?:test|live)_[A-Za-z0-9]+/confirm$";
             readonly effect: "payment_confirmation";
             readonly amount_binding: "expected_amount_test_evidence_currency_unqualified";
             readonly psp: "stripe";
@@ -1002,7 +1002,7 @@ export declare const CHECKOUT_PREFLIGHT_CAPABILITIES: {
                 readonly requirements: readonly ["verify_merchant_billing"];
             };
         };
-        readonly limitations: readonly ["Only the listed request format is recognized; a recognized processor is not verified merchant coverage.", "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints."];
+        readonly limitations: readonly ["Only the listed request format is recognized; a recognized processor is not verified merchant coverage.", "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints.", "Prepare approval before submitting a timed native card form. Both regions require the shared environment because test and live keys use the same endpoints."];
         readonly unsupported_variants: readonly [{
             readonly variant: "legacy_jsonp_get";
             readonly status: "unsupported";
@@ -1013,6 +1013,21 @@ export declare const CHECKOUT_PREFLIGHT_CAPABILITIES: {
             readonly status: "unsupported";
             readonly constraint: "direct_sdk";
             readonly reason: "Bank-account and alternative-payment token routes are outside the new-card path.";
+        }, {
+            readonly variant: "card_bound_risk_preflight";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Worldpay and Cybersource risk sessions can depend on the original card. Prepared requests refuse those results until collection can use the approved card.";
+        }, {
+            readonly variant: "prepared_co_badged_network_choice";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "A prepared request cannot reuse the original card’s network preference without checking the selected card’s supported networks.";
+        }, {
+            readonly variant: "proactive_authentication";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Card-bearing risk authentication and proactive 3-D Secure action tokens require separate support.";
         }];
         readonly processor_amount: "none";
         readonly challenge_surface: "merchant_browser";

package/dist/preflight-capabilities.generated.js

@@ -80,7 +80,7 @@ export const CHECKOUT_PREFLIGHT_CAPABILITIES = {
             "operations": [
                 {
                     "id": "stripe.device_checkout_confirm.v1",
-                    "path_pattern": "^/v1/payment_pages/cs_test_[A-Za-z0-9]+/confirm$",
+                    "path_pattern": "^/v1/payment_pages/cs_(?:test|live)_[A-Za-z0-9]+/confirm$",
                     "effect": "payment_confirmation",
                     "amount_binding": "expected_amount_test_evidence_currency_unqualified",
                     "psp": "stripe",
@@ -1545,7 +1545,8 @@ export const CHECKOUT_PREFLIGHT_CAPABILITIES = {
             },
             "limitations": [
                 "Only the listed request format is recognized; a recognized processor is not verified merchant coverage.",
-                "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints."
+                "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints.",
+                "Prepare approval before submitting a timed native card form. Both regions require the shared environment because test and live keys use the same endpoints."
             ],
             "unsupported_variants": [
                 {
@@ -1559,6 +1560,24 @@ export const CHECKOUT_PREFLIGHT_CAPABILITIES = {
                     "status": "unsupported",
                     "constraint": "direct_sdk",
                     "reason": "Bank-account and alternative-payment token routes are outside the new-card path."
+                },
+                {
+                    "variant": "card_bound_risk_preflight",
+                    "status": "unsupported",
+                    "constraint": "direct_sdk",
+                    "reason": "Worldpay and Cybersource risk sessions can depend on the original card. Prepared requests refuse those results until collection can use the approved card."
+                },
+                {
+                    "variant": "prepared_co_badged_network_choice",
+                    "status": "unsupported",
+                    "constraint": "direct_sdk",
+                    "reason": "A prepared request cannot reuse the original card’s network preference without checking the selected card’s supported networks."
+                },
+                {
+                    "variant": "proactive_authentication",
+                    "status": "unsupported",
+                    "constraint": "direct_sdk",
+                    "reason": "Card-bearing risk authentication and proactive 3-D Secure action tokens require separate support."
                 }
             ],
             "processor_amount": "none",

package/dist/preflight-catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "catalog_version": "2026-09-11.2",
+  "catalog_version": "2026-09-14.1",
   "scope": "preflight_hint",
   "integration_version_note": "bundled describes the capabilities accompanying this helper, not a claim about another installed SDK version.",
   "limits": {
@@ -1966,7 +1966,7 @@
       "operations": [
         {
           "id": "stripe.device_checkout_confirm.v1",
-          "path_pattern": "^/v1/payment_pages/cs_test_[A-Za-z0-9]+/confirm$",
+          "path_pattern": "^/v1/payment_pages/cs_(?:test|live)_[A-Za-z0-9]+/confirm$",
           "effect": "payment_confirmation",
           "amount_binding": "expected_amount_test_evidence_currency_unqualified",
           "psp": "stripe",
@@ -3431,7 +3431,8 @@
       },
       "limitations": [
         "Only the listed request format is recognized; a recognized processor is not verified merchant coverage.",
-        "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints."
+        "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints.",
+        "Prepare approval before submitting a timed native card form. Both regions require the shared environment because test and live keys use the same endpoints."
       ],
       "unsupported_variants": [
         {
@@ -3445,6 +3446,24 @@
           "status": "unsupported",
           "constraint": "direct_sdk",
           "reason": "Bank-account and alternative-payment token routes are outside the new-card path."
+        },
+        {
+          "variant": "card_bound_risk_preflight",
+          "status": "unsupported",
+          "constraint": "direct_sdk",
+          "reason": "Worldpay and Cybersource risk sessions can depend on the original card. Prepared requests refuse those results until collection can use the approved card."
+        },
+        {
+          "variant": "prepared_co_badged_network_choice",
+          "status": "unsupported",
+          "constraint": "direct_sdk",
+          "reason": "A prepared request cannot reuse the original card’s network preference without checking the selected card’s supported networks."
+        },
+        {
+          "variant": "proactive_authentication",
+          "status": "unsupported",
+          "constraint": "direct_sdk",
+          "reason": "Card-bearing risk authentication and proactive 3-D Secure action tokens require separate support."
         }
       ],
       "processor_amount": "none",
@@ -3722,7 +3741,7 @@
   "direct_sdk_profile": {
     "schema_version": 1,
     "profile_version": "preflight-2",
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "integration": {
       "id": "direct_sdk",
       "version": "bundled"
@@ -3881,7 +3900,7 @@
   "kernel_profile_template": {
     "schema_version": 1,
     "profile_version": "kernel-template-1",
-    "catalog_version": "2026-09-11.2",
+    "catalog_version": "2026-09-14.1",
     "integration": {
       "id": "kernel_native",
       "version": "REPLACE-WITH-ADAPTER-VERSION"

package/dist/preflight-schemas.json

@@ -162,7 +162,7 @@
             "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,119}$"
           },
           "catalog_version": {
-            "const": "2026-09-11.2"
+            "const": "2026-09-14.1"
           },
           "integration": {
             "type": "object",
@@ -358,7 +358,7 @@
         "const": 1
       },
       "catalog_version": {
-        "const": "2026-09-11.2"
+        "const": "2026-09-14.1"
       },
       "signals": {
         "type": "array",
@@ -550,7 +550,7 @@
         "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,119}$"
       },
       "catalog_version": {
-        "const": "2026-09-11.2"
+        "const": "2026-09-14.1"
       },
       "integration": {
         "type": "object",
@@ -753,7 +753,7 @@
         "const": 1
       },
       "catalog_version": {
-        "const": "2026-09-11.2"
+        "const": "2026-09-14.1"
       },
       "integration": {
         "type": "object",

package/dist/preflight.generated.d.ts

@@ -1,6 +1,6 @@
 /** Advisory page discovery. These rules never admit a payment destination. */
 export declare const CHECKOUT_PREFLIGHT_VERSION = "1";
-export declare const CHECKOUT_PREFLIGHT_CATALOG_VERSION = "2026-09-11.2";
+export declare const CHECKOUT_PREFLIGHT_CATALOG_VERSION = "2026-09-14.1";
 export declare const CHECKOUT_PREFLIGHT_LIMITS: Readonly<{
     frames: 64;
     signals: 2048;
@@ -196,7 +196,7 @@ export declare function getCheckoutPreflightCatalog(): {
         readonly mode: "token";
         readonly operations: readonly [{
             readonly id: "stripe.device_checkout_confirm.v1";
-            readonly path_pattern: "^/v1/payment_pages/cs_test_[A-Za-z0-9]+/confirm$";
+            readonly path_pattern: "^/v1/payment_pages/cs_(?:test|live)_[A-Za-z0-9]+/confirm$";
             readonly effect: "payment_confirmation";
             readonly amount_binding: "expected_amount_test_evidence_currency_unqualified";
             readonly psp: "stripe";
@@ -1147,7 +1147,7 @@ export declare function getCheckoutPreflightCatalog(): {
                 readonly requirements: readonly ["verify_merchant_billing"];
             };
         };
-        readonly limitations: readonly ["Only the listed request format is recognized; a recognized processor is not verified merchant coverage.", "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints."];
+        readonly limitations: readonly ["Only the listed request format is recognized; a recognized processor is not verified merchant coverage.", "The adapter covers the normal XHR POST new-card tokenization path on Recurly US and EU endpoints.", "Prepare approval before submitting a timed native card form. Both regions require the shared environment because test and live keys use the same endpoints."];
         readonly unsupported_variants: readonly [{
             readonly variant: "legacy_jsonp_get";
             readonly status: "unsupported";
@@ -1158,6 +1158,21 @@ export declare function getCheckoutPreflightCatalog(): {
             readonly status: "unsupported";
             readonly constraint: "direct_sdk";
             readonly reason: "Bank-account and alternative-payment token routes are outside the new-card path.";
+        }, {
+            readonly variant: "card_bound_risk_preflight";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Worldpay and Cybersource risk sessions can depend on the original card. Prepared requests refuse those results until collection can use the approved card.";
+        }, {
+            readonly variant: "prepared_co_badged_network_choice";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "A prepared request cannot reuse the original card’s network preference without checking the selected card’s supported networks.";
+        }, {
+            readonly variant: "proactive_authentication";
+            readonly status: "unsupported";
+            readonly constraint: "direct_sdk";
+            readonly reason: "Card-bearing risk authentication and proactive 3-D Secure action tokens require separate support.";
         }];
         readonly processor_amount: "none";
         readonly challenge_surface: "merchant_browser";

package/dist/preflight.generated.js

@@ -1,9 +1,9 @@
 // Generated from @agent-cards/payment-core. Do not edit.
-// source-sha256: ced5aecd22684c680a53b9e33dff1c5333cd36823f6fe3b4b8e84f10f6f73c53
+// source-sha256: 69919c5fe4133b090eddae027fb12c5ad7c51a8c63e8719325c174aeee78c30a
 import { CHECKOUT_PREFLIGHT_CAPABILITIES } from './preflight-capabilities.generated.js';
 /** Advisory page discovery. These rules never admit a payment destination. */
 export const CHECKOUT_PREFLIGHT_VERSION = '1';
-export const CHECKOUT_PREFLIGHT_CATALOG_VERSION = '2026-09-11.2';
+export const CHECKOUT_PREFLIGHT_CATALOG_VERSION = '2026-09-14.1';
 export const CHECKOUT_PREFLIGHT_LIMITS = Object.freeze({ frames: 64, signals: 2048, snapshot_bytes: 262144, url_length: 4096 });
 // Identification-only IDs, checked against the canonical catalog by the core tests.
 // No card destination, request method, or request body pattern lives here.

package/dist/prepared-processor.d.ts

@@ -1,4 +1,4 @@
-export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago';
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'recurly';
 export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
 /** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
 export declare function validPreparationEnvironment(psp: string, environment: string): boolean;

package/dist/prepared-processor.js

@@ -1,7 +1,8 @@
 import { braintreeEnvironment, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.js';
+import { isPreparedRecurlyRequest } from './recurly.generated.js';
 /** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
 export function validPreparationEnvironment(psp, environment) {
-    if (psp === 'bambora' || psp === 'mercado_pago')
+    if (psp === 'bambora' || psp === 'mercado_pago' || psp === 'recurly')
         return environment === 'shared';
     return ['square', 'braintree', 'worldpay'].includes(psp) && ['production', 'sandbox'].includes(environment);
 }
@@ -12,6 +13,8 @@ export function preparationEndpoint(psp, environment) {
         return 'https://api.bam.shift4api.net/scripts/tokenization/tokens';
     if (psp === 'mercado_pago')
         return 'https://api.mercadopago.com/v1/card_tokens';
+    if (psp === 'recurly')
+        return 'https://api.recurly.com/js/v1/token';
     if (psp === 'worldpay')
         return environment === 'production'
             ? 'https://access.worldpay.com/sessions/card' : 'https://try.access.worldpay.com/sessions/card';
@@ -70,6 +73,9 @@ export function matchesPreparedRequest(psp, environment, requestUrl, method, bod
         const request = new URL(requestUrl), endpoint = new URL(preparationEndpoint(psp, environment));
         if (request.username || request.password || request.hash)
             return false;
+        if (psp === 'recurly')
+            return [endpoint.href, 'https://api.eu.recurly.com/js/v1/token'].includes(requestUrl)
+                && isPreparedRecurlyRequest(body ?? null);
         if (psp === 'bambora') {
             if (![endpoint.href, 'https://api.na.bambora.com/scripts/tokenization/tokens'].includes(requestUrl))
                 return false;

package/dist/recurly.generated.d.ts

@@ -0,0 +1 @@
+export declare function isPreparedRecurlyRequest(body: string | null): boolean;