@agent-cards/checkout 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+- Identify hosted, regional, and versioned processor variants seen on live checkouts: Adyen secured fields on the regional live hosts and any release, the Square card element frame, dLocal Smart Fields releases, Mercado Pago secure fields and the guest Checkout Pro card form, and the Rapyd hosted checkout page. The Tranzila terminal-root page, the Authorize.Net hosted payment form, and Worldpay hosted payment pages identify their processor and return `unknown` with `processor_variant_unverified`. The catalog is `2026-09-15.1`; issue native profiles against it.
+
+- Report a sole script-only candidate as `psp` only when the observation is complete. On a partial scan the script stays in `candidates` as `undetermined`, so a co-loaded SDK is never presented as the selected processor.
+
+- Detect visible card controls in nested frames from field metadata only, never values. When those controls sit on a site no evidenced processor owns, the collector reports `card_entry_unrecognized`, the observation is incomplete, and the result stays `unknown`. Callers supplying their own observations can report the same reason.
+
+- Match discovery rules on the origin and path only. A long query string on an unrelated wallet or widget frame no longer invalidates the observation. `invalid_url` covers unparsable locations, an origin and path over `4096` characters, or a raw location over `65536` characters.
+
+- Compare committed frame URLs with committed frame URLs. A script-created frame that inherits the merchant URL through `document.open()` no longer reports `navigation_changed`; real navigations, added frames, and removed frames still do.
+
+- Read frames one nesting level at a time with up to eight frames in flight, and release frame handles while the document read proceeds. Frame-heavy checkouts over a remote CDP connection fit the default 1,500 ms budget far more often. `collection.timeoutMs` remains available for slower connections.
+
+- 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.

package/PREFLIGHT.md

@@ -93,7 +93,7 @@ The [Mollie fixture](./examples/preflight/mollie-hosted.observations.json) ident
 | `signals[].visible` | `true`, `false`, or `null` when visibility is undetermined. Do not mark scripts active merely because they loaded. |
 | `observation.complete` | Whether the scan finished without missing observations. |
 | `observation.truncated` | Whether a collection limit discarded observations. |
-| `observation.reasons` | Documented collection reason codes for an incomplete observation. |
+| `observation.reasons` | Documented collection reason codes for an incomplete observation. Report `card_entry_unrecognized` when your own collector sees visible card controls in a nested frame on a site no evidenced processor owns. |
 
 The normalized snapshot contains `schema_version: 1`, `catalog_version`, rule identifiers, frame relationships, and collection status. Raw URLs do not survive normalization. The assessment returns PSP candidates with reviewed evidence, support status and its scope, any identified flow, reason codes, and limitations. `scenario_defaulted` records whether the caller omitted the scenario and accepted `one_time`.
 
@@ -177,6 +177,8 @@ The catalog includes reviewed discovery rules and direct SDK implementation capa
 
 The bundled direct SDK profile declares processor support for `one_time` purchases. The catalog carries each processor's request limitations and known exclusions. A detection rule does not cover every product or regional variant sold under the processor's name. For example, Moneris Hosted Tokenization and Moneris Checkout use different payment paths; the implemented adapter covers Hosted Tokenization.
 
+The catalog also carries reviewed hosted, regional, and versioned variants observed on live checkouts: Adyen secured fields on the regional live hosts and any release, the Square card element frame, dLocal Smart Fields releases, Mercado Pago secure fields and the guest Checkout Pro card form, and the Rapyd hosted checkout page. A variant the implemented adapter does not admit, such as the Tranzila terminal-root page, the Authorize.Net hosted payment form, or a Worldpay hosted payment page, identifies its processor and returns `unknown` with `processor_variant_unverified`. A new fingerprint never declares payment support by itself.
+
 | Observed checkout | Classification |
 | --- | --- |
 | A compatible Stripe script, `one_time`, direct SDK | `supported` at `processor_integration` scope; `checkout_flow_status` remains `unknown`. |
@@ -184,6 +186,8 @@ The bundled direct SDK profile declares processor support for `one_time` purchas
 | A detected processor with an empty Kernel native profile | `unknown`; the native adapter has not declared processor or flow support. |
 | Competing processors without enough evidence to select one | `unknown`, with `checkout_flow_status: "ambiguous"`. |
 | An incomplete observation | `unknown`; inspect again after the checkout settles. |
+| A single processor script during an incomplete scan | `unknown`; `psp` stays `null` and the script remains in `candidates` as `undetermined` until a complete scan confirms it. |
+| Visible card controls in a nested frame on a site no evidenced processor owns | `unknown` with `card_entry_unrecognized`; a co-loaded SDK script is listed as a candidate, not as the processor. |
 
 Processor support does not establish which payment method the merchant selected. Many SDKs also load wallets or fraud checks before a card form appears. Read `checkout_flow_status` and the returned limitations alongside `status`; never present `supported` alone as a promise that a merchant purchase will succeed.
 
@@ -208,7 +212,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-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.
+The JSON contract uses `schema_version: 1`. The catalog bundled with this release uses `catalog_version: "2026-09-15.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.
 
@@ -235,7 +239,7 @@ The current inventory leaves every native runtime status `unknown`. Kernel docum
 | `checkout_flow_status: "unknown"` | The observations do not identify the exact checkout flow. Processor support can still be known. |
 | `checkout_flow_status: "ambiguous"` | Competing evidence prevents a single flow assessment. Inspect after the payment method is selected. |
 
-A loaded PSP script establishes a possible processor, not necessarily the active card flow. The helper returns candidates rather than picking the first script. A missing fingerprint does not establish lack of support.
+A loaded PSP script establishes a possible processor, not necessarily the active card flow. The helper returns candidates rather than picking the first script. A sole script candidate becomes `psp` only when the observation is complete. When a visible card-entry frame belongs to no evidenced processor's site, the collector reports `card_entry_unrecognized` and the script stays a candidate. A missing fingerprint does not establish lack of support.
 
 Every assessment is an advisory hint. The existing payment request checks still apply. A supported flow can require authentication or merchant configuration, and only the merchant's payment result establishes whether a purchase succeeded.
 
@@ -278,9 +282,10 @@ Collection reasons explain why an observation is partial:
 | `signal_limit` | Preserve `unknown` when the page exceeds the observation limit. |
 | `snapshot_limit` | Preserve `unknown` when the observations exceed the size budget. |
 | `frame_unavailable` | Inspect again after the frame is available. |
-| `navigation_changed` | Inspect the new checkout state after navigation finishes. |
+| `navigation_changed` | A frame's committed URL changed, a frame was added or removed, or an http(s) document's URL changed during the scan. A script-created frame that inherits the merchant URL is not a navigation. Inspect the new checkout state after navigation finishes. |
+| `card_entry_unrecognized` | Visible card controls sit in a nested frame on a site that no evidenced processor owns, or no processor evidence was found at all. Treat listed candidates as unconfirmed and inspect again after the payment method is selected. Identification needs a reviewed fingerprint for that frame. |
 | `invalid_observation` | Validate raw observations against the packaged schema. |
-| `invalid_url` | Correct the malformed or oversized asset location before normalization. |
+| `invalid_url` | The location could not be parsed, its origin and path exceed `4096` characters, or the raw location exceeds `65536` characters. Matching reads the origin and path only, so a long query string on an unrelated frame never invalidates an observation. |
 | `collection_incomplete` | Inspect again after the underlying collection problem is resolved. |
 
 ## Keep observations current
@@ -293,6 +298,8 @@ Collect only the documented asset observations when using your own browser tools
 
 The default collection budget is `1500` milliseconds, with at most `64` frames, `2048` signals, and `262144` serialized snapshot bytes. Set lower bounds through `collection.timeoutMs`, `collection.maxFrames`, `collection.maxSignals`, or `collection.maxSnapshotBytes` on `inspectCheckout`. The maximum time budget is `10000` milliseconds; the remaining limits cannot exceed their defaults. The minimum snapshot budget is `512` bytes.
 
+Frames are read one nesting level at a time with up to eight frames in flight, and each frame handle is released while its document read proceeds. A remote CDP connection therefore pays about three round trips per nesting level plus one per eight frames, rather than four round trips per frame. Over a remote connection, allow `3000` to `5000` milliseconds through `collection.timeoutMs`, inspect after the payment controls have loaded, and read `observation.reasons` before retrying. A longer budget cannot repair a scan that started before the checkout settled.
+
 ## Validate without a purchase
 
 The included fixture is synthetic and contains no card information. Fixture classifications validate the detector contract; they are not evidence of a real payment or of a merchant's coverage.

package/README.md

@@ -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
@@ -579,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 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 Session on `checkout.stripe.com`. Direct `authorize()` calls use `stripeCheckoutEnvironment: 'production'` for the same explicit LIVE opt-in; the attachment functions pass it automatically.
+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.
 
+When Agentcard reports `autopilot_status: action_required` for the same authorization and grant, the SDK stops waiting and calls `onUserAction` with `reason: 'other'` and the authorization ID. The checkout controller records `requires_user_action` and holds further card requests. A direct `VaultClient.authorize()` call rejects with `PaymentOutcomeUnknownError` and reason `autopilot_action_required`. The existing authorization and reservation remain held; the SDK does not cancel or create another payment, return a processor payload, or infer a 3DS challenge. Your application's `resolveMerchantResult` can report the authoritative outcome of this same payment through `reconcile()`. Challenge execution and automatic continuation are not provided by this status report.
+
 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.

package/dist/client.js

@@ -696,6 +696,21 @@ export class VaultClient {
             catch { /* observer only */ }
         };
         let failed = false;
+        let actionRequired = false;
+        const checkAutopilotAction = (state) => {
+            if (state.autopilot_status !== 'action_required')
+                return;
+            // The authenticated API reports only a verified completion category.
+            // Retain this authorization without returning its processor payload or
+            // inferring whether the required action is 3DS, a redirect, or another step.
+            if (state.id !== authorizationId || state.status !== 'awaiting_approval' || state.mode !== 'token'
+                || state.execution_mode !== 'autopilot' || execution.executionMode !== 'autopilot'
+                || state.grant_id !== execution.grantId || (input.grantId && state.grant_id !== input.grantId)) {
+                throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_action_unconfirmed');
+            }
+            actionRequired = true;
+            throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_action_required');
+        };
         const stopSignal = input.merchantSignal
             ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
         try {
@@ -706,6 +721,7 @@ export class VaultClient {
             if (input.merchantSignal?.aborted)
                 throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
             execution = executionMetadata(created, authorizationId);
+            checkAutopilotAction(created);
             deliverApproval(created);
             while (Date.now() < deadline) {
                 if (stopSignal?.aborted)
@@ -729,6 +745,7 @@ export class VaultClient {
                     throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
                 }
                 execution = executionMetadata(s, authorizationId, execution);
+                checkAutopilotAction(s);
                 if (nativeCheckout && (s.status === 'submitted_on_device' ||
                     (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'
                         || execution.grantId !== input.grantId))))
@@ -885,7 +902,9 @@ export class VaultClient {
             throw error;
         }
         finally {
-            if (input.merchantSignal?.aborted || ((preparation || nativeCheckout) && failed)) {
+            // An attested action-required result retains its claim and reservation.
+            // Reporting that state must not request cancellation of the same attempt.
+            if (!actionRequired && (input.merchantSignal?.aborted || ((preparation || nativeCheckout) && failed))) {
                 // Drain a create acknowledgement even after the merchant aborts so its
                 // known ID can be retired. An unacknowledged create remains unknown.
                 // A started/finalized replay or failed cleanup never becomes a claimed

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)
@@ -137,7 +139,12 @@ export class CheckoutLifecycle {
             return;
         }
         const authorizationId = error instanceof PaymentOutcomeUnknownError || error instanceof ProcessorRefusedError ? error.authorizationId : this.state.authorizationId;
-        if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
+        if (!handoffStarted && error instanceof PaymentOutcomeUnknownError && error.reason === 'autopilot_action_required') {
+            this.held = true;
+            this.set({ ...this.state, authorizationId, status: 'requires_user_action', reason: 'other' });
+            this.notify({ reason: 'other', authorizationId });
+        }
+        else if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
             this.held = true;
             this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
         }
@@ -195,14 +202,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.