@agent-cards/checkout 0.18.0 → 0.19.0

package/dist/cdp.js

@@ -1,12 +1,15 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
-import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
+import { AdyenTestPlatformRefusedError, ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, MerchantTotalError, PaymentOutcomeUnknownError, PreparationRequiredError, ProcessorRefusedError, UnsupportedModeError, } from './client.js';
 import { PreparationGate } from './preparation.js';
-import { classifyBraintreeRequest } from './braintree.js';
-import { StripeCheckoutGate, StripeCheckoutClaimConflictError, stripeCheckoutReadinessError } from './stripe-checkout.js';
+import { StripeCheckoutGate } from './stripe-checkout.js';
 import { MercadoCheckoutGate } from './mercado-checkout.js';
 import { MERCADO_CHECKOUT_PATTERN } from './mercado-checkout.generated.js';
+import { dispatchPreClaim, eventUrl } from './pre-claim.js';
 import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
-import { substituteEncryptedFields } from './substitute.js';
+import { cseBody } from './cse-body.js';
+import { replayTemplatedUrl, reviewedMerchantProfileUrlPatterns } from './merchant-hosted.js';
+import { MerchantHandoffWatch } from './merchant-handoff.js';
+import { MERCHANT_PAGE_WAIT_MS, MerchantTotalWatch } from './merchant-total-watch.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
 // Every URL that leaves this module through onEvent is redacted to origin +
@@ -141,20 +144,121 @@ function isApprovalOutcome(err) {
 function isTerminal(err) {
     if (err instanceof CheckoutApiError)
         return err.permanent;
-    return err instanceof CardEncryptedError || err instanceof UnsupportedModeError;
+    // Refused at create for Adyen's test platform: the page's next request is refused the same way.
+    if (err instanceof AdyenTestPlatformRefusedError)
+        return err.stage === 'create';
+    return err instanceof CardEncryptedError || err instanceof UnsupportedModeError || err instanceof PreparationRequiredError;
 }
 /**
- * The cse continuation: the paused body with the vault's ciphertext in place
- * of the dummy blobs. It is sent as postData ALONE. Chromium recomputes
- * Content-Length for a continued request itself and refuses a header override
- * that names it (Fetch.continueRequest answers -32602 "Unsafe header"), and
- * that refusal would land after the cardholder approved, failing a paid-for
- * request. Leaving `headers` off the command keeps every other header the
- * browser's own, untouched, which is the point of continuing rather than
- * fulfilling.
+ * cseBody, retiring a merchant-hosted approval it refuses. The refusal (a live body
+ * that is not the one the API checked, a swap payment-core will not write) happens
+ * before anything leaves the browser, so the approval went to no request: it is
+ * retired as merchant_never_retried, the one runtime reason the API accepts on an
+ * approved cse row, and the API stops serving its ciphertext. Not awaited, so the
+ * page's request fails at once; a retirement that fails leaves the API's purge to
+ * drop the ciphertext.
  */
-function cseBody(body, replay) {
-    return substituteEncryptedFields(body, replay.substitutions);
+function cseContinuationBody(opts, body, replay, url, preparation) {
+    try {
+        return cseBody(body, replay, url, preparation);
+    }
+    catch (error) {
+        if (replay.kind === 'merchant_hosted' && typeof opts.vault?.cancelAuthorization === 'function') {
+            void Promise.resolve().then(() => opts.vault.cancelAuthorization(replay.authorizationId, 'merchant_never_retried')).catch(() => { });
+        }
+        throw error;
+    }
+}
+/** Chromium's own limit on the redirects one request follows. */
+const MAX_REDIRECT_HOPS = 20;
+/** The statuses a browser follows to the Location they name. */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Reports the merchant's answer to a continued merchant-hosted request to the
+ * hand-off watch, from the page's own response and requestfailed events. They
+ * arrive in the Playwright server's order, and Playwright routes a paused request
+ * only once Chromium's renderer reported it, so an answer the page read before it
+ * sent a retry is read here before that retry's route. request.response() is a
+ * round trip that the retry's route can overtake.
+ *
+ * A followed redirect is answered by its last hop, as CDP reports it. Playwright
+ * reports a hop's 3xx and then, in the same step, the next hop as a new request
+ * (redirectedTo()), so a 3xx waits, and settle() takes it as the final answer once
+ * any later event finds no next hop: the reply to that request's own response()
+ * call, another network event, a retry's route, or the page closing. `answered`
+ * runs once the final answer is known, after the watch has read it.
+ */
+function watchPlaywrightHandoff(page, request, watch, answered) {
+    let redirect = null;
+    let done = false;
+    const final = (status) => {
+        stop();
+        watch.responded(status);
+        try {
+            answered?.();
+        }
+        catch { /* the charge report never breaks the page */ }
+    };
+    const inChain = (candidate) => {
+        for (let hop = 0; candidate && hop <= MAX_REDIRECT_HOPS; hop++) {
+            if (candidate === request)
+                return true;
+            candidate = typeof candidate.redirectedFrom === 'function' ? candidate.redirectedFrom() : null;
+        }
+        return false;
+    };
+    const onResponse = (response) => {
+        settle();
+        let from, status;
+        try {
+            from = response.request();
+            status = response.status();
+        }
+        catch {
+            return;
+        }
+        if (done || !inChain(from))
+            return;
+        if (REDIRECT_STATUSES.has(status)) {
+            redirect = { request: from, status };
+            if (typeof from.response === 'function')
+                Promise.resolve().then(() => from.response()).then(settle, settle);
+            return;
+        }
+        final(status);
+    };
+    const onFailed = (failed) => { settle(); if (!done && inChain(failed)) {
+        stop();
+        watch.failed();
+    } };
+    const stop = () => { done = true; page.off?.('response', onResponse); page.off?.('requestfailed', onFailed); };
+    const settle = () => {
+        if (done || !redirect)
+            return;
+        let next = null;
+        try {
+            next = typeof redirect.request.redirectedTo === 'function' ? redirect.request.redirectedTo() : null;
+        }
+        catch {
+            next = null;
+        }
+        if (next)
+            return;
+        final(redirect.status);
+    };
+    page.on?.('response', onResponse);
+    page.on?.('requestfailed', onFailed);
+    return { settle, stop, closed: () => { settle(); if (!done) {
+            stop();
+            watch.failed();
+        } } };
+}
+/** The `authorized` event's detail for a cse continuation; a merchant-hosted one names its profile and templated URL. */
+function cseAuthorizedDetail(replay, url) {
+    const base = { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) };
+    return replay.kind === 'merchant_hosted'
+        ? { ...base, kind: 'merchant_hosted', profile: replay.profile, url: replayTemplatedUrl(replay, url) }
+        : base;
 }
 /**
  * The paused request's body, or null when Chromium says there is one and did
@@ -415,6 +519,12 @@ function safeOptions(opts) {
 function failureSummary(error) {
     if (error instanceof CheckoutApiError)
         return `${error.name}: ${error.code ?? `http_${error.status}`}`;
+    // The rule's code, as the API's own refusal carried it before the error was typed.
+    if (error instanceof AdyenTestPlatformRefusedError)
+        return `${error.name}: ${error.code}`;
+    // Why the merchant's own total could not stand behind the payment, and at which step.
+    if (error instanceof MerchantTotalError)
+        return `${error.name}: ${error.code}${error.reasonCode ? ` (${error.reasonCode})` : ''}`;
     return error instanceof Error ? error.name : 'CheckoutError';
 }
 const STRIPE_PAYMENT_INTENT_CONFIRM = /^\/v1\/payment_intents\/pi_[A-Za-z0-9]+\/confirm$/;
@@ -813,7 +923,10 @@ async function retireUnusedApproval(opts, lifecycle, authorizationId) {
  * than the recognizers (see cardUrlPatterns): each paused request is re-checked
  * with `isCardRequest` below and continued untouched unless it is an exact
  * match. Patterns are resolved once, at attach, so every nested target ends up
- * armed identically.
+ * armed identically. Merchant profiles are the exception to syncing first: the
+ * endpoint of every profile this build reviewed is armed whatever the sync said,
+ * and each paused request is judged against the profiles armed when it pauses,
+ * so a sync after attach arms a profile here as it does in attachToPlaywright.
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
@@ -884,6 +997,16 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         return tree.frameTree.frame.url;
     };
     const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
+    // A merchant-hosted request this attachment continued with the Vault's
+    // ciphertext, and the Network identity its answer arrives under.
+    const merchantHandoff = new MerchantHandoffWatch(lifecycle, opts.onEvent);
+    let handoffNetwork = null;
+    // The page's retries of that request, each waiting for its own Network report; see awaitRetryReport.
+    const retriesAwaitingReport = new Map();
+    // The merchant's own total (merchant-total-watch.ts): its checkout responses, recorded
+    // read-only from attach on, and the approval a hand-off answers, for the charge report.
+    const merchantTotal = new MerchantTotalWatch(opts.onEvent, opts.vault);
+    let handoffReplay = null;
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     const arming = new Map();
@@ -959,6 +1082,29 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         request.attempt.assertLive();
         return true;
     };
+    /**
+     * Judges a retry of the handed-off merchant-hosted request in the page's order
+     * (MerchantHandoffWatch.retried). Fetch pauses a request in the browser process,
+     * while the renderer reports, in order on the page's session, the merchant's
+     * answer and then the page's next request (Network.requestWillBeSent). A retry's
+     * pause can arrive before an answer the page already read, so the retry is
+     * judged at its own requestWillBeSent. False when that already arrived or cannot
+     * come; otherwise the session going away or the attachment deadline ends the wait.
+     */
+    const awaitRetryReport = (sessionId, networkId, judge) => {
+        if (!sessionId || typeof networkId !== 'string' || !networkId || hasRetiredSummary(sessionId, networkId))
+            return false;
+        if ([...requestSources.values(), ...retiredSources.values()]
+            .some(source => sourceOwner(source) === sessionId && source.networkId === networkId))
+            return false;
+        const key = requestKey(sessionId, networkId);
+        let timer;
+        const reported = () => { clearTimeout(timer); retriesAwaitingReport.delete(key); judge(); };
+        timer = setTimeout(reported, setupTimeoutMs);
+        timer.unref?.();
+        retriesAwaitingReport.set(key, { sessionId, reported });
+        return true;
+    };
     /** A frame's Fetch event does not identify which dedicated worker sent it.
      * Require the exact Network event before asking the Vault whenever that frame
      * has had workers. A sibling's detach proves nothing about an unknown request;
@@ -1013,8 +1159,15 @@ 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() : [];
+    // The endpoint and siblings of every merchant profile this build reviewed
+    // (merchant-hosted.ts), which a VaultClient arms from the start: a profile's card
+    // request is paused here exactly as attachToPlaywright's per-request route catches
+    // it, before or after any syncRegistry(). The gate continues untouched a request
+    // that the vault names no profile for.
+    const merchantPatterns = [...reviewedMerchantProfileUrlPatterns(),
+        ...(typeof opts.vault?.merchantProfileUrlPatterns === 'function' ? opts.vault.merchantProfileUrlPatterns() : [])];
     const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns,
-            ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN])];
+            ...(stripeCheckout.isEnabled() ? ['https://api.stripe.com/*'] : []), MERCADO_CHECKOUT_PATTERN, ...merchantPatterns])];
     const arm = async (sessionId, resume = false, worker = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
@@ -1122,6 +1275,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             mercadoCheckout.invalidate();
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
+            // Nothing can read the merchant's answer to a continued merchant-hosted
+            // request any more, nor the page's report of a retry: a retry is judged on
+            // what was read, then the answer is an unknown outcome unless it arrived.
+            for (const waiting of [...retriesAwaitingReport.values()])
+                waiting.reported();
+            if (handoffNetwork)
+                merchantHandoff.failed();
         }
         // The transport is browser-scoped. A second tab's request or child target
         // must never be authorized with this page's merchant, amount or preparation.
@@ -1140,6 +1300,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 retireSource(record);
             else
                 requestSources.set(key, record);
+            // Read-only: the page this request came from (its session and document loader), and
+            // the request itself when a priced merchant profile's rules read it.
+            if (!sessionDetached(sessionId) && params.request) {
+                merchantTotal.sent(key, { method: params.request.method, url: params.request.url,
+                    ...(typeof params.request.postData === 'string' ? { requestBody: params.request.postData } : {}),
+                    ...(typeof params.loaderId === 'string' && params.loaderId ? { page: `${owner}:${params.loaderId}` } : {}) });
+            }
             if (matchesActive) {
                 try {
                     identifyRequest(activeRequest);
@@ -1147,15 +1314,39 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 catch { /* stop already retires the exact attempt */ }
                 activeRequest.attributionChanged?.();
             }
+            retriesAwaitingReport.get(requestKey(owner, params.requestId))?.reported();
             return;
         }
         if (sessionDetached(sessionId))
             return;
         if (method === 'Network.loadingFinished') {
-            requestSources.delete(requestKey(sessionId, params.requestId));
+            const key = requestKey(sessionId, params.requestId);
+            requestSources.delete(key);
+            if (merchantTotal.log.tracks(key)) {
+                // When it finished, then its text: a merchant response the total or the charge is read from.
+                const completedAt = Date.now();
+                cdp.send('Network.getResponseBody', { requestId: params.requestId }, sessionId).then((read) => merchantTotal.log.read(key, typeof read?.body === 'string'
+                    ? (read.base64Encoded ? Buffer.from(read.body, 'base64').toString('utf8') : read.body) : null, completedAt), () => merchantTotal.log.read(key, null, completedAt));
+            }
+            return;
+        }
+        if (method === 'Network.responseReceived') {
+            merchantTotal.log.answered(requestKey(sessionId, params.requestId), params.response?.status);
+            // The merchant's answer to a continued merchant-hosted request: 5xx is an unknown outcome.
+            if (handoffNetwork && params.requestId === handoffNetwork.networkId && sessionId === handoffNetwork.sessionId) {
+                merchantHandoff.responded(params.response?.status);
+                // What the merchant's confirmation says it charged, once it has been read: reported from
+                // the hand-off's own answer, as the Playwright adapter does, whether or not the card
+                // request itself is one the after-payment rules read (Dick's reads its checkout calls).
+                if (handoffReplay)
+                    merchantTotal.answered(handoffReplay, opts.vault);
+            }
             return;
         }
         if (method === 'Network.loadingFailed') {
+            merchantTotal.log.failed(requestKey(sessionId, params.requestId));
+            if (handoffNetwork && params.requestId === handoffNetwork.networkId && sessionId === handoffNetwork.sessionId)
+                merchantHandoff.failed();
             if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sourceSessionId === sessionId) {
                 const dead = { requestId: activeRequest.requestId, sessionId: activeRequest.sessionId, request: activeRequest.request };
                 // A request a dedicated worker sent keeps today's behaviour: its loss
@@ -1196,6 +1387,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             if (method !== 'Page.frameDetached') {
                 const detached = method === 'Target.detachedFromTarget' ? params.sessionId : sessionId;
                 detachedSessions.add(detached);
+                // A retry paused there is judged on what was read, and the target a
+                // continued merchant-hosted request went out on is gone before its answer arrived.
+                for (const waiting of [...retriesAwaitingReport.values()])
+                    if (sessionDetached(waiting.sessionId))
+                        waiting.reported();
+                if (handoffNetwork && detached === handoffNetwork.sessionId)
+                    merchantHandoff.failed();
                 if (arming.has(detached))
                     failInterception(new CheckoutAttachmentError('closed'));
                 // Terminating a worker need not emit loadingFailed. Its nested workers
@@ -1268,105 +1466,41 @@ 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'
-            ? classifyBraintreeRequest(request.url, request.method, pausedBody(request)) : undefined;
-        if (braintree === 'configuration') {
-            await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
-            return;
-        }
-        if (braintree === 'invalid') {
-            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
-            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
-            return;
-        }
-        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();
-                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url), method: request.method } });
-                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
-                return;
-            }
-            await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
+        // When this request paused: the merchant's total is read as of this moment.
+        const pausedAt = Date.now();
+        // One pre-claim gate registry decides and performs the mechanics through
+        // these effects; the state accessors read the same closure variables the
+        // inline gates did. It resolves synchronously for an ordinary card request,
+        // so activeRequest is still set in the paused request's own microtask. Only
+        // a pause hands work back to the claim flow below.
+        const preClaimResult = dispatchPreClaim({
+            // headers and body are read lazily, inside the gate that needs them (see PreClaimContext.request).
+            request: { url: request.url, method: request.method, get headers() { return request.headers; }, get body() { return pausedBody(request); } },
+            vault: opts.vault, guards, mercado: mercadoCheckout, stripe: stripeCheckout,
+            readDocumentUrl, lifecycle, preparationGate, onEvent: opts.onEvent, failureSummary,
+            effects: {
+                continueRequest: (postData) => cdp.send('Fetch.continueRequest', { requestId, ...(postData !== undefined ? { postData: Buffer.from(postData).toString('base64') } : {}) }, sessionId),
+                answer: (response) => 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),
+                abort: () => cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { }),
+            },
+            attachmentReady: () => attachmentReady,
+            interceptionAborted: () => setupStop.signal.aborted,
+            lifecycleAborted: () => lifecycle.abort.signal.aborted,
+            terminal: () => !!terminal,
+            documentClosed: () => false,
+            stripeAttachmentBusy: () => arming.has(sessionId ?? '__root__'),
+            requestInactive: () => false,
+            awaitingApproval: () => awaitingApproval,
+            stripeStep: null,
+            merchantHandoff: { retried: (profile) => merchantHandoff.retried(profile, (judge) => awaitRetryReport(sessionId, networkId, judge)) },
+        });
+        const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
+        if (preClaim.kind !== 'pause')
             return;
-        }
+        const stripeStep = preClaim.stripeStep;
         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(() => { });
@@ -1399,7 +1533,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 activeRequest.frameId = frameId;
                 activeRequest.request = request;
                 activeRequest.sourceSessionId = undefined;
-                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}),
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: eventUrl(opts.vault, request.url), ...(resourceType ? { resourceType } : {}),
                         authorizationId: lifecycle.getState().authorizationId, retry: true } });
                 activeRequest.attempt.bind({ requestId, sessionId, request });
                 return;
@@ -1492,7 +1626,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     void opts.vault.reportDuplicateGuard?.(lastSubmitted.authorizationId);
                 return;
             }
-            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
+            opts.onEvent?.({ type: 'card_request_paused', detail: { url: eventUrl(opts.vault, request.url), ...(resourceType ? { resourceType } : {}) } });
             lifecycle.begin();
             const approvalStartedAt = Date.now();
             const payToInterceptMs = readPayToInterceptMs(opts.payClickedAt, approvalStartedAt);
@@ -1520,6 +1654,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             const merchantOrigin = preparation?.merchantOrigin ?? (opts.executionMode === 'user_approval'
                 ? opts.merchantOrigin : pageOrigin?.startsWith('https:') ? pageOrigin : opts.merchantOrigin);
             attempt.assertLive();
+            // The card request's page is its own Network event's document, and Chromium can deliver
+            // that event after the pause: for a profile the merchant's total prices, wait for it
+            // (bounded), so a total tied to its page (Cinemark) is not refused for want of one.
+            const cardKey = requestKey(activeRequest?.sourceSessionId ?? sessionId ?? '', networkId ?? '');
+            const cardPage = merchantTotal.priced(request.url)
+                ? await merchantTotal.pageFor(cardKey, MERCHANT_PAGE_WAIT_MS, attempt.signal) : merchantTotal.pageOf(cardKey);
+            attempt.assertLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
@@ -1537,6 +1678,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
                 merchantSignal: attempt.signal,
+                // What the merchant's own checkout said its total was, as this browser recorded it
+                // (read only for a reviewed profile priced by it): the page is the card request's.
+                merchantTotal: merchantTotal.capture(pausedAt, cardPage),
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
                 onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
                     lifecycle.approvalUrl(url);
@@ -1601,15 +1745,25 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // still goes out from THIS browser, with its own session, risk data
                 // and cookies, and only the four ciphertext fields swapped in. Only
                 // postData rides on the command: no header override, ever (see
-                // cseBody for why a recomputed Content-Length is refused by Chromium).
-                const postData = Buffer.from(cseBody(deliverBody, replay)).toString('base64');
+                // cse-body.ts for why a recomputed Content-Length is refused by Chromium).
+                // A total the merchant moved while the cardholder decided holds the card here.
+                if (replay.kind === 'merchant_hosted')
+                    await merchantTotal.release(replay, opts.vault, attempt.signal);
+                attempt.assertLive();
+                const postData = Buffer.from(cseContinuationBody(opts, deliverBody, replay, deliverRequest.url, preparation)).toString('base64');
                 handoffStarted = true;
+                if (replay.kind === 'merchant_hosted') {
+                    // Watched from before the continue, so an answer that races the command is still read.
+                    merchantHandoff.begin(replay.profile, replay.authorizationId, replayTemplatedUrl(replay, deliverRequest.url));
+                    handoffNetwork = { sessionId: activeRequest?.sourceSessionId ?? deliverOn, networkId: activeRequest?.networkId ?? '' };
+                    handoffReplay = replay;
+                }
                 await cdp.send('Fetch.continueRequest', {
                     requestId: deliverTo,
                     postData,
                 }, deliverOn);
                 attempt.assertLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+                opts.onEvent?.({ type: 'authorized', detail: cseAuthorizedDetail(replay, deliverRequest.url) });
             }
             else {
                 // The processor's answer, handed to the page as if the processor had
@@ -1746,6 +1900,79 @@ export async function attachToPlaywright(page, opts) {
         return page.url();
     };
     const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
+    // A merchant-hosted request this attachment continued, and its answer; see watchPlaywrightHandoff.
+    const merchantHandoff = new MerchantHandoffWatch(lifecycle, opts.onEvent);
+    let handoffAnswer = null;
+    // The merchant's own total, as attachToCdp records it. A page id is the main frame's
+    // document: it changes when the main frame commits a new document, and a document request
+    // belongs to the document it loads, so its page is read once the frame has committed it.
+    // A same-document navigation (history.pushState, a hash change) fires framenavigated too
+    // but sends no document request, so it keeps the page id, as CDP's loaderId does. Nor does
+    // a document request that commits nothing: one that failed, or one answered 204 or 205.
+    const merchantTotal = new MerchantTotalWatch(opts.onEvent, opts.vault);
+    let documentSerial = 1;
+    // The main frame's document request that no navigation has committed yet.
+    let documentRequest = null;
+    let requestSerial = 0;
+    const requestKeys = new WeakMap();
+    const keyOf = (request) => {
+        let key = requestKeys.get(request);
+        if (!key) {
+            key = `pw:${++requestSerial}`;
+            requestKeys.set(request, key);
+        }
+        return key;
+    };
+    const mainDocument = (request) => {
+        try {
+            return request.isNavigationRequest?.() === true && request.frame?.() === page.mainFrame?.();
+        }
+        catch {
+            return false;
+        }
+    };
+    page.on?.('request', (request) => {
+        // A new document is on its way: the main frame's next navigation commits it.
+        if (mainDocument(request))
+            documentRequest = request;
+        try {
+            const body = typeof request.postData === 'function' ? request.postData() : null;
+            merchantTotal.sent(keyOf(request), { method: request.method(), url: request.url(),
+                ...(typeof body === 'string' ? { requestBody: body } : {}), page: `doc:${documentSerial}` });
+        }
+        catch { /* a request the page already dropped */ }
+    });
+    page.on?.('requestfinished', (request) => {
+        // A document answered 204 or 205 loads nothing, so no navigation will commit it.
+        if (request === documentRequest) {
+            Promise.resolve().then(() => request.response()).then((response) => {
+                if (request === documentRequest && [204, 205].includes(response?.status?.()))
+                    documentRequest = null;
+            }).catch(() => { });
+        }
+        const key = keyOf(request);
+        if (!merchantTotal.log.tracks(key))
+            return;
+        const completedAt = Date.now();
+        Promise.resolve().then(async () => {
+            const response = await request.response();
+            if (!response) {
+                merchantTotal.log.failed(key);
+                return;
+            }
+            merchantTotal.log.answered(key, response.status());
+            if (mainDocument(request))
+                merchantTotal.log.repage(key, `doc:${documentSerial}`);
+            let text = null;
+            try {
+                text = await response.text();
+            }
+            catch {
+                text = null;
+            }
+            merchantTotal.log.read(key, text, completedAt);
+        }).catch(() => merchantTotal.log.failed(key));
+    });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
@@ -1770,6 +1997,10 @@ export async function attachToPlaywright(page, opts) {
     const retryWait = retryWaitMs(opts.merchantRetryWaitMs);
     let activeRequest = null;
     page.on?.('requestfailed', (request) => {
+        // A document request that failed commits nothing either.
+        if (request === documentRequest)
+            documentRequest = null;
+        merchantTotal.log.failed(keyOf(request));
         if (activeRequest && activeRequest.request === request && activeRequest.attempt.lose()) {
             // The page's own script gave up on its request; the cardholder's
             // approval did not (see merchantAttempt). Forget the request's identity
@@ -1780,11 +2011,15 @@ export async function attachToPlaywright(page, opts) {
         }
     });
     page.on?.('close', () => { if (!attachmentReady)
-        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); });
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); handoffAnswer?.closed(); });
     page.on?.('crash', () => { if (!attachmentReady)
-        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); });
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); handoffAnswer?.closed(); });
     page.on?.('framenavigated', (frame) => {
         if (frame === page.mainFrame?.()) {
+            if (documentRequest) {
+                documentRequest = null;
+                documentSerial += 1;
+            }
             preparationGate.invalidate('merchant_document_changed');
             mercadoCheckout.invalidate();
             if (stripeCheckout.isPrepared()) {
@@ -1820,97 +2055,48 @@ export async function attachToPlaywright(page, opts) {
             setupStop.abort(failure);
             throw failure;
         }
-        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()) || stripeCheckout.matches(url.toString()) || mercadoCheckout.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())
+            // An armed merchant profile's endpoint or a sibling of it (merchant-hosted.ts), as attachToCdp arms it.
+            || (typeof opts.vault.merchantProfileOf === 'function' && opts.vault.merchantProfileOf(url.toString()) !== null), 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')
-                return route.fallback();
-            if (braintree === 'invalid') {
-                opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
-                return 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.
-            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();
-                    opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
-                    return route.abort('aborted');
-                }
-                return route.fallback();
-            }
+            // When this request paused, and the page it came from: the merchant's total is read as of now.
+            const pausedAt = Date.now();
+            const pausedPage = merchantTotal.pageOf(keyOf(request)) ?? `doc:${documentSerial}`;
+            // One pre-claim gate registry decides and performs the mechanics through
+            // Playwright's own routing; the accessors read the same state the inline
+            // gates did. The matcher only sees the URL, so a preflight, a GET, or any
+            // non-card body continues untouched (route.fallback) or the browser's CORS
+            // check fails on a synthetic answer. It resolves synchronously for an
+            // ordinary card request. Only a pause hands work back below.
+            const preClaimResult = dispatchPreClaim({
+                // headers() and postData() are read lazily, inside the gate that needs them (see
+                // PreClaimContext.request): a Playwright request mock without headers() and no Stripe checkout
+                // never invokes it, and a body Playwright cannot read stops a Mercado checkout the way it did inline.
+                request: { url: request.url(), method: request.method(), get headers() { return request.headers(); }, get body() { return request.postData(); } },
+                vault: opts.vault, guards, mercado: mercadoCheckout, stripe: stripeCheckout,
+                readDocumentUrl, lifecycle, preparationGate, onEvent: opts.onEvent, failureSummary,
+                effects: {
+                    continueRequest: (postData) => postData !== undefined ? route.continue({ postData }) : route.fallback(),
+                    answer: (response) => route.fulfill({ ...response,
+                        headers: withCorsHeaders(response.headers, corsHeadersFor(request.url(), request.headers())) }),
+                    abort: () => route.abort('aborted'),
+                },
+                attachmentReady: () => attachmentReady,
+                interceptionAborted: () => setupStop.signal.aborted,
+                lifecycleAborted: () => lifecycle.abort.signal.aborted,
+                terminal: () => !!terminal,
+                documentClosed: () => !!page.isClosed?.(),
+                stripeAttachmentBusy: () => false,
+                requestInactive: () => !!(page.isClosed?.() || request.failure?.()),
+                awaitingApproval: () => awaitingApproval,
+                stripeStep: null,
+                // This route arrives after every answer the page read before sending it; only an unfollowed 3xx is left to settle.
+                merchantHandoff: { retried: (profile) => merchantHandoff.retried(profile, () => { handoffAnswer?.settle(); return false; }) },
+            });
+            const preClaim = preClaimResult instanceof Promise ? await preClaimResult : preClaimResult;
+            if (preClaim.kind !== 'pause')
+                return;
+            const stripeStep = preClaim.stripeStep;
             if (!attachmentReady || setupStop.signal.aborted) {
                 opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
                 return route.abort('aborted');
@@ -1939,7 +2125,7 @@ export async function attachToPlaywright(page, opts) {
                     catch { /* covered by requestfailed */ }
                     activeRequest.request = request;
                     activeRequest.frames = retryFrames;
-                    opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()), authorizationId: lifecycle.getState().authorizationId, retry: true } });
+                    opts.onEvent?.({ type: 'card_request_paused', detail: { url: eventUrl(opts.vault, request.url()), authorizationId: lifecycle.getState().authorizationId, retry: true } });
                     activeRequest.attempt.bind({ route, request, frames: retryFrames });
                     return;
                 }
@@ -2034,7 +2220,7 @@ export async function attachToPlaywright(page, opts) {
                         void opts.vault.reportDuplicateGuard?.(lastSubmitted.authorizationId);
                     return refused;
                 }
-                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: eventUrl(opts.vault, request.url()) } });
                 lifecycle.begin();
                 const approvalStartedAt = Date.now();
                 const payToInterceptMs = readPayToInterceptMs(opts.payClickedAt, approvalStartedAt);
@@ -2073,6 +2259,8 @@ export async function attachToPlaywright(page, opts) {
                     timeoutMs: opts.timeoutMs,
                     signal: lifecycle.abort.signal,
                     merchantSignal: attempt.signal,
+                    // Same as the CDP path: the merchant's total as this browser recorded it.
+                    merchantTotal: merchantTotal.capture(pausedAt, pausedPage),
                     onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
                     onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
                         lifecycle.approvalUrl(url);
@@ -2119,11 +2307,22 @@ export async function attachToPlaywright(page, opts) {
                     // 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(deliverBody, replay);
+                    // A total the merchant moved while the cardholder decided holds the card here.
+                    if (replay.kind === 'merchant_hosted')
+                        await merchantTotal.release(replay, opts.vault, attempt.signal);
+                    assertRequestLive();
+                    const postData = cseContinuationBody(opts, deliverBody, replay, deliverRequest.url(), preparation);
                     handoffStarted = true;
+                    if (replay.kind === 'merchant_hosted') {
+                        merchantHandoff.begin(replay.profile, replay.authorizationId, replayTemplatedUrl(replay, deliverRequest.url()));
+                        // Watched from before the continue: 5xx, a failure or the page closing is an unknown outcome.
+                        // Once the merchant's final answer arrived, what its confirmation says it charged is reported.
+                        handoffAnswer?.stop();
+                        handoffAnswer = watchPlaywrightHandoff(page, deliverRequest, merchantHandoff, () => merchantTotal.answered(replay, opts.vault));
+                    }
                     await deliverTo.continue({ postData });
                     assertRequestLive();
-                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+                    opts.onEvent?.({ type: 'authorized', detail: cseAuthorizedDetail(replay, deliverRequest.url()) });
                 }
                 else {
                     // Playwright adds these itself when a cross-origin fulfill carries