@agent-cards/sdk 0.22.0 → 0.23.1

package/dist/cdp.js

@@ -11,6 +11,7 @@ import { dispatchPreClaim, eventUrl } from './pre-claim.js';
 import { GMO_TOKEN_V1_PATTERNS, gmoRequestShop, isGmoTokenV1Request, recognizesGmo } from './gmo.js';
 import { DatatransRepeats } from './datatrans.js';
 import { SHIJI_STS_COMPANION_WINDOW_MS, ShijiStsCompanions, ShijiStsError, isShijiStsHost, shijiStsTokenContinuation, } from './shiji-sts.js';
+import { isArmedEkashuUrl } from './ekashu.js';
 import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { cseBody } from './cse-body.js';
 import { STRIPE_SETUP_INTENT_CONFIRM, setupConfirmPayingWith } from './stripe-setup.js';
@@ -21,9 +22,11 @@ import { MERCHANT_PAGE_WAIT_MS, MerchantTotalWatch } from './merchant-total-watc
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { amadeusSendWindowMs, armSendWindow, failsAsNetworkError } from './amadeus.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
-import { CaptureContexts, MicroformFrames, judgeMicroformFrameUrls, refusedRequestFailure } from './cybersource-flex.js';
-import { CARD_ENDPOINT_WITHHELD_ANSWER, CardEndpointRefusedError, captureCardEndpointSession, cardEndpointAnswerHeaders, cardEndpointCookies, cardEndpointDetail, cardEndpointFor, cardEndpointPatterns, } from './card-endpoint.js';
+import { CaptureContexts, MicroformFrames, judgeMicroformFrameUrls, loadedCardMicroformFromUrls, refusedRequestFailure, } from './cybersource-flex.js';
+import { CARD_ENDPOINT_REFUSED_STEP_ANSWER, CARD_ENDPOINT_WITHHELD_ANSWER, CardEndpointRefusedError, captureCardEndpointSession, cardEndpointAnswerHeaders, cardEndpointCookies, cardEndpointDetail, cardEndpointFor, cardEndpointNavigationAnswer, cardEndpointPatterns, cardEndpointResendFor, } from './card-endpoint.js';
+import { CardEndpointFactsWatch } from './card-endpoint-facts.js';
 import { PAYRAILS_GUARD_PATTERNS, PAYRAILS_INIT_BODY_LIMIT, PayrailsSessionCapture, isPayrailsHost, payrailsInitCandidate, recognizesPayrails, } from './payrails.js';
+import { cardEndpointStoppedPage, refusedNavigationOutcome } from './card-endpoint-page.js';
 /**
  * How an adapter fails a paused request it will not let through: as a network error for a
  * CyberSource Flex request (refusedRequestFailure, so the Microform field reports it to the page)
@@ -620,10 +623,24 @@ export function withCorsHeaders(headers, cors) {
 /**
  * The request a card endpoint approval is asked for: `request` names the URL and
  * nothing else, and the profile travels with the captured session in
- * merchant_card_endpoint, the one member the API seals.
+ * merchant_card_endpoint, the one member the API seals, with the merchant's own cut
+ * record of the order for a profile that reads one.
  */
-function cardEndpointRequest(profile, session) {
-    return { url: session.url, method: 'POST', headers: {}, body: '', merchant_card_endpoint: { profile: profile.id, session } };
+function cardEndpointRequest(profile, session, facts = null) {
+    return { url: session.url, method: 'POST', headers: {}, body: '', merchant_card_endpoint: { profile: profile.id, session, ...(facts ? { facts } : {}) } };
+}
+/**
+ * The merchant's own record of the order for a paused card request of a profile that
+ * reads one (card-endpoint-facts.ts), or null for any other profile. A request with no
+ * record to send is refused before any create, naming no value.
+ */
+async function cardEndpointFacts(watch, profile, url, pausedAt, signal) {
+    if (!profile.facts)
+        return null;
+    const captured = await watch.capture(profile, url, pausedAt, signal);
+    if (!captured.record)
+        throw new CardEndpointRefusedError(profile.id, 'facts_unavailable', captured.refusal);
+    return captured.record;
 }
 /** A card endpoint refusal as an event: the profile, the endpoint origin, the reason, and the fields it is about, never a value. */
 function reportCardEndpointRefusal(opts, profile, error) {
@@ -651,6 +668,75 @@ function playwrightCookieParams(cookie) {
         secure: cookie.secure, httpOnly: cookie.httpOnly,
         ...(cookie.sameSite ? { sameSite: cookie.sameSite } : {}), ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}) };
 }
+/**
+ * The page a stopped card form navigation is answered with (card-endpoint-page.ts): the
+ * card never left the device, it reached the merchant and the answer cannot be shown, or
+ * a payment for this checkout is waiting or may have reached the merchant.
+ */
+function stoppedNavigationPage(profile, outcome, reason, authorizationId) {
+    return cardEndpointStoppedPage({ outcome, reason, merchant: profile.merchant, authorizationId });
+}
+/** The API refused the create because this checkout already has a payment waiting or sent (409 merchant_checkout_in_use). */
+function checkoutInUse(error) {
+    return error instanceof CheckoutApiError && error.code === 'merchant_checkout_in_use';
+}
+/**
+ * How a card form navigation the attachment refuses before any approval (not ready, held,
+ * busy, quiet, or after a failure that ends every later request) is answered. The API's
+ * refusal of this checkout as already paying keeps saying so on every later post. Otherwise
+ * the page reads the attachment (refusedNavigationOutcome): while an approval is outstanding,
+ * or once a payment may exist, it says a payment is in progress and names its authorization,
+ * never that nothing was sent.
+ */
+function heldNavigationRefusal(terminal, awaitingApproval, lifecycle) {
+    if (checkoutInUse(terminal))
+        return { outcome: 'payment_in_progress', reason: 'checkout_in_use', authorizationId: null };
+    const state = lifecycle.getState();
+    const outcome = refusedNavigationOutcome({ awaitingApproval, status: state.status });
+    return { outcome, reason: 'blocked', authorizationId: outcome === 'payment_in_progress' ? state.authorizationId : null };
+}
+/**
+ * How a card form navigation whose approval failed is answered, for `authorizationId`. Once
+ * the device approved or the hand-off began (`sent`), the card reached the merchant. Before
+ * that it may have left only while the authorization stood: a PaymentOutcomeUnknownError
+ * whose authorization the API confirmed retired before any processor request
+ * (processorRequestStarted false) sent nothing, and any other one may have reached the
+ * merchant. The API's refusal of a checkout already paying says a payment is in progress.
+ * Every other failure stopped the card before it left.
+ */
+function failedNavigationRefusal(error, sent, authorizationId) {
+    if (sent)
+        return { outcome: 'sent_answer_not_shown', reason: 'outcome_unknown', authorizationId };
+    if (error instanceof PaymentOutcomeUnknownError) {
+        return error.processorRequestStarted === false ? { outcome: 'stopped_before_send', reason: 'not_approved', authorizationId }
+            : { outcome: 'payment_in_progress', reason: 'outcome_unknown', authorizationId };
+    }
+    if (checkoutInUse(error))
+        return { outcome: 'payment_in_progress', reason: 'checkout_in_use', authorizationId };
+    return { outcome: 'stopped_before_send', reason: stoppedBeforeSendReason(error), authorizationId };
+}
+/**
+ * What a Playwright request navigates: 'top' for the page, 'frame' for an iframe, or null
+ * for a fetch, an XHR or a subresource, and for a request whose frame cannot be read.
+ */
+function playwrightNavigation(request) {
+    try {
+        const navigating = typeof request.isNavigationRequest === 'function' ? request.isNavigationRequest() === true : request.resourceType?.() === 'document';
+        if (!navigating)
+            return null;
+        const frame = request.frame?.();
+        if (!frame)
+            return null;
+        return frame.parentFrame?.() ? 'frame' : 'top';
+    }
+    catch {
+        return null;
+    }
+}
+/** Why a card form navigation stopped before its card left, from the error that stopped it. */
+function stoppedBeforeSendReason(error) {
+    return error instanceof CardEndpointRefusedError ? (error.reason === 'not_enabled' ? 'not_enabled' : 'request_unsupported') : 'not_approved';
+}
 /**
  * Answer a paused card endpoint request with what the cardholder's device reported.
  * A withheld answer (it carried the card, or a stream the device cannot read) becomes
@@ -661,15 +747,24 @@ function playwrightCookieParams(cookie) {
  * merchant's status, the profile's answer
  * headers, the CORS answer the request needs, and the body. Resolves false for a
  * withheld answer and true when the merchant's answer was handed over.
+ *
+ * A profile whose page submits its form as a navigation is answered as a page load: a
+ * withheld answer, or a redirect that would make the browser post the form again, gets
+ * the stopped page (the card reached the merchant, the answer is not shown); a 301, 302
+ * or 303 is handed over as a redirect to its one https Location, which the browser
+ * follows in its own session with the merchant's cookies written first; any other
+ * answer is the page itself. No CORS answer rides on a page load.
  */
 async function deliverCardEndpointAnswer(opts, lifecycle, profile, replay, request, io) {
     // Only the request that named this profile is answered from its merchant's answer.
     if (!profile || replay.profile !== profile.id)
         throw new PaymentOutcomeUnknownError(replay.authorizationId, 'approved_mode_unsupported');
     const cors = corsDecision(request.url, request.headers);
+    const navigation = profile.navigation !== null;
     if (replay.withheld) {
-        await io.fulfill({ status: CARD_ENDPOINT_WITHHELD_ANSWER.status, headers: withCorsHeaders({ ...CARD_ENDPOINT_WITHHELD_ANSWER.headers }, cors.headers),
-            body: CARD_ENDPOINT_WITHHELD_ANSWER.body });
+        const fixed = replay.withheld === 'refused_step_in_response' ? CARD_ENDPOINT_REFUSED_STEP_ANSWER : CARD_ENDPOINT_WITHHELD_ANSWER;
+        await io.fulfill(navigation ? stoppedNavigationPage(profile, 'sent_answer_not_shown', 'answer_withheld', replay.authorizationId)
+            : { status: fixed.status, headers: withCorsHeaders({ ...fixed.headers }, cors.headers), body: fixed.body });
         io.assertLive();
         lifecycle.failed(new PaymentOutcomeUnknownError(replay.authorizationId, 'merchant_answer_withheld'), true);
         opts.onEvent?.({ type: 'merchant_answer_withheld', detail: { authorizationId: replay.authorizationId, ...cardEndpointDetail(profile), reason: replay.withheld } });
@@ -687,6 +782,15 @@ async function deliverCardEndpointAnswer(opts, lifecycle, profile, replay, reque
         }
     }
     const { cookies, skipped } = cardEndpointCookies(profile, request.url, replay.setCookies, Date.now(), jar);
+    // A navigation's answer is judged before any cookie is written: a redirect it cannot follow ends on the stopped page.
+    const verdict = navigation ? cardEndpointNavigationAnswer(profile, { status: replay.status, headers: replay.headers }, request.url) : { kind: 'page' };
+    if (verdict.kind === 'refused') {
+        await io.fulfill(stoppedNavigationPage(profile, 'sent_answer_not_shown', verdict.reason, replay.authorizationId));
+        io.assertLive();
+        lifecycle.failed(new PaymentOutcomeUnknownError(replay.authorizationId, 'merchant_redirect_refused'), true);
+        opts.onEvent?.({ type: 'merchant_answer_withheld', detail: { authorizationId: replay.authorizationId, ...cardEndpointDetail(profile), reason: verdict.reason } });
+        return false;
+    }
     let written = 0;
     let refused = 0;
     for (const cookie of cookies) {
@@ -701,10 +805,20 @@ async function deliverCardEndpointAnswer(opts, lifecycle, profile, replay, reque
         }
     }
     io.assertLive();
-    await io.fulfill({ status: replay.status, headers: withCorsHeaders(cardEndpointAnswerHeaders(profile, replay.headers), cors.headers), body: replay.body });
+    if (verdict.kind === 'redirect') {
+        await io.fulfill({ status: verdict.status, headers: { location: verdict.location, 'cache-control': 'no-store' }, body: '' });
+    }
+    else if (navigation) {
+        const headers = cardEndpointAnswerHeaders(profile, replay.headers);
+        delete headers.location;
+        await io.fulfill({ status: replay.status, headers, body: replay.body });
+    }
+    else {
+        await io.fulfill({ status: replay.status, headers: withCorsHeaders(cardEndpointAnswerHeaders(profile, replay.headers), cors.headers), body: replay.body });
+    }
     io.assertLive();
     opts.onEvent?.({ type: 'authorized', detail: { mode: 'card_endpoint', authorizationId: replay.authorizationId, ...cardEndpointDetail(profile),
-            status: replay.status, cors: cors.outcome, cookies: { written, skipped: skipped + refused } } });
+            status: replay.status, ...(navigation ? { answered: verdict.kind } : { cors: cors.outcome }), cookies: { written, skipped: skipped + refused } } });
     return true;
 }
 /** CDP's header shape: `{ name, value }` entries. */
@@ -745,6 +859,21 @@ function pageOriginFrom(documentUrl) {
         return undefined;
     }
 }
+/** The URL of the document the frame `frameId` holds, from the frame tree of the CDP session a request paused on. */
+async function frameUrlIn(cdp, sessionId, frameId) {
+    if (typeof frameId !== 'string' || frameId === '')
+        throw new Error('merchant_document_unavailable');
+    const tree = await cdp.send('Page.getFrameTree', {}, sessionId);
+    const stack = tree?.frameTree ? [tree.frameTree] : [];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node?.frame?.id === frameId && typeof node.frame.url === 'string')
+            return node.frame.url;
+        for (const child of node?.childFrames ?? [])
+            stack.push(child);
+    }
+    throw new Error('merchant_document_unavailable');
+}
 /**
  * The top-level document's URL, read once with a one-second bound when a card
  * request pauses: pageOriginFrom derives the merchant origin from it, and the
@@ -1530,7 +1659,58 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         preparationFrameId = tree.frameTree.frame.id;
         return tree.frameTree.frame.url;
     };
-    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
+    // prepare({ tokenizeBeforePay: true }) sends the card Microform whose field documents are committed
+    // now. A field's commit can come before this attachment enabled its session, so no event reports
+    // it; each iframe session's own frame tree, and the page's, is read once first (as rereadMicroforms
+    // reads the pausing one), and every field found there is recorded (cybersource-flex.ts MicroformFrames).
+    const readLoadedMicroform = async () => {
+        const sessions = [pageSessionId, ...[...ownedSessions].filter(session => sessionTypes.get(session) === 'iframe' && !sessionDetached(session))];
+        await Promise.all(sessions.map(session => rereadMicroforms(session, '').catch(() => undefined)));
+        return microforms.loadedCard();
+    };
+    /**
+     * The frame a paused document request navigates, read from the frame tree of the
+     * session it paused on: 'top' for the page itself, 'frame' for an iframe (a frame with
+     * a parent, or the root of an iframe's own session), with that frame's current
+     * document URL, where the form was submitted. Null when the frame is not in the tree.
+     */
+    const documentFrame = async (sessionId, frameId) => {
+        if (typeof frameId !== 'string' || !frameId)
+            return null;
+        const tree = await cdp.send('Page.getFrameTree', {}, sessionId);
+        const find = (node, depth) => {
+            if (!node || depth > 32)
+                return null;
+            if (node.frame?.id === frameId)
+                return node.frame;
+            for (const child of Array.isArray(node.childFrames) ? node.childFrames : []) {
+                const hit = find(child, depth + 1);
+                if (hit)
+                    return hit;
+            }
+            return null;
+        };
+        const frame = find(tree?.frameTree, 0);
+        if (!frame)
+            return null;
+        return { navigation: frame.parentId || sessionId !== pageSessionId ? 'frame' : 'top', url: typeof frame.url === 'string' ? frame.url : undefined };
+    };
+    /**
+     * Refuse a paused request after the pre-claim gates: a card form navigation gets the
+     * stopped page (card-endpoint-page.ts) that `refusal` describes, since an aborted page
+     * load renders nothing and invites another click on Pay; any other request fails as
+     * cdpFailure says (a network error for CyberSource Flex and Amadeus, else an abort).
+     */
+    const refusePaused = async (requestId, sessionId, url, profile, refusal) => {
+        if (profile && profile.navigation !== null) {
+            const page = stoppedNavigationPage(profile, refusal.outcome, refusal.reason, refusal.authorizationId);
+            await cdp.send('Fetch.fulfillRequest', { requestId, responseCode: page.status, responseHeaders: headerEntries(page.headers),
+                body: Buffer.from(page.body).toString('base64') }, sessionId).catch(() => { });
+            return;
+        }
+        await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(url) }, sessionId).catch(() => { });
+    };
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl, readLoadedMicroform);
     // 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);
@@ -1540,6 +1720,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     // 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);
+    // A reviewed card endpoint merchant's own record of the order (card-endpoint-facts.ts).
+    const cardEndpointRecord = new CardEndpointFactsWatch();
     let handoffReplay = null;
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Payrails sessions this page's own XHR and fetch answers carried, read only
@@ -1722,8 +1904,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     // GMO token v1's JSONP GET is armed only when the synced registry recognizes
     // GMO (an org the API served the dark entry to), so the gate can refuse it;
     // for every other org it is never intercepted, as before (see gmo.ts).
-    // Every reviewed card endpoint is armed in any status: one this build does not pay is
-    // paused only to be refused, so the placeholder card never reaches the merchant.
+    // Every reviewed card endpoint is armed in any status: a card request to one this build
+    // does not pay is paused only to be refused, so the placeholder card never reaches the
+    // merchant, and a request with no card in it continues untouched.
     // Every Payrails host is intercepted only for an org the API served Payrails
     // to, so the gate can abort a card-form payment (see payrails.ts).
     const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns,
@@ -1884,6 +2067,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 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}` } : {}) });
+                cardEndpointRecord.sent(key, { method: params.request.method, url: params.request.url, resourceType: params.type ?? null, networkId: params.requestId });
             }
             if (matchesActive) {
                 try {
@@ -1906,6 +2090,16 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         if (method === 'Network.loadingFinished') {
             const key = requestKey(sessionId, params.requestId);
             requestSources.delete(key);
+            // An out-of-process frame's document finishes on the frame's own session, under the
+            // network id its request was reported with on the parent's (keyFor).
+            const recordKey = cardEndpointRecord.keyFor(key, params.requestId);
+            if (recordKey) {
+                const completedAt = Date.now();
+                // Its place among the answers that finished, before its text is read: texts can come back out of order.
+                cardEndpointRecord.finished(recordKey);
+                cdp.send('Network.getResponseBody', { requestId: params.requestId }, sessionId).then((read) => cardEndpointRecord.read(recordKey, typeof read?.body === 'string'
+                    ? (read.base64Encoded ? Buffer.from(read.body, 'base64').toString('utf8') : read.body) : null, completedAt), () => cardEndpointRecord.read(recordKey, null, completedAt));
+            }
             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();
@@ -1926,6 +2120,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (method === 'Network.responseReceived') {
             merchantTotal.log.answered(requestKey(sessionId, params.requestId), params.response?.status);
+            const recordKey = cardEndpointRecord.keyFor(requestKey(sessionId, params.requestId), params.requestId);
+            if (recordKey)
+                cardEndpointRecord.answered(recordKey, 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);
@@ -1947,6 +2144,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (method === 'Network.loadingFailed') {
             merchantTotal.log.failed(requestKey(sessionId, params.requestId));
+            const recordKey = cardEndpointRecord.keyFor(requestKey(sessionId, params.requestId), params.requestId);
+            if (recordKey)
+                cardEndpointRecord.failed(recordKey);
             if (handoffNetwork && params.requestId === handoffNetwork.networkId && sessionId === handoffNetwork.sessionId)
                 merchantHandoff.failed();
             payrailsAnswers.delete(requestKey(sessionId, params.requestId));
@@ -2109,6 +2309,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             // navigation (the ACI browser test's classic case, design gate G3).
             replacesNavigationBody: async () => true,
             readDocumentUrl, lifecycle, preparationGate, onEvent: opts.onEvent, failureSummary,
+            // Read only for a card endpoint whose page submits its form as a navigation.
+            navigation: async () => (resourceType === 'Document' ? (await documentFrame(sessionId, frameId))?.navigation ?? null : null),
             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,
@@ -2145,13 +2347,15 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         const stripeStep = preClaim.stripeStep;
         // The capture context and fields a CyberSource Flex create carries, and its retry shape.
         const flexPause = preClaim.cybersourceFlex;
-        // A reviewed merchant's own card endpoint this build pays (see card-endpoint.ts).
+        // A reviewed merchant's own card endpoint this build pays (see card-endpoint.ts), and
+        // for one whose page submits its form as a navigation, which frame it navigates.
         const cardEndpoint = preClaim.cardEndpoint ?? null;
         // A Payrails card save the gate bound to a captured session: its key rides on the create.
         const payrailsSidecar = preClaim.payrails;
+        const cardNavigation = preClaim.navigation;
         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: cdpFailure(request.url) }, sessionId).catch(() => { });
+            await refusePaused(requestId, sessionId, request.url, cardEndpoint, heldNavigationRefusal(terminal, awaitingApproval, lifecycle));
             return;
         }
         // A request the catalog marks as routine without a card (a confirmation
@@ -2238,7 +2442,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
             if (preparation)
                 preparationGate.retireUnboundClaim();
-            await cdp.send('Fetch.failRequest', { requestId, errorReason: cdpFailure(request.url) }, sessionId).catch(() => { });
+            // A card form navigation never reads that nothing was sent while a payment for this checkout may exist.
+            await refusePaused(requestId, sessionId, request.url, cardEndpoint, heldNavigationRefusal(terminal, awaitingApproval, lifecycle));
             if (repeatedAuthorizationId)
                 void opts.vault.reportDuplicateGuard?.(repeatedAuthorizationId);
             return;
@@ -2341,12 +2546,23 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 ? await merchantTotal.pageFor(cardKey, MERCHANT_PAGE_WAIT_MS, attempt.signal) : merchantTotal.pageOf(cardKey);
             // The card endpoint's session: the profile's own headers from the paused request,
             // the endpoint's cookie jar for a cookie profile (Chrome keeps it out of the
-            // paused headers, HttpOnly cookies included), and the checkout page's Referer.
+            // paused headers, HttpOnly cookies included), and a Referer on the origin the
+            // request is sent from: the profile's card vault frame when it names one, else
+            // the checkout page.
+            // A form inside an iframe is judged by the iframe's own document, where it was submitted, and
+            // a checkout in a frame the merchant's page embeds by that frame's own document.
+            const capturedOrigin = cardEndpoint?.navigation === 'frame'
+                ? pageOriginFrom((await documentFrame(sessionId, frameId).catch(() => null))?.url)
+                : cardEndpoint?.checkout_frame
+                    ? pageOriginFrom(await documentUrlOf(() => frameUrlIn(cdp, sessionId, frameId), attempt.signal)) : pageOrigin;
             const session = cardEndpoint ? await captureCardEndpointSession(cardEndpoint, {
-                url: request.url, headers: request.headers, body, pageOrigin,
+                url: request.url, headers: request.headers, body, pageOrigin: capturedOrigin, navigation: cardNavigation,
                 cookies: async () => (await cdp.send('Network.getCookies', { urls: [request.url] }, sessionId))?.cookies ?? [],
             }) : null;
             attempt.assertLive();
+            // The merchant's own record of the order, as of the pause, for a profile that reads one.
+            const cardRecord = cardEndpoint ? await cardEndpointFacts(cardEndpointRecord, cardEndpoint, request.url, pausedAt, attempt.signal) : null;
+            attempt.assertLive();
             // Decision 176: pause only. The business creates the authorization from the paused request and answers
             // through controller.resume; the replay it hands back goes down the same delivery path as a create's.
             const pause = opts.pauseOnly ? pauseForBusiness(opts, lifecycle, attempt.signal, { url: request.url, method: request.method, headers: request.headers ?? {}, body }, pageOrigin) : null;
@@ -2376,7 +2592,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     lifecycle.approvalUrl(url);
                     return opts.onApprovalUrl?.(url);
                 } },
-                request: stripeStep?.phase === 'final' ? stripeStep.request : cardEndpoint && session ? cardEndpointRequest(cardEndpoint, session)
+                request: stripeStep?.phase === 'final' ? stripeStep.request : cardEndpoint && session ? cardEndpointRequest(cardEndpoint, session, cardRecord)
                     : { url: request.url, method: request.method, headers: request.headers, body,
                         ...(mercadoCheckout.requiresDocument(request.url, request.method)
                             ? { mercado_checkout: mercadoCheckout.claimToken(request.url, request.method, await readDocumentUrl()) } : {}),
@@ -2565,7 +2781,9 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 reportCardEndpointRefusal(opts, cardEndpoint, err);
                 opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
             }
-            await cdp.send('Fetch.failRequest', { requestId: dead.requestId, errorReason: cdpFailure(request.url) }, dead.sessionId).catch(() => { });
+            // A card form navigation ends on the stopped page: its card reached the merchant once the
+            // device approved (the merchant answered it) or the hand-off began; see failedNavigationRefusal.
+            await refusePaused(dead.requestId, dead.sessionId, request.url, cardEndpoint, failedNavigationRefusal(err, handoffStarted || approvedId !== null, approvedId ?? lifecycle.getState().authorizationId));
             settlePause();
         }
         finally {
@@ -2675,7 +2893,17 @@ export async function attachToPlaywright(page, opts) {
             throw new Error('merchant_document_unavailable');
         return page.url();
     };
-    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
+    // prepare({ tokenizeBeforePay: true }) sends the card Microform whose fields are on the page now.
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl, () => {
+        let frames = [];
+        try {
+            frames = page.frames?.() ?? [];
+        }
+        catch {
+            frames = [];
+        }
+        return loadedCardMicroformFromUrls(frames.map(frameUrlOf));
+    });
     // A merchant-hosted request this attachment continued, and its answer; see watchPlaywrightHandoff.
     const merchantHandoff = new MerchantHandoffWatch(lifecycle, opts.onEvent);
     let handoffAnswer = null;
@@ -2686,6 +2914,8 @@ export async function attachToPlaywright(page, opts) {
     // 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);
+    // A reviewed card endpoint merchant's own record of the order (card-endpoint-facts.ts).
+    const cardEndpointRecord = new CardEndpointFactsWatch();
     let documentSerial = 1;
     // The main frame's document request that no navigation has committed yet.
     let documentRequest = null;
@@ -2713,6 +2943,18 @@ export async function attachToPlaywright(page, opts) {
     // a new document (the handlers below).
     const shijiCompanions = new ShijiStsCompanions();
     lifecycle.abort.signal.addEventListener('abort', () => shijiCompanions.release(), { once: true });
+    // An answer to a request the facts watch records began to arrive: the watch orders what the page sent after a
+    // record by this moment, since Playwright reports the answer's end after the page's next request. Listened to only
+    // once the page sent such a request, so a page that never meets a merchant with facts carries no extra listener.
+    let factsAnswers = false;
+    const factsAnswer = (response) => {
+        try {
+            const key = keyOf(response.request());
+            if (cardEndpointRecord.tracks(key))
+                cardEndpointRecord.answered(key, response.status());
+        }
+        catch { /* a response the page already dropped */ }
+    };
     page.on?.('request', (request) => {
         // A new document is on its way: the main frame's next navigation commits it.
         if (mainDocument(request))
@@ -2723,6 +2965,16 @@ export async function attachToPlaywright(page, opts) {
                 ...(typeof body === 'string' ? { requestBody: body } : {}), page: `doc:${documentSerial}` });
         }
         catch { /* a request the page already dropped */ }
+        try {
+            cardEndpointRecord.sent(keyOf(request), { method: request.method(), url: request.url(),
+                resourceType: typeof request.resourceType === 'function' ? request.resourceType() : null });
+            // From the first request the watch records, it also hears when each answer begins to arrive (factsAnswer).
+            if (!factsAnswers && cardEndpointRecord.tracks(keyOf(request))) {
+                factsAnswers = true;
+                page.on?.('response', factsAnswer);
+            }
+        }
+        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.
@@ -2733,6 +2985,27 @@ export async function attachToPlaywright(page, opts) {
             }).catch(() => { });
         }
         const key = keyOf(request);
+        if (cardEndpointRecord.tracks(key)) {
+            const finishedAt = Date.now();
+            // Its place among the answers that finished, before its text is read: texts can come back out of order.
+            cardEndpointRecord.finished(key);
+            Promise.resolve().then(async () => {
+                const response = await request.response();
+                if (!response) {
+                    cardEndpointRecord.failed(key);
+                    return;
+                }
+                cardEndpointRecord.answered(key, response.status());
+                let text = null;
+                try {
+                    text = await response.text();
+                }
+                catch {
+                    text = null;
+                }
+                cardEndpointRecord.read(key, text, finishedAt);
+            }).catch(() => cardEndpointRecord.failed(key));
+        }
         if (!merchantTotal.log.tracks(key))
             return;
         const completedAt = Date.now();
@@ -2802,6 +3075,7 @@ export async function attachToPlaywright(page, opts) {
         if (request === documentRequest)
             documentRequest = null;
         merchantTotal.log.failed(keyOf(request));
+        cardEndpointRecord.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
@@ -2899,11 +3173,17 @@ export async function attachToPlaywright(page, opts) {
             // GMO token v1's JSONP GET, routed only for an org the API served GMO to (see attachToCdp).
             || (isGmoTokenV1Request(url.toString()) && recognizesGmo(opts.vault))
             || juspayCheckout.matches(url.toString())
-            // Every reviewed card endpoint, in any status (the pre-claim gate refuses one this build does not pay).
+            // Every reviewed card endpoint, in any status (the pre-claim gate holds only a request that carries a card,
+            // and refuses one this build does not pay).
             || cardEndpointFor(url.toString(), 'POST') !== null
+            // A request that sends the typed card to such a merchant again, refused in every status.
+            || cardEndpointResendFor(url.toString(), 'POST') !== null
             || aci.matches(url.toString())
             // Every Payrails host, routed only for an org the API served Payrails to (see attachToCdp).
-            || (payrails !== null && isPayrailsHost(url.toString())), async (route) => {
+            || (payrails !== null && isPayrailsHost(url.toString()))
+            // Every request to an NMI host whose entry is served (ekashu.ts), as attachToCdp arms the
+            // host: the card page's post and its 3-D Secure calls reach the NMI gate and fail.
+            || isArmedEkashuUrl(opts.vault, url.toString()), async (route) => {
             const request = route.request();
             // When this request paused, and the page it came from: the merchant's total is read as of now.
             const pausedAt = Date.now();
@@ -2944,6 +3224,8 @@ export async function attachToPlaywright(page, opts) {
                 // the body route.continue replaces on a navigation (aci.ts playwrightReplacesNavigationBody).
                 replacesNavigationBody: () => (navigationBodyReplaced ??= playwrightReplacesNavigationBody(page)),
                 readDocumentUrl, lifecycle, preparationGate, onEvent: opts.onEvent, failureSummary,
+                // Read only for a card endpoint whose page submits its form as a navigation (see attachToCdp).
+                navigation: async () => playwrightNavigation(request),
                 effects: {
                     continueRequest: (postData) => postData !== undefined ? route.continue({ postData }) : route.fallback(),
                     answer: (response) => route.fulfill({ ...response,
@@ -3004,13 +3286,20 @@ export async function attachToPlaywright(page, opts) {
             const stripeStep = preClaim.stripeStep;
             // The capture context and fields a CyberSource Flex create carries, and its retry shape.
             const flexPause = preClaim.cybersourceFlex;
-            // A reviewed merchant's own card endpoint this build pays (see card-endpoint.ts).
+            // A reviewed merchant's own card endpoint this build pays (see card-endpoint.ts), and
+            // for one whose page submits its form as a navigation, which frame it navigates.
             const cardEndpoint = preClaim.cardEndpoint ?? null;
             // A Payrails card save the gate bound to a captured session: its key rides on the create.
             const payrailsSidecar = preClaim.payrails;
+            const cardNavigation = preClaim.navigation;
+            // A card form navigation is refused with the stopped page, anything else as refusalFailure says (see attachToCdp
+            // refusePaused).
+            const refuseRoute = (target, refusal) => (cardEndpoint && cardEndpoint.navigation !== null
+                ? target.fulfill(stoppedNavigationPage(cardEndpoint, refusal.outcome, refusal.reason, refusal.authorizationId))
+                : target.abort(refusalFailure(request.url())));
             if (!attachmentReady || setupStop.signal.aborted) {
                 opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
-                return route.abort(refusalFailure(request.url()));
+                return refuseRoute(route, heldNavigationRefusal(terminal, awaitingApproval, lifecycle));
             }
             // Same order as attachToCdp: a routine card-free request continues in
             // every state, before the preparation claim, so it neither spends a
@@ -3082,7 +3371,8 @@ export async function attachToPlaywright(page, opts) {
                 opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
                 if (preparation)
                     preparationGate.retireUnboundClaim();
-                const refused = await route.abort(refusalFailure(request.url()));
+                // As in attachToCdp: never that nothing was sent while a payment for this checkout may exist.
+                const refused = await refuseRoute(route, heldNavigationRefusal(terminal, awaitingApproval, lifecycle));
                 if (repeatedAuthorizationId)
                     void opts.vault.reportDuplicateGuard?.(repeatedAuthorizationId);
                 return refused;
@@ -3171,11 +3461,28 @@ export async function attachToPlaywright(page, opts) {
                 assertRequestLive();
                 // The card endpoint's session (see attachToCdp): request.headers() never carries
                 // the cookie jar, so the endpoint's cookies are read from the context.
+                // A form inside an iframe is judged by the iframe's own document, where it was submitted, and
+                // a checkout in a frame the merchant's page embeds by that frame's own document.
+                let capturedOrigin = pageOrigin;
+                if (cardEndpoint?.navigation === 'frame') {
+                    try {
+                        capturedOrigin = pageOriginFrom(request.frame?.()?.url?.());
+                    }
+                    catch {
+                        capturedOrigin = undefined;
+                    }
+                }
+                else if (cardEndpoint?.checkout_frame) {
+                    capturedOrigin = pageOriginFrom(await documentUrlOf(async () => String(request.frame().url()), attempt.signal));
+                }
                 const session = cardEndpoint ? await captureCardEndpointSession(cardEndpoint, {
-                    url: request.url(), headers: request.headers(), body, pageOrigin,
+                    url: request.url(), headers: request.headers(), body, pageOrigin: capturedOrigin, navigation: cardNavigation,
                     cookies: async () => await page.context().cookies(request.url()),
                 }) : null;
                 assertRequestLive();
+                // The merchant's own record of the order, as of the pause (see attachToCdp).
+                const cardRecord = cardEndpoint ? await cardEndpointFacts(cardEndpointRecord, cardEndpoint, request.url(), pausedAt, attempt.signal) : null;
+                assertRequestLive();
                 const replay = await opts.vault.authorize({
                     user: opts.user,
                     merchant: opts.merchant,
@@ -3200,7 +3507,7 @@ export async function attachToPlaywright(page, opts) {
                         lifecycle.approvalUrl(url);
                         return opts.onApprovalUrl?.(url);
                     } },
-                    request: stripeStep?.phase === 'final' ? stripeStep.request : cardEndpoint && session ? cardEndpointRequest(cardEndpoint, session)
+                    request: stripeStep?.phase === 'final' ? stripeStep.request : cardEndpoint && session ? cardEndpointRequest(cardEndpoint, session, cardRecord)
                         : { url: request.url(), method: request.method(), headers: request.headers(), body,
                             ...(mercadoCheckout.requiresDocument(request.url(), request.method())
                                 ? { mercado_checkout: mercadoCheckout.claimToken(request.url(), request.method(), await readDocumentUrl()) } : {}),
@@ -3340,7 +3647,8 @@ export async function attachToPlaywright(page, opts) {
                     reportCardEndpointRefusal(opts, cardEndpoint, err);
                     opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
                 }
-                await dead.abort(refusalFailure(request.url())).catch(() => { });
+                // As in attachToCdp: a card form navigation ends on the stopped page (failedNavigationRefusal).
+                await Promise.resolve().then(() => refuseRoute(dead, failedNavigationRefusal(err, handoffStarted || approvedId !== null, approvedId ?? lifecycle.getState().authorizationId))).catch(() => { });
             }
             finally {
                 disarmSendWindow?.();