@agent-cards/checkout 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+- 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.
+
 ## 0.9.0
 
 - Inspect checkout assets before entering card details with `collectCheckoutSignals` and `inspectCheckout`, or assess sanitized observations with `assessCheckoutSupport`. Results identify the PSP, retain evidence and report `supported`, `unsupported` or `unknown` for the selected integration.

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,6 +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. 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 |
@@ -384,6 +385,32 @@ drives that hook. Deliver `onUserAction` approval URLs privately: they are
 capabilities and never belong in general telemetry. Observer exceptions are
 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.
+
+| Field | Values |
+| --- | --- |
+| `endpoint_family` | `payment_methods`, `payment_page_confirm`, `other` |
+| `phase` | `tokenization`, `final`, `unknown` |
+| `stage` | `request_read`, `classification`, `claim`, `readiness`, `document`, `stub_response` |
+| `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
+the failure, though document validation may already have stopped the gate.
+
+`active_claim_preserved` means a valid duplicate was refused without invalidating
+the original request's claim. Do not cancel that checkout in response to the duplicate.
+`checkout_stopped` means the local preparation was retired; reconcile any existing
+authorization before another attempt. Neither disposition proves a payment outcome.
+
 With `requireMerchantResult`, subsequent card requests stay blocked after
 handoff. Stripe `/v1/payment_methods` and `/v1/tokens` handoffs always hold further
 recognized card requests, even when that option is false. A tokenization approval has no
@@ -440,8 +467,31 @@ 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.
+
+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
+
+Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout:
 
-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.
+```ts
+await controller.prepare({ psp: 'mercado_pago', environment: 'shared' });
+```
+
+The Vault checks the selected card's issuer using the merchant's current checkout configuration. Your browser receives the processor's original card-token response, and the SDK replaces the issuer in one native card association. The card number, security code and eight-digit prefix stay out of your SDK process. The encrypted relay carries the configuration lookup between the approval device and Mercado Pago.
+
+The selected card must have the same brand and card type as the native form. Missing or ambiguous configuration, changed checkout details, and a repeated card association stop continuation. Start a fresh checkout and approval after resolving the mismatch. Final Pay and merchant confirmation still follow your existing checkout integration.
+
+Use the matching SDK, API, Vault and relay releases together. The issuer correction covers the observed guest Checkout Pro flow in Mexico. CardForm or Bricks on merchant websites, other countries, installment changes and Autopilot need separate validation. Successful tokenization and issuer association do not establish a paid order; keep `requireMerchantResult` and a merchant receipt resolver when validating a purchase.
 
 Braintree's native `ClientConfiguration` GraphQL query can run before, during or after preparation without using the approval. Only a single `TokenizeCreditCard` mutation can consume the prepared Braintree checkout. Prepared requests require guest card tokenization with explicit `options.validate: false`; omitted validation options, saved-card fields and `validate: true` are refused. Other GraphQL operations, batches and compound mutations are blocked. Braintree's legacy REST fallback cannot consume a prepared authorization.
 
@@ -529,4 +579,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.
+
+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.
+
+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.d.ts

@@ -1,4 +1,5 @@
 import { type VaultClient, type ExecutionMetadata } from './client.js';
+import { type StripeCheckoutOptions } from './stripe-checkout.js';
 import { type CheckoutController, type LifecycleOptions, type PaymentEndpointGuard } from './lifecycle.js';
 /**
  * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
@@ -72,6 +73,8 @@ export interface CdpLike {
     on(handler: (method: string, params: any, sessionId?: string) => void): void;
 }
 export interface AttachOptions extends LifecycleOptions, ExecutionMetadata {
+    /** Explicit native hosted Stripe Checkout TEST integration; requires an Autopilot grant. */
+    stripeCheckout?: StripeCheckoutOptions;
     /** Fallback when the browser cannot expose its top-level origin. Never an amount/payee authority. */
     merchantOrigin?: string;
     vault: VaultClient;

package/dist/cdp.js

@@ -2,6 +2,9 @@ import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
 import { PreparationGate } from './preparation.js';
 import { classifyBraintreeRequest } from './braintree.js';
+import { StripeCheckoutGate, StripeCheckoutClaimConflictError, stripeCheckoutReadinessError } from './stripe-checkout.js';
+import { MercadoCheckoutGate } from './mercado-checkout.js';
+import { MERCADO_CHECKOUT_PATTERN } from './mercado-checkout.generated.js';
 import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
@@ -407,6 +410,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let attachmentReady = false;
     let setupFailureReported = false;
     const lifecycle = new CheckoutLifecycle(opts);
+    const stripeCheckout = new StripeCheckoutGate(opts);
+    const mercadoCheckout = new MercadoCheckoutGate();
     let preparationFrameId;
     const readDocumentUrl = async () => {
         const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
@@ -431,7 +436,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
     const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
-    const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns])];
+    const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns,
+            ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN])];
     const arm = async (sessionId, resume = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
@@ -478,6 +484,11 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     cdp.on(async (method, params, sessionId) => {
         if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
             preparationGate.invalidate('merchant_document_changed');
+            mercadoCheckout.invalidate();
+            if (stripeCheckout.isPrepared()) {
+                stripeCheckout.invalidate();
+                activeRequest?.attempt.stop();
+            }
             if (preparationGate.isEngaged())
                 activeRequest?.attempt.stop();
             return;
@@ -486,6 +497,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
             setupStop.abort(new CheckoutAttachmentError('closed'));
             preparationGate.invalidate('merchant_document_closed');
+            stripeCheckout.invalidate();
+            mercadoCheckout.invalidate();
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
         }
@@ -526,6 +539,31 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         if (method !== 'Fetch.requestPaused')
             return;
         const { requestId, request, resourceType, networkId, frameId } = params;
+        if (mercadoCheckout.matches(request.url) && !['GET', 'HEAD', 'OPTIONS'].includes(request.method)) {
+            try {
+                if (!attachmentReady || setupStop.signal.aborted || lifecycle.abort.signal.aborted || terminal)
+                    throw new Error('checkout_interception_not_ready');
+                const body = pausedBody(request) ?? '';
+                if (await mercadoCheckout.configuration(request.url, request.method, body, readDocumentUrl)) {
+                    await cdp.send('Fetch.continueRequest', { requestId }, sessionId);
+                    return;
+                }
+                const postData = mercadoCheckout.associationBody(request.url, request.method, body, await readDocumentUrl());
+                if (postData !== undefined) {
+                    if (setupStop.signal.aborted || lifecycle.abort.signal.aborted)
+                        throw new Error('checkout_interception_not_ready');
+                    await cdp.send('Fetch.continueRequest', { requestId, postData: Buffer.from(postData).toString('base64') }, sessionId);
+                    return;
+                }
+            }
+            catch {
+                mercadoCheckout.invalidate();
+                lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'mercado_checkout_continuation_stopped'));
+                opts.onEvent?.({ type: 'blocked', detail: 'mercado_checkout_continuation_stopped' });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                return;
+            }
+        }
         // Braintree shares /graphql between configuration and card mutations.
         // Classify before URL-only recognition or claiming a prepared request.
         const braintree = request.method.toUpperCase() === 'POST'
@@ -539,7 +577,57 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
-        if (!opts.vault.isCardRequest(request.url, request.method)) {
+        let stripeStep = null;
+        let stripeStage = 'request_read', stripeUrl = '';
+        try {
+            if (stripeCheckout.isEnabled()) {
+                stripeUrl = request.url;
+                const nativeRequest = { url: stripeUrl, method: request.method,
+                    headers: request.headers, body: pausedBody(request) ?? '' };
+                stripeStage = 'classification';
+                stripeStep = stripeCheckout.claim(nativeRequest);
+            }
+            if (stripeStep) {
+                stripeStage = 'readiness';
+                if (!attachmentReady || arming.has(sessionId ?? '__root__'))
+                    throw stripeCheckoutReadinessError('attachment_not_ready');
+                if (setupStop.signal.aborted)
+                    throw stripeCheckoutReadinessError('cancelled');
+                if (terminal || lifecycle.isBlocked())
+                    throw stripeCheckoutReadinessError(lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
+                if (awaitingApproval)
+                    throw stripeCheckoutReadinessError('approval_pending');
+                stripeStage = 'document';
+                stripeCheckout.assertDocument(await readDocumentUrl());
+                stripeStage = 'claim';
+                stripeCheckout.assertClaim(stripeStep);
+                stripeStage = 'readiness';
+                if (setupStop.signal.aborted)
+                    throw stripeCheckoutReadinessError('cancelled');
+                if (lifecycle.isBlocked())
+                    throw stripeCheckoutReadinessError(lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
+                if (stripeStep.phase === 'tokenization') {
+                    stripeStage = 'stub_response';
+                    const response = stripeStep.response;
+                    await cdp.send('Fetch.fulfillRequest', { requestId, responseCode: response.status,
+                        responseHeaders: Object.entries(withCorsHeaders(response.headers, corsHeadersFor(request.url, request.headers)))
+                            .map(([name, value]) => ({ name, value })),
+                        body: Buffer.from(response.body).toString('base64') }, sessionId);
+                    opts.onEvent?.({ type: 'checkout_prepared', detail: { processor: 'stripe' } });
+                    return;
+                }
+            }
+        }
+        catch (error) {
+            const detail = stripeCheckout.describeRejection(error, stripeUrl, stripeStage, stripeStep?.phase);
+            if (!(error instanceof StripeCheckoutClaimConflictError))
+                stripeCheckout.invalidate();
+            opts.onEvent?.({ type: 'checkout_blocked', detail });
+            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
+        if (!stripeStep && !opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
                 preparationGate.invalidate('unsupported_checkout');
                 lifecycle.unsupported();
@@ -557,7 +645,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url, pausedBody(request));
+            preparation = stripeStep ? undefined : preparationGate.claim(request.url, pausedBody(request));
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -610,6 +698,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             const pageOrigin = await pageOriginOf(readDocumentUrl, attempt.signal);
             const pageAmount = await pageAmountOf(opts);
             attempt.assertLive();
+            if (stripeStep)
+                stripeCheckout.assertClaim(stripeStep);
             const merchantOrigin = preparation?.merchantOrigin ?? (opts.executionMode === 'user_approval'
                 ? opts.merchantOrigin : pageOrigin?.startsWith('https:') ? pageOrigin : opts.merchantOrigin);
             attempt.assertLive();
@@ -621,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,
@@ -633,11 +724,20 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     lifecycle.approvalUrl(url);
                     return opts.onApprovalUrl?.(url);
                 } },
-                request: { url: request.url, method: request.method, headers: request.headers, body },
+                request: stripeStep?.phase === 'final' ? stripeStep.request : { url: request.url, method: request.method, headers: request.headers, body,
+                    ...(mercadoCheckout.requiresDocument(request.url, request.method)
+                        ? { mercado_checkout: mercadoCheckout.claimToken(request.url, request.method, await readDocumentUrl()) } : {}) },
             });
             attempt.assertLive();
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
+            try {
+                await mercadoCheckout.arm(replay, request.url);
+            }
+            catch {
+                throw new PaymentOutcomeUnknownError(replay.authorizationId, 'mercado_checkout_metadata_invalid');
+            }
+            attempt.assertLive();
             lifecycle.prepareHandoff(replay, request.url);
             handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
@@ -758,6 +858,8 @@ export async function attachToPlaywright(page, opts) {
         throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
     }
     const lifecycle = new CheckoutLifecycle(opts);
+    const stripeCheckout = new StripeCheckoutGate(opts);
+    const mercadoCheckout = new MercadoCheckoutGate();
     const readDocumentUrl = async () => {
         if (page.isClosed?.() || typeof page.url !== 'function')
             throw new Error('merchant_document_unavailable');
@@ -790,12 +892,17 @@ export async function attachToPlaywright(page, opts) {
             activeRequest.attempt.stop();
     });
     page.on?.('close', () => { if (!attachmentReady)
-        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); });
     page.on?.('crash', () => { if (!attachmentReady)
-        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); });
     page.on?.('framenavigated', (frame) => {
         if (frame === page.mainFrame?.()) {
             preparationGate.invalidate('merchant_document_changed');
+            mercadoCheckout.invalidate();
+            if (stripeCheckout.isPrepared()) {
+                stripeCheckout.invalidate();
+                activeRequest?.attempt.stop();
+            }
             if (preparationGate.isEngaged())
                 activeRequest?.attempt.stop();
         }
@@ -813,8 +920,30 @@ export async function attachToPlaywright(page, opts) {
             setupStop.abort(failure);
             throw failure;
         }
-        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
+        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()) || stripeCheckout.matches(url.toString()) || mercadoCheckout.matches(url.toString()), async (route) => {
             const request = route.request();
+            if (mercadoCheckout.matches(request.url()) && !['GET', 'HEAD', 'OPTIONS'].includes(request.method())) {
+                try {
+                    if (!attachmentReady || setupStop.signal.aborted || lifecycle.abort.signal.aborted || terminal)
+                        throw new Error('checkout_interception_not_ready');
+                    const body = request.postData() ?? '';
+                    if (await mercadoCheckout.configuration(request.url(), request.method(), body, readDocumentUrl))
+                        return route.fallback();
+                    const postData = mercadoCheckout.associationBody(request.url(), request.method(), body, await readDocumentUrl());
+                    if (postData !== undefined) {
+                        if (setupStop.signal.aborted || lifecycle.abort.signal.aborted || page.isClosed?.())
+                            throw new Error('checkout_interception_not_ready');
+                        await route.continue({ postData });
+                        return;
+                    }
+                }
+                catch {
+                    mercadoCheckout.invalidate();
+                    lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'mercado_checkout_continuation_stopped'));
+                    opts.onEvent?.({ type: 'blocked', detail: 'mercado_checkout_continuation_stopped' });
+                    return route.abort('aborted');
+                }
+            }
             const braintree = request.method().toUpperCase() === 'POST'
                 ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
             if (braintree === 'configuration')
@@ -825,7 +954,55 @@ export async function attachToPlaywright(page, opts) {
             }
             // The matcher only sees the URL; a preflight or a GET must pass through
             // untouched or the browser's CORS check fails on our synthetic answer.
-            if (!opts.vault.isCardRequest(request.url(), request.method())) {
+            let stripeStep = null;
+            let stripeStage = 'request_read', stripeUrl = '';
+            try {
+                if (stripeCheckout.isEnabled()) {
+                    stripeUrl = request.url();
+                    const nativeRequest = { url: stripeUrl, method: request.method(), headers: request.headers(), body: request.postData() ?? '' };
+                    stripeStage = 'classification';
+                    stripeStep = stripeCheckout.claim(nativeRequest);
+                }
+                if (stripeStep) {
+                    stripeStage = 'readiness';
+                    if (!attachmentReady)
+                        throw stripeCheckoutReadinessError('attachment_not_ready');
+                    if (setupStop.signal.aborted)
+                        throw stripeCheckoutReadinessError('cancelled');
+                    if (terminal || lifecycle.isBlocked())
+                        throw stripeCheckoutReadinessError(lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
+                    if (awaitingApproval)
+                        throw stripeCheckoutReadinessError('approval_pending');
+                    stripeStage = 'document';
+                    stripeCheckout.assertDocument(await readDocumentUrl());
+                    stripeStage = 'claim';
+                    stripeCheckout.assertClaim(stripeStep);
+                    stripeStage = 'readiness';
+                    if (setupStop.signal.aborted)
+                        throw stripeCheckoutReadinessError('cancelled');
+                    if (lifecycle.isBlocked())
+                        throw stripeCheckoutReadinessError(lifecycle.isCancelled() ? 'cancelled' : 'checkout_inactive');
+                    if (page.isClosed?.() || request.failure?.())
+                        throw stripeCheckoutReadinessError('request_inactive');
+                    if (stripeStep.phase === 'tokenization') {
+                        stripeStage = 'stub_response';
+                        const response = stripeStep.response;
+                        await route.fulfill({ ...response,
+                            headers: withCorsHeaders(response.headers, corsHeadersFor(request.url(), request.headers())) });
+                        opts.onEvent?.({ type: 'checkout_prepared', detail: { processor: 'stripe' } });
+                        return;
+                    }
+                }
+            }
+            catch (error) {
+                const detail = stripeCheckout.describeRejection(error, stripeUrl, stripeStage, stripeStep?.phase);
+                if (!(error instanceof StripeCheckoutClaimConflictError))
+                    stripeCheckout.invalidate();
+                opts.onEvent?.({ type: 'checkout_blocked', detail });
+                opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+                return route.abort('aborted');
+            }
+            if (!stripeStep && !opts.vault.isCardRequest(request.url(), request.method())) {
                 if (guards.matches(request.url(), request.method())) {
                     preparationGate.invalidate('unsupported_checkout');
                     lifecycle.unsupported();
@@ -840,7 +1017,7 @@ export async function attachToPlaywright(page, opts) {
             }
             let preparation;
             try {
-                preparation = preparationGate.claim(request.url(), request.postData() ?? '');
+                preparation = stripeStep ? undefined : preparationGate.claim(request.url(), request.postData() ?? '');
             }
             catch (error) {
                 opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -887,6 +1064,8 @@ export async function attachToPlaywright(page, opts) {
                 const pageOrigin = await pageOriginOf(readDocumentUrl, attempt.signal);
                 const pageAmount = await pageAmountOf(opts);
                 assertRequestLive();
+                if (stripeStep)
+                    stripeCheckout.assertClaim(stripeStep);
                 const merchantOrigin = preparation?.merchantOrigin ?? (opts.executionMode === 'user_approval'
                     ? opts.merchantOrigin : pageOrigin?.startsWith('https:') ? pageOrigin : opts.merchantOrigin);
                 assertRequestLive();
@@ -898,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,
@@ -910,11 +1090,20 @@ export async function attachToPlaywright(page, opts) {
                         lifecycle.approvalUrl(url);
                         return opts.onApprovalUrl?.(url);
                     } },
-                    request: { url: request.url(), method: request.method(), headers: request.headers(), body },
+                    request: stripeStep?.phase === 'final' ? stripeStep.request : { url: request.url(), method: request.method(), headers: request.headers(), body,
+                        ...(mercadoCheckout.requiresDocument(request.url(), request.method())
+                            ? { mercado_checkout: mercadoCheckout.claimToken(request.url(), request.method(), await readDocumentUrl()) } : {}) },
                 });
                 assertRequestLive();
                 if (lifecycle.isCancelled())
                     throw new Error('checkout cancelled locally after approval');
+                try {
+                    await mercadoCheckout.arm(replay, request.url());
+                }
+                catch {
+                    throw new PaymentOutcomeUnknownError(replay.authorizationId, 'mercado_checkout_metadata_invalid');
+                }
+                assertRequestLive();
                 lifecycle.prepareHandoff(replay, request.url());
                 handoffStarted = replay.mode !== 'cse';
                 if (replay.mode === 'hosted_form') {

package/dist/client.d.ts

@@ -6,6 +6,8 @@ export interface PausedRequest {
     method: string;
     headers: Record<string, string>;
     body: string;
+    /** Captured native Checkout Pro initialization, validated before use. */
+    mercado_checkout?: unknown;
 }
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
@@ -39,6 +41,10 @@ export interface ExecutionMetadata {
  * this is the processor's answer to replay into the paused request.
  */
 export interface TokenReplay extends ExecutionMetadata {
+    /** Authenticated selected-card metadata; the processor response body stays unchanged. */
+    processorContext?: unknown;
+    /** Present only after validating the native TEST Checkout completion. */
+    checkoutSessionId?: string;
     /** Present only after validating the explicit owned-shop purchase receipt. */
     shopOrderId?: string;
     /** Absent on older API versions; always 'token' here. */
@@ -160,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. */