@agent-cards/checkout 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- 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/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. A completed merchant payment remains 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
@@ -443,6 +470,20 @@ await page.getByRole('button', { name: 'Pay', exact: true }).click();
 
 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.
 
+### Use Checkout Pro in Mexico
+
+Attach the SDK before entering card fields on `www.mercadopago.com.mx`, then prepare the guest card checkout:
+
+```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.
 
 Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, changes native request deadlines, or automatically retries a failed prepared checkout.
@@ -529,4 +570,10 @@ 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`.
+
+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 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();
@@ -633,11 +723,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 +857,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 +891,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 +919,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 +953,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 +1016,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 +1063,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();
@@ -910,11 +1088,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. */

package/dist/client.js

@@ -1,6 +1,8 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
+import { isMercadoTokenRequest, parseMercadoCheckoutContext, validateMercadoProcessorContext } from './mercado-checkout.generated.js';
 import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-processor.js';
 import { hasOwnedShopMarker, parseOwnedShopOrder, parseOwnedShopReceipt } from './owned-shop.generated.js';
+import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
@@ -513,6 +515,24 @@ export class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        const mercadoContext = input.request.mercado_checkout === undefined ? undefined : parseMercadoCheckoutContext(input.request.mercado_checkout);
+        if (mercadoContext && (!isMercadoTokenRequest(input.request.url, input.request.method)
+            || input.executionMode === 'autopilot' || input.grantId))
+            throw new Error('mercado_checkout_context_invalid');
+        const nativeCheckout = hasStripeCheckoutMarker(input.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.');
+            const phase = classifyStripeCheckoutRequest(input.request, {
+                sessionId: checkoutContext.session_id, syntheticPaymentMethodId: checkoutContext.synthetic_payment_method_id,
+                amountCents: input.amount,
+            });
+            if (phase?.phase !== 'final')
+                throw new Error('Native Stripe Checkout request is not prepared.');
+        }
         const ownedShop = hasOwnedShopMarker(input.request);
         const shopOrder = ownedShop ? parseOwnedShopOrder(input.request) : null;
         if (ownedShop) {
@@ -551,7 +571,8 @@ export class VaultClient {
             throw new CheckoutCancelledError();
         if (input.merchantSignal?.aborted)
             throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-        const rec = findRecognizer(input.request.url, this.registry);
+        const rec = nativeCheckout ? this.registry.find(entry => entry.psp === 'stripe' && (entry.mode ?? 'token') === 'token')
+            : findRecognizer(input.request.url, this.registry);
         if (!rec)
             throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
         // A client-side-encrypted processor is only takeable when its entry says
@@ -614,8 +635,10 @@ export class VaultClient {
             request: {
                 url: input.request.url,
                 method: input.request.method,
-                headers: pickHeaders(input.request.headers, rec.passthroughHeaders),
+                headers: { ...pickHeaders(input.request.headers, rec.passthroughHeaders),
+                    ...(checkoutContext ? { [STRIPE_CHECKOUT_CONTEXT_HEADER]: encodeStripeCheckoutContext(checkoutContext) } : {}) },
                 body: input.request.body,
+                ...(mercadoContext ? { mercado_checkout: mercadoContext } : {}),
             },
         };
         try {
@@ -650,10 +673,16 @@ export class VaultClient {
         if (!created || typeof created.id !== 'string' || !created.id)
             throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_malformed');
         const authorizationId = created.id;
+        // A prepared Mercado token already has the person's approval. Poll its
+        // result promptly while the native SDK waits: at the default interval,
+        // 10 seconds has at most 20 reads instead of 5 (15 additional reads).
+        // Then restore the caller's interval. Human approval waiting, cancellation,
+        // merchant deadlines, and the single processor request remain unchanged.
+        const preparedMercadoPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000 : 0;
         let execution = {};
         let approvalDelivered = false;
         const deliverApproval = (state) => {
-            if (ownedShop || preparation || approvalDelivered || execution.executionMode === 'autopilot')
+            if (ownedShop || nativeCheckout || preparation || approvalDelivered || execution.executionMode === 'autopilot')
                 return;
             const url = state.approvalUrl ?? state.approval_url;
             if (typeof url !== 'string' || !url)
@@ -679,7 +708,8 @@ export class VaultClient {
             while (Date.now() < deadline) {
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
-                await interruptibleSleep(Math.min(this.pollIntervalMs, Math.max(0, deadline - Date.now())), stopSignal);
+                const pollInterval = Date.now() < preparedMercadoPollUntil ? Math.min(this.pollIntervalMs, 500) : this.pollIntervalMs;
+                await interruptibleSleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())), stopSignal);
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
                 let s;
@@ -697,6 +727,10 @@ export class VaultClient {
                     throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
                 }
                 execution = executionMetadata(s, authorizationId, execution);
+                if (nativeCheckout && (s.status === 'submitted_on_device' ||
+                    (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'
+                        || execution.grantId !== input.grantId))))
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'checkout_receipt_unconfirmed');
                 if (shopOrder && (s.status === 'submitted_on_device' ||
                     (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'))))
                     throw new PaymentOutcomeUnknownError(authorizationId, 'shop_receipt_unconfirmed');
@@ -777,11 +811,36 @@ export class VaultClient {
                         response.body = JSON.stringify(receipt);
                         response.headers = { 'content-type': 'application/json' };
                     }
+                    if (checkoutContext) {
+                        let receipt;
+                        try {
+                            receipt = parseStripeCheckoutResponse(JSON.parse(response.body), { sessionId: checkoutContext.session_id });
+                        }
+                        catch { /* Never return an unvalidated processor body to the page. */ }
+                        if (response.status !== 200 || !receipt || s.amount_verified !== true
+                            || s.charged_amount !== input.amount || s.charged_currency !== 'usd' || s.charged_kind !== 'captured')
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'checkout_receipt_unconfirmed');
+                        response.body = JSON.stringify(receipt);
+                        response.headers = { 'content-type': 'application/json' };
+                    }
+                    let processorContext;
+                    if (mercadoContext) {
+                        try {
+                            processorContext = await validateMercadoProcessorContext(s.processor_context, mercadoContext, input.request.url, response.body);
+                        }
+                        catch {
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'mercado_checkout_metadata_invalid');
+                        }
+                    }
+                    else if (s.processor_context !== undefined)
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'unexpected_processor_context');
                     return {
                         mode: 'token',
                         authorizationId,
                         ...(shopOrder ? { shopOrderId: shopOrder.order_id } : {}),
+                        ...(checkoutContext ? { checkoutSessionId: checkoutContext.session_id } : {}),
                         ...response,
+                        ...(processorContext ? { processorContext } : {}),
                         amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
                         chargedAmount: typeof s.charged_amount === 'number' ? s.charged_amount : null,
                         chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
@@ -824,7 +883,7 @@ export class VaultClient {
             throw error;
         }
         finally {
-            if (input.merchantSignal?.aborted || (preparation && failed)) {
+            if (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

@@ -3,6 +3,7 @@ export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormR
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { CheckoutAttachmentError } from './attachment.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
+export type { StripeCheckoutOptions, StripeCheckoutBlockedDetail, StripeCheckoutBlockStage, StripeCheckoutBlockReason } from './stripe-checkout.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';

package/dist/mercado-checkout.d.ts

@@ -0,0 +1,20 @@
+import type { ReplayResponse } from './client.js';
+/** Capture only the native Checkout Pro configuration. A late configuration,
+ * navigation or repeated token cannot replace the context of an issued token.
+ * Final payment requests retain the attachment's existing payment guards.
+ */
+export declare class MercadoCheckoutGate {
+    private context;
+    private started;
+    private stopped;
+    private sequence;
+    private associatedFlow;
+    private association;
+    matches(url: string): boolean;
+    requiresDocument(url: string, method: string): boolean;
+    invalidate(): void;
+    configuration(url: string, method: string, body: string, readDocument: () => Promise<string>): Promise<boolean>;
+    claimToken(url: string, method: string, documentUrl: string): unknown;
+    arm(replay: ReplayResponse, tokenUrl: string): Promise<void>;
+    associationBody(url: string, method: string, body: string, documentUrl: string): string | undefined;
+}