@agent-cards/checkout 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0
+
+- Recognize Paysafe Checkout 1.8's exact hosted tokenization endpoints and preserve its native credential and correlation headers. The matching API registry and Vault deployment are required.
+- Recognize Checkout.com card tokenization at `card-acquisition-gateway.checkout.com/tokens` and its sandbox counterpart alongside the existing API hosts. The matching backend registry and Vault deployment are required; this entry does not establish native merchant payment completion.
+- Prepare Worldpay, Bambora and Mercado Pago checkout before the merchant's first Pay action. Use `psp: 'worldpay'` with `environment: 'production' | 'sandbox'`, or `psp: 'bambora' | 'mercado_pago'` with `environment: 'shared'`. Shared endpoints do not establish processor test mode. The merchant's credentials and checkout configuration determine that mode.
+- Keep the existing selected-card, merchant, document, amount, currency and one-use consent checks. The native request begins only after approval, and approval readiness lasts at most 30 seconds. The SDK does not extend processor deadlines or automatically retry after payment uncertainty. Matching API, Vault and preparation migration are required.
+- Bound Playwright and CDP setup with `attachmentTimeoutMs`, defaulting to 30 seconds. A stalled setup throws a sanitized `CheckoutAttachmentError`; late acknowledgements cannot start approval or retry setup, and concurrent setup failures report once. Close the failed checkout page and start a fresh context before trying again.
+- Preserve the original setup failure across attached frames: a transport failure reports `unavailable`, a deadline reports `timeout`, and an observed page closure reports `closed`.
+- Reject processor URLs with credentials or nondefault ports consistently across SDK and API discovery. Registry synchronization updates endpoint recognition; upgrading the SDK is required for the new preparation and setup behavior.
+
+The matching Vault/API release adds Mollie card-token and supported Airwallex intent-confirmation replay through browser-owned TLS, preserves Worldpay's native session media type and Bambora's `cvd` field, and reports Nuvei's unambiguous validation error as processor refusal. Local regression and Chromium fixture results do not establish native processor acceptance or a completed merchant purchase.
+
 ## 0.5.0
 
 - Prepare Braintree card checkout with `controller.prepare({ psp: 'braintree', environment: 'production' | 'sandbox' })` before the merchant's first Pay action. The cardholder approves and unlocks first; one fresh native request then uses that approval without another notification. The matching API and Vault release is required.

package/README.md

@@ -130,7 +130,7 @@ Coverage is specific to the processor request format, merchant setup, browser tr
 |---|---|
 | Shopify | supported, verified end to end |
 | Stripe | tokenization replay and direct card-bearing PaymentIntent confirms are implemented; direct confirms with `amountCents` + `currency` use backend amount verification. Browser token-to-intent continuation is unsupported and held. Validate the exact merchant flow before pilot use |
-| Braintree card tokenization | prepared checkout supported; production paid-order validation pending |
+| 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 |
 | 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 |
@@ -327,6 +327,16 @@ Playwright `CDPSession` is not the `CdpLike` interface. Raw CDP must preserve th
 Initial arming errors reject `attachToCdp`; a child that cannot be armed remains
 paused and reports `browser_interception_unavailable` for operator recovery.
 
+Await attachment before clicking Pay. Both adapters stop waiting for browser
+setup after 30 seconds and throw `CheckoutAttachmentError` with
+`code: 'checkout_attachment_failed'` and `reason: 'timeout'`, `'closed'` or
+`'unavailable'`. Use `attachmentTimeoutMs` to choose a setup deadline from 1 to
+300000 milliseconds, separately from the approval's `timeoutMs`.
+Close the failed checkout page and create a fresh browser context before
+trying again. A late setup response cannot reopen the failed attachment or
+request approval; intercepted card requests remain blocked. A setup failure
+does not establish the status of any earlier purchase.
+
 Use a checkout context created with `serviceWorkers: 'block'`. Playwright cannot
 route requests intercepted by a service worker. The SDK rejects already active
 service workers, but that check cannot prevent a site from registering one
@@ -400,7 +410,9 @@ do not reuse that token in a new attachment as a workaround. Configuration and
 unsupported-mode failures require fixing the integration. Bank flows requiring
 another confirmation and other stored-token chains remain unverified.
 
-Prepare a Square or Braintree checkout before the first Pay action so the cardholder can approve before the native card request starts. The API and Vault deployments must support the selected processor:
+Worldpay, Bambora and Mercado Pago preparation requires SDK 0.6.0 or later and the matching API and Vault release.
+
+Prepare a Square, Braintree, Worldpay, Bambora or Mercado Pago checkout before the first Pay action so the cardholder can approve before the native card request starts. The API and Vault deployments must support the selected processor:
 
 ```ts
 const checkout = await attachToPlaywright(page, {
@@ -409,8 +421,8 @@ const checkout = await attachToPlaywright(page, {
   onApprovalUrl: deliverPrivatelyToCardholder,
 });
 const preparation = await checkout.prepare({
-  psp: 'braintree', // use 'square' for Square
-  environment: 'production', // explicit; use 'sandbox' for the processor's sandbox
+  psp: 'braintree',
+  environment: 'production', // Square, Braintree and Worldpay: production or sandbox
 });
 // The cardholder has consented and unlocked the same approval document.
 // No processor request or payment has started.
@@ -419,6 +431,16 @@ await page.getByRole('button', { name: 'Pay', exact: true }).click();
 
 `prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency, processor and environment bind one fresh request. The amount remains `display_only`; a card token does not enforce the merchant's eventual charge amount.
 
+| Processor | `environment` | Fresh native request |
+| --- | --- | --- |
+| Square | `production` or `sandbox` | Matching Square `/v2/card-nonce` host |
+| Braintree | `production` or `sandbox` | Matching Braintree GraphQL host and guest `TokenizeCreditCard` mutation |
+| 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 |
+
+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.
+
 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.
@@ -472,9 +494,7 @@ The browser fixtures never contact a payment service. The general suite uses
 allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
 `openssl` CLI). All other proxy destinations are rejected. These suites use an
 in-process Agentcard API fixture and loopback merchant pages. The preparation
-fixture denies all external traffic, waits more than ten seconds before any
-card request, and then checks one fresh request with an unchanged ten-second
-fixture abort timer. It exercises SDK ordering, not the native Square SDK. It proves nested-frame pause/resume, agent control during approval,
+fixture denies all external traffic and waits beyond each modeled request deadline before any card request: eleven seconds for Square, sixty-one seconds for Braintree, and six and a half seconds for Worldpay, Bambora and Mercado Pago. Each fixture then checks one fresh request with an unchanged abort timer. The five-second timer matches the inspected Worldpay and Bambora source; the Mercado Pago timer is a test boundary, not a measured native deadline. The fixture exercises SDK ordering with native-shaped request bodies and synthetic responses, not processor acceptance. It proves nested-frame pause/resume, agent control during approval,
 post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
 blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
 Stripe token-to-intent fetch chain, including unrelated first intents, changed

package/dist/attachment.d.ts

@@ -0,0 +1,11 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export declare class CheckoutAttachmentError extends Error {
+    readonly reason: 'timeout' | 'closed' | 'unavailable';
+    readonly code = "checkout_attachment_failed";
+    constructor(reason: 'timeout' | 'closed' | 'unavailable');
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export declare function attachmentFailure(error: unknown): CheckoutAttachmentError;
+export declare function attachmentDeadline(value: number | undefined): number;
+/** Stop waiting, then reject every late continuation before its next command. */
+export declare function withinAttachmentDeadline(arm: (assertActive: () => void) => Promise<void>, timeoutMs: number, signal: AbortSignal): Promise<void>;

package/dist/attachment.js

@@ -0,0 +1,50 @@
+/** An attachment failure has no payment or browser credentials in its message. */
+export class CheckoutAttachmentError extends Error {
+    reason;
+    code = 'checkout_attachment_failed';
+    constructor(reason) {
+        super('Could not attach checkout interception. Close this checkout page and retry in a fresh browser context.');
+        this.reason = reason;
+        this.name = 'CheckoutAttachmentError';
+    }
+}
+/** Preserve a known setup cause without exposing raw transport errors. */
+export function attachmentFailure(error) {
+    return error instanceof CheckoutAttachmentError ? error : new CheckoutAttachmentError('unavailable');
+}
+export function attachmentDeadline(value) {
+    if (value === undefined)
+        return 30_000;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 300_000) {
+        throw new Error('attachmentTimeoutMs must be an integer between 1 and 300000.');
+    }
+    return value;
+}
+/** Stop waiting, then reject every late continuation before its next command. */
+export async function withinAttachmentDeadline(arm, timeoutMs, signal) {
+    let stopped;
+    let timer;
+    let onAbort = () => { };
+    const assertActive = () => { if (stopped)
+        throw stopped; };
+    const deadline = new Promise((_resolve, reject) => {
+        const stop = (failure) => { stopped ??= failure; reject(stopped); };
+        onAbort = () => stop(attachmentFailure(signal.reason));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        else
+            timer = setTimeout(() => stop(new CheckoutAttachmentError('timeout')), timeoutMs);
+    });
+    try {
+        await Promise.race([deadline, Promise.resolve().then(() => { assertActive(); return arm(assertActive); })]);
+    }
+    catch (error) {
+        stopped ??= attachmentFailure(error);
+        throw stopped;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', onAbort);
+    }
+}

package/dist/braintree.d.ts

@@ -2,6 +2,8 @@
 export type BraintreeEnvironment = 'production' | 'sandbox';
 export type BraintreeRequestKind = 'configuration' | 'tokenization' | 'invalid';
 export declare function braintreeEnvironment(url: string): BraintreeEnvironment | undefined;
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export declare function readTokenizationJson(body: string | null): Record<string, unknown> | null;
 /** Undefined belongs to another processor; invalid Braintree requests stay blocked. */
 export declare function classifyBraintreeRequest(url: string, method: string, body: string | null): BraintreeRequestKind | undefined;
 /** Preparation accepts guest tokenization only; ordinary interception stays broader. */

package/dist/braintree.js

@@ -115,6 +115,18 @@ class JsonReader {
         return value;
     }
 }
+/** Bounded duplicate-aware JSON for fresh-card preparation bodies. */
+export function readTokenizationJson(body) {
+    if (typeof body !== 'string' || body.length === 0 || body.length > MAX_BODY_LENGTH)
+        return null;
+    try {
+        const value = new JsonReader(body).read();
+        return record(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Native operations need names, punctuation and variables, never literals. */
 function lex(query) {
     const tokens = [];

package/dist/cdp.d.ts

@@ -87,6 +87,8 @@ export interface AttachOptions extends LifecycleOptions {
     currency?: string;
     cardId?: string;
     timeoutMs?: number;
+    /** Browser interception setup deadline, separate from approval. Defaults to 30000 ms; maximum 300000 ms. */
+    attachmentTimeoutMs?: number;
     /** Explicit payment endpoints to block if the registry cannot handle their method/format. Unlisted traffic is untouched. */
     paymentEndpoints?: readonly PaymentEndpointGuard[];
     onApprovalUrl?: (url: string) => void;

package/dist/cdp.js

@@ -2,6 +2,7 @@ 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 { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -328,6 +329,10 @@ function merchantAttempt(lifecycle) {
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
+    let setupFailureReported = false;
     const lifecycle = new CheckoutLifecycle(opts);
     let preparationFrameId;
     const preparationGate = new PreparationGate(opts, lifecycle, async () => {
@@ -339,6 +344,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
+    const arming = new Map();
     // Set once a failure proves that retrying cannot help; see isTerminal.
     let terminal = null;
     // Silence window after a person declined or ignored one; see APPROVAL_COOLDOWN_MS.
@@ -352,23 +358,48 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     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])];
-    opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
-    const arm = async (sessionId) => {
+    const arm = async (sessionId, resume = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
+        if (arming.has(key))
+            return arming.get(key);
         // Fetch's interception ID differs from Network's ID. Enable failure events
         // before intercepting and bind each attempt to both its ID and CDP session.
-        await cdp.send('Network.enable', {}, sessionId);
-        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
-        await cdp.send('Fetch.enable', {
-            patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-        }, sessionId);
-        // Descend into this target's own children (iframes inside iframes).
-        await cdp.send('Target.setAutoAttach', {
-            autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
-        }, sessionId);
-        armed.add(key);
+        const pending = withinAttachmentDeadline(async (assertActive) => {
+            await cdp.send('Network.enable', {}, sessionId);
+            assertActive();
+            await cdp.send('Page.enable', {}, sessionId).catch(() => { });
+            assertActive();
+            await cdp.send('Fetch.enable', {
+                patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
+            }, sessionId);
+            assertActive();
+            // Descend into this target's own children (iframes inside iframes).
+            await cdp.send('Target.setAutoAttach', {
+                autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
+            }, sessionId);
+            assertActive();
+            // A child remains part of setup until Chrome acknowledges its resume.
+            // Deduplicate this command with arming, and bound the acknowledgement too.
+            if (resume) {
+                await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId);
+                assertActive();
+            }
+        }, setupTimeoutMs, setupStop.signal);
+        arming.set(key, pending);
+        try {
+            await pending;
+            armed.add(key);
+        }
+        catch (error) {
+            const failure = attachmentFailure(error);
+            setupStop.abort(failure);
+            throw failure;
+        }
+        finally {
+            arming.delete(key);
+        }
     };
     cdp.on(async (method, params, sessionId) => {
         if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
@@ -379,6 +410,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if ((method === 'Inspector.detached' && sessionId === pageSessionId)
             || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            setupStop.abort(new CheckoutAttachmentError('closed'));
             preparationGate.invalidate('merchant_document_closed');
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
@@ -396,19 +428,25 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         if (method === 'Target.attachedToTarget') {
+            if (setupStop.signal.aborted)
+                return;
             const child = params.sessionId;
             try {
-                await arm(child);
+                await arm(child, true);
             }
-            catch {
+            catch (error) {
+                // Shared child setup and sibling cancellation can reject several
+                // handlers together. Publish the terminal setup failure only once.
+                if (setupFailureReported)
+                    return;
+                setupFailureReported = true;
+                setupStop.abort(attachmentFailure(error));
                 terminal = new Error('browser_interception_unavailable');
                 lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
                 opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
                 // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
                 return;
             }
-            // Child targets start paused when waitForDebuggerOnStart is set.
-            await cdp.send('Runtime.runIfWaitingForDebugger', {}, child).catch(() => { });
             return;
         }
         if (method !== 'Fetch.requestPaused')
@@ -438,9 +476,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
+        if (!attachmentReady || arming.has(sessionId ?? '__root__') || setupStop.signal.aborted) {
+            opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url, braintree === 'tokenization' ? pausedBody(request) : undefined);
+            preparation = preparationGate.claim(request.url, pausedBody(request));
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -590,7 +633,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 preparationGate.retireUnboundClaim();
         }
     });
-    await arm(pageSessionId);
+    try {
+        await arm(pageSessionId);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+        opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        if (!setupFailureReported) {
+            setupFailureReported = true;
+            lifecycle.cancel();
+            opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        }
+        throw failure;
+    }
     return lifecycle;
 }
 /**
@@ -606,6 +666,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
  */
 export async function attachToPlaywright(page, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
     // Routing cannot see requests owned by a service worker. Existing controlled
     // contexts must be recreated with serviceWorkers: 'block' before checkout.
     if (page.context?.().serviceWorkers?.().length) {
@@ -642,8 +705,10 @@ export async function attachToPlaywright(page, opts) {
         if (activeRequest && activeRequest.request === request)
             activeRequest.attempt.stop();
     });
-    page.on?.('close', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
-    page.on?.('crash', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('close', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('crash', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
     page.on?.('framenavigated', (frame) => {
         if (frame === page.mainFrame?.()) {
             preparationGate.invalidate('merchant_document_changed');
@@ -658,147 +723,175 @@ export async function attachToPlaywright(page, opts) {
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
-    await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
-        const request = route.request();
-        const braintree = request.method().toUpperCase() === 'POST'
-            ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
-        if (braintree === 'configuration')
-            return route.fallback();
-        if (braintree === 'invalid') {
-            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
-            return route.abort('aborted');
+    const install = async (assertActive) => {
+        if (page.isClosed?.()) {
+            const failure = new CheckoutAttachmentError('closed');
+            setupStop.abort(failure);
+            throw failure;
         }
-        // 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())) {
-            if (guards.matches(request.url(), request.method())) {
-                preparationGate.invalidate('unsupported_checkout');
-                lifecycle.unsupported();
-                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
+            const request = route.request();
+            const braintree = request.method().toUpperCase() === 'POST'
+                ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
+            if (braintree === 'configuration')
+                return route.fallback();
+            if (braintree === 'invalid') {
+                opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
                 return route.abort('aborted');
             }
-            return route.fallback();
-        }
-        let preparation;
-        try {
-            preparation = preparationGate.claim(request.url(), braintree === 'tokenization' ? request.postData() ?? '' : undefined);
-        }
-        catch (error) {
-            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
-            return route.abort('aborted');
-        }
-        // Fail closed and stay quiet: no card may reach the PSP, but neither may
-        // the page's retry loop turn into a stream of doomed API calls. Every
-        // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
-        // CDP adapter's Fetch.failRequest uses, so a refused navigation
-        // resolves identically whichever adapter is attached.
-        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-            return route.abort('aborted');
-        }
-        // Reserved before anything that could yield, matching attachToCdp.
-        awaitingApproval = true;
-        const attempt = merchantAttempt(lifecycle);
-        const frames = [];
-        try {
-            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
-                frames.push(frame);
-        }
-        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
-        const assertRequestLive = () => {
-            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
-                attempt.stop();
-            attempt.assertLive();
-        };
-        let handoffStarted = false;
-        try {
-            const body = request.postData() ?? '';
-            if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
-                opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
-                return await route.abort('aborted');
+            // 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())) {
+                if (guards.matches(request.url(), request.method())) {
+                    preparationGate.invalidate('unsupported_checkout');
+                    lifecycle.unsupported();
+                    opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+                    return route.abort('aborted');
+                }
+                return route.fallback();
             }
-            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
-            lifecycle.begin();
-            activeRequest = { request, frames, attempt };
-            if (preparation)
-                await preparationGate.assertDocument();
-            assertRequestLive();
-            const replay = await opts.vault.authorize({
-                user: opts.user,
-                merchant: opts.merchant,
-                amount: opts.amount,
-                amountCents: opts.amountCents,
-                currency: opts.currency,
-                cardId: preparation?.cardId ?? opts.cardId,
-                preparation,
-                timeoutMs: opts.timeoutMs,
-                signal: lifecycle.abort.signal,
-                merchantSignal: attempt.signal,
-                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
-                    lifecycle.approvalUrl(url);
-                    return opts.onApprovalUrl?.(url);
-                } },
-                request: { url: request.url(), method: request.method(), headers: request.headers(), body },
-            });
-            assertRequestLive();
-            if (lifecycle.isCancelled())
-                throw new Error('checkout cancelled locally after approval');
-            lifecycle.prepareHandoff(replay, request.url());
-            handoffStarted = replay.mode !== 'cse';
-            if (replay.mode === 'hosted_form') {
-                // Same as the CDP path: the paused navigation resolves to the
-                // synthetic page, and a re-post of this form is refused.
-                const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
-                // Inert on a navigation (never CORS-checked); one path for every fulfill.
-                await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
-                assertRequestLive();
-                lastSubmitted = { url: request.url(), body, at: Date.now() };
-                opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+            if (!attachmentReady || setupStop.signal.aborted) {
+                opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+                return route.abort('aborted');
             }
-            else if (replay.mode === 'cse') {
-                // Same as the CDP path: the request continues from this browser
-                // with the ciphertext swapped in and no header override; Playwright
-                // recomputes the length itself.
-                const postData = cseBody(body, replay);
-                handoffStarted = true;
-                await route.continue({ postData });
-                assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+            let preparation;
+            try {
+                preparation = preparationGate.claim(request.url(), request.postData() ?? '');
             }
-            else {
-                // Playwright adds these itself when a cross-origin fulfill carries
-                // none; written here anyway (replacing a stale value) so a
-                // cross-origin answer is the same whichever adapter ran.
-                const cors = corsDecision(request.url(), request.headers());
-                await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+            catch (error) {
+                opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+                return route.abort('aborted');
+            }
+            // Fail closed and stay quiet: no card may reach the PSP, but neither may
+            // the page's retry loop turn into a stream of doomed API calls. Every
+            // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
+            // CDP adapter's Fetch.failRequest uses, so a refused navigation
+            // resolves identically whichever adapter is attached.
+            if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+                const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+                opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+                return route.abort('aborted');
+            }
+            // Reserved before anything that could yield, matching attachToCdp.
+            awaitingApproval = true;
+            const attempt = merchantAttempt(lifecycle);
+            const frames = [];
+            try {
+                for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                    frames.push(frame);
+            }
+            catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+            const assertRequestLive = () => {
+                if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                    attempt.stop();
+                attempt.assertLive();
+            };
+            let handoffStarted = false;
+            try {
+                const body = request.postData() ?? '';
+                if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
+                    opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
+                    return await route.abort('aborted');
+                }
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+                lifecycle.begin();
+                activeRequest = { request, frames, attempt };
+                if (preparation)
+                    await preparationGate.assertDocument();
                 assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                const replay = await opts.vault.authorize({
+                    user: opts.user,
+                    merchant: opts.merchant,
+                    amount: opts.amount,
+                    amountCents: opts.amountCents,
+                    currency: opts.currency,
+                    cardId: preparation?.cardId ?? opts.cardId,
+                    preparation,
+                    timeoutMs: opts.timeoutMs,
+                    signal: lifecycle.abort.signal,
+                    merchantSignal: attempt.signal,
+                    onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                    onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
+                        lifecycle.approvalUrl(url);
+                        return opts.onApprovalUrl?.(url);
+                    } },
+                    request: { url: request.url(), method: request.method(), headers: request.headers(), body },
+                });
+                assertRequestLive();
+                if (lifecycle.isCancelled())
+                    throw new Error('checkout cancelled locally after approval');
+                lifecycle.prepareHandoff(replay, request.url());
+                handoffStarted = replay.mode !== 'cse';
+                if (replay.mode === 'hosted_form') {
+                    // Same as the CDP path: the paused navigation resolves to the
+                    // synthetic page, and a re-post of this form is refused.
+                    const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                    // Inert on a navigation (never CORS-checked); one path for every fulfill.
+                    await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                    assertRequestLive();
+                    lastSubmitted = { url: request.url(), body, at: Date.now() };
+                    opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+                }
+                else if (replay.mode === 'cse') {
+                    // Same as the CDP path: the request continues from this browser
+                    // with the ciphertext swapped in and no header override; Playwright
+                    // recomputes the length itself.
+                    const postData = cseBody(body, replay);
+                    handoffStarted = true;
+                    await route.continue({ postData });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+                }
+                else {
+                    // Playwright adds these itself when a cross-origin fulfill carries
+                    // none; written here anyway (replacing a stale value) so a
+                    // cross-origin answer is the same whichever adapter ran.
+                    const cors = corsDecision(request.url(), request.headers());
+                    await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                }
+                lifecycle.handedOff(replay);
             }
-            lifecycle.handedOff(replay);
-        }
-        catch (err) {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            lifecycle.failed(err, handoffStarted);
-            if (isTerminal(err))
-                terminal = err;
-            else if (isApprovalOutcome(err))
-                quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await route.abort('aborted').catch(() => { });
-        }
-        finally {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            awaitingApproval = false;
-            lifecycle.end();
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-        }
-    });
+            catch (err) {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                lifecycle.failed(err, handoffStarted);
+                if (isTerminal(err))
+                    terminal = err;
+                else if (isApprovalOutcome(err))
+                    quietUntil = Date.now() + cooldownMs;
+                opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+                await route.abort('aborted').catch(() => { });
+            }
+            finally {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                awaitingApproval = false;
+                lifecycle.end();
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+            }
+        });
+        assertActive();
+    };
+    try {
+        await withinAttachmentDeadline(install, setupTimeoutMs, setupStop.signal);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        lifecycle.cancel();
+        opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        // A route registration may finish after this rejection. Keep its handler
+        // inert for card traffic; removing it would reopen the failed checkout.
+        throw failure;
+    }
     return lifecycle;
 }

package/dist/client.d.ts

@@ -102,7 +102,7 @@ export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
 export interface PrepareCheckoutOptions {
     psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
-    environment: 'production' | 'sandbox';
+    environment: 'production' | 'sandbox' | 'shared';
     signal?: AbortSignal;
 }
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
@@ -122,7 +122,7 @@ export interface PreparedCheckout {
     readonly id: string;
     readonly status: 'ready';
     readonly psp: PreparationProcessor;
-    readonly environment: 'production' | 'sandbox';
+    readonly environment: 'production' | 'sandbox' | 'shared';
     readonly expiresAt: string;
     readonly cardId: string;
     readonly user: string;

package/dist/client.js

@@ -1,5 +1,5 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
-import { matchesPreparedRequest } from './prepared-processor.js';
+import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-processor.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
@@ -315,7 +315,7 @@ export class VaultClient {
     async prepareCheckout(input) {
         input = { ...input };
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
-        if (!['square', 'braintree'].includes(input.psp) || !['production', 'sandbox'].includes(input.environment))
+        if (!validPreparationEnvironment(input.psp, input.environment))
             throw fail('unsupported_processor');
         if (!Number.isSafeInteger(input.amountCents) || input.amountCents <= 0 || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
             throw fail('amount_required');

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
 export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, PrepareCheckoutOptions, PrepareCheckoutInput, PreparedCheckout, RazorpayProcessorError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { CheckoutAttachmentError } from './attachment.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export type { Substitutions } from './substitute.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, PaymentOutcomeUnknownError, CheckoutCancelledError, CheckoutPreparationError, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
+export { CheckoutAttachmentError } from './attachment.js';
 export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
 export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
 export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';

package/dist/preparation.js

@@ -1,5 +1,5 @@
 import { CheckoutPreparationError } from './client.js';
-import { matchesPreparedRequest, preparationEndpoint } from './prepared-processor.js';
+import { matchesPreparedRequest, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -34,7 +34,7 @@ export class PreparationGate {
         const onAbort = () => this.invalidate('cancelled');
         signal.addEventListener('abort', onAbort, { once: true });
         try {
-            if (!options || !['square', 'braintree'].includes(options.psp) || !['production', 'sandbox'].includes(options.environment))
+            if (!options || !validPreparationEnvironment(options.psp, options.environment))
                 throw new CheckoutPreparationError(null, 'unsupported_processor');
             const tokenizer = preparationEndpoint(options.psp, options.environment);
             if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))

package/dist/prepared-processor.d.ts

@@ -1,5 +1,7 @@
-export type PreparationProcessor = 'square' | 'braintree';
-export type PreparationEnvironment = 'production' | 'sandbox';
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago';
+export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export declare function validPreparationEnvironment(psp: string, environment: string): boolean;
 export declare function preparationEndpoint(psp: PreparationProcessor, environment: PreparationEnvironment): string;
 /** Processor identity and environment are part of the device's prior consent. */
 export declare function matchesPreparedRequest(psp: PreparationProcessor, environment: PreparationEnvironment, requestUrl: string, method: string, body?: string | null): boolean;

package/dist/prepared-processor.js

@@ -1,23 +1,91 @@
-import { braintreeEnvironment, isPreparedBraintreeRequest } from './braintree.js';
+import { braintreeEnvironment, isPreparedBraintreeRequest, readTokenizationJson } from './braintree.js';
+/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. */
+export function validPreparationEnvironment(psp, environment) {
+    if (psp === 'bambora' || psp === 'mercado_pago')
+        return environment === 'shared';
+    return ['square', 'braintree', 'worldpay'].includes(psp) && ['production', 'sandbox'].includes(environment);
+}
 export function preparationEndpoint(psp, environment) {
+    if (!validPreparationEnvironment(psp, environment))
+        throw new Error('unsupported_preparation_processor');
+    if (psp === 'bambora')
+        return 'https://api.bam.shift4api.net/scripts/tokenization/tokens';
+    if (psp === 'mercado_pago')
+        return 'https://api.mercadopago.com/v1/card_tokens';
+    if (psp === 'worldpay')
+        return environment === 'production'
+            ? 'https://access.worldpay.com/sessions/card' : 'https://try.access.worldpay.com/sessions/card';
     if (psp === 'braintree')
         return environment === 'production'
             ? 'https://payments.braintree-api.com/graphql' : 'https://payments.sandbox.braintree-api.com/graphql';
     return environment === 'production'
         ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
 }
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+const keys = (value, allowed) => Object.keys(value).every(key => allowed.includes(key));
+const string = (value, max = 1024) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+const digits = (value, min, max) => typeof value === 'string' && value.length >= min && value.length <= max && !/[^0-9]/.test(value);
+const month = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 1, 2)) && Number(value) >= 1 && Number(value) <= 12;
+const year = (value) => (typeof value === 'number' && Number.isInteger(value) || digits(value, 2, 4)) && (Number(value) >= 0 && Number(value) <= 99 || Number(value) >= 2000 && Number(value) <= 9999);
+/** Native fresh-card shapes only. Saved-card, charge and recurring siblings never consume consent. */
+function freshCardBody(psp, body) {
+    const value = readTokenizationJson(body);
+    if (!value)
+        return false;
+    if (psp === 'worldpay')
+        return keys(value, ['identity', 'cardNumber', 'cardExpiryDate', 'cvc'])
+            && string(value.identity) && digits(value.cardNumber, 12, 19)
+            && record(value.cardExpiryDate) && keys(value.cardExpiryDate, ['month', 'year'])
+            && month(value.cardExpiryDate.month) && year(value.cardExpiryDate.year)
+            && (value.cvc === undefined || digits(value.cvc, 3, 4));
+    if (psp === 'bambora')
+        return keys(value, ['number', 'expiry_month', 'expiry_year', 'cvd'])
+            && digits(value.number, 12, 19) && month(value.expiry_month) && year(value.expiry_year)
+            && (value.cvd === undefined || digits(value.cvd, 3, 4));
+    if (psp !== 'mercado_pago' || !keys(value, ['card_number', 'expiration_month', 'expiration_year', 'security_code', 'cardholder', 'device'])
+        || !digits(value.card_number, 12, 19) || !month(value.expiration_month) || !year(value.expiration_year)
+        || (value.security_code !== undefined && value.security_code !== '' && !digits(value.security_code, 3, 4)) || !record(value.cardholder)
+        || !keys(value.cardholder, ['name', 'identification']))
+        return false;
+    const holder = value.cardholder;
+    if (holder.name !== undefined && holder.name !== '' && !string(holder.name))
+        return false;
+    if (holder.identification !== undefined && (!record(holder.identification) || !keys(holder.identification, ['type', 'number'])
+        || Object.values(holder.identification).some(v => v !== '' && !string(v))))
+        return false;
+    if (value.device !== undefined && (!record(value.device) || !keys(value.device, ['meli'])
+        || !record(value.device.meli) || !keys(value.device.meli, ['session_id']) || !string(value.device.meli.session_id, 4096)))
+        return false;
+    return true;
+}
 /** Processor identity and environment are part of the device's prior consent. */
 export function matchesPreparedRequest(psp, environment, requestUrl, method, body) {
-    if (method.toUpperCase() !== 'POST')
+    if (method.toUpperCase() !== 'POST' || !validPreparationEnvironment(psp, environment))
         return false;
-    if (psp === 'braintree') {
+    if (psp === 'braintree')
         return braintreeEnvironment(requestUrl) === environment && isPreparedBraintreeRequest(body ?? null);
-    }
-    if (psp !== 'square')
-        return false;
     try {
         const request = new URL(requestUrl), endpoint = new URL(preparationEndpoint(psp, environment));
-        return request.origin === endpoint.origin && request.pathname === endpoint.pathname && !request.username && !request.password;
+        if (request.username || request.password || request.hash)
+            return false;
+        if (psp === 'bambora') {
+            if (![endpoint.href, 'https://api.na.bambora.com/scripts/tokenization/tokens'].includes(requestUrl))
+                return false;
+        }
+        else if (psp === 'worldpay') {
+            if (requestUrl !== endpoint.href)
+                return false;
+        }
+        else if (request.origin !== endpoint.origin || request.pathname !== endpoint.pathname)
+            return false;
+        if (psp === 'mercado_pago') {
+            const names = [...request.searchParams.keys()];
+            if (new Set(names).size !== names.length || names.some(name => !['public_key', 'locale', 'js_version', 'referer'].includes(name)))
+                return false;
+        }
+        return psp === 'square' || freshCardBody(psp, body ?? null);
     }
     catch {
         return false;

package/dist/registry.js

@@ -48,8 +48,12 @@ export const BUILTIN_REGISTRY = [
     },
     {
         psp: 'checkout_com',
-        match: /api(\.sandbox)?\.checkout\.com\/tokens/i,
-        hosts: ["^api\\.checkout\\.com$", "^api\\.sandbox\\.checkout\\.com$"],
+        // Flow's native card controller can use either tokenization host.
+        match: /(api|card-acquisition-gateway)(\.sandbox)?\.checkout\.com\/tokens/i,
+        hosts: [
+            "^api\\.checkout\\.com$", "^api\\.sandbox\\.checkout\\.com$",
+            "^card-acquisition-gateway\\.checkout\\.com$", "^card-acquisition-gateway\\.sandbox\\.checkout\\.com$",
+        ],
         encoding: 'json',
         passthroughHeaders: [/^authorization$/i],
     },
@@ -156,10 +160,10 @@ export const BUILTIN_REGISTRY = [
     },
     {
         psp: 'paysafe',
-        match: /api(\.test)?\.paysafe\.com\/(?:paymenthub\/v1\/singleusepaymenthandles|js\/api\/v1\/tokenize)(?![\w\/-])/i,
-        hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$"],
+        match: /(?:api(\.test)?\.paysafe\.com\/(?:paymenthub\/v1\/singleusepaymenthandles|js\/api\/v1\/tokenize)|hosted(\.test)?\.paysafe\.com\/checkout\/api\/v1\/tokenize)(?![\w\/-])/i,
+        hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$", "^hosted\\.paysafe\\.com$", "^hosted\\.test\\.paysafe\\.com$"],
         encoding: 'json',
-        passthroughHeaders: [/^authorization$/i, /^x-paysafe-credentials$/i],
+        passthroughHeaders: [/^authorization$/i, /^x-paysafe-credentials$/i, /^correlationid$/i],
     },
     {
         psp: 'recurly',
@@ -211,7 +215,7 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY) {
     catch {
         return null;
     }
-    if (parsed.protocol !== 'https:')
+    if (parsed.protocol !== 'https:' || parsed.port || parsed.username || parsed.password)
         return null;
     const hostPath = `${parsed.hostname.toLowerCase()}${parsed.pathname}`;
     return (registry.find((r) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Let browser agents pay with the user's own card, without your infrastructure ever touching card data.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs minimum-delay.test.mjs",
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs braintree.test.mjs prepared-processor.test.mjs minimum-delay.test.mjs paysafe.test.mjs attachment.test.mjs",
     "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs"
   },
   "keywords": [