@agent-cards/checkout 0.15.2 → 0.16.0

package/dist/cdp.js

@@ -306,7 +306,29 @@ function headerEntries(headers) {
  * undefined and the authorization goes out without one (a merchant, category
  * or place rule then refuses it as unknown, never the request itself).
  */
-async function pageOriginOf(readDocumentUrl, signal) {
+function pageOriginFrom(documentUrl) {
+    if (typeof documentUrl !== 'string')
+        return undefined;
+    try {
+        const url = new URL(documentUrl);
+        if (url.username || url.password)
+            return undefined;
+        if (url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost'))
+            return url.origin;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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
+ * retry rule (sameCheckoutRequest) compares it. Undefined when the page
+ * cannot be read, the attempt was stopped, or the read was late; the
+ * authorization then goes out without a page origin and no retry can bind.
+ */
+async function documentUrlOf(readDocumentUrl, signal) {
     let timer;
     let abort;
     try {
@@ -320,14 +342,7 @@ async function pageOriginOf(readDocumentUrl, signal) {
                     abort();
             }),
         ]);
-        if (typeof documentUrl !== 'string')
-            return undefined;
-        const url = new URL(documentUrl);
-        if (url.username || url.password)
-            return undefined;
-        if (url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost'))
-            return url.origin;
-        return undefined;
+        return typeof documentUrl === 'string' ? documentUrl : undefined;
     }
     catch {
         return undefined;
@@ -391,13 +406,250 @@ function failureSummary(error) {
         return `${error.name}: ${error.code ?? `http_${error.status}`}`;
     return error instanceof Error ? error.name : 'CheckoutError';
 }
-/** Separate from explicit cancellation: the client can drain a late create ID. */
-function merchantAttempt(lifecycle) {
+/**
+ * How long an approval waits, after the cardholder gives it, for the page to
+ * issue the request it will answer.
+ *
+ * This only matters when the page's own script abandoned its card request
+ * while the person was deciding (Braintree's client gives up after 60
+ * seconds, Square's after about 10) and did not ask again on its own. The
+ * approval is real: the device sent the card to the processor and a token
+ * came back, or encrypted it for the agent's browser. What is missing is a
+ * request to hand it to, and the application supplies one by clicking Pay
+ * again (the controller reads `ready_to_submit` with reason
+ * `awaiting_merchant_retry` while this wait runs). Two minutes is a first
+ * value, chosen rather than measured: long enough for an agent loop to read
+ * the state and act, short enough that a minted token never sits usable for
+ * the rest of the approval window. The approval window itself is the ceiling,
+ * whatever this is set to. Overridable per attach via `merchantRetryWaitMs`;
+ * the benchmark's retry gaps are what should replace it.
+ */
+const MERCHANT_RETRY_WAIT_MS = 2 * 60_000;
+function retryWaitMs(value) {
+    if (value === undefined)
+        return MERCHANT_RETRY_WAIT_MS;
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 15 * 60_000) {
+        throw new Error('merchantRetryWaitMs must be an integer between 1 and 900000.');
+    }
+    return value;
+}
+/** The page never asked again inside the retry wait; see merchantAttempt.awaitTarget. */
+class MerchantNeverRetried extends Error {
+    authorizationId;
+    constructor(authorizationId) {
+        super('the merchant page never asked again');
+        this.authorizationId = authorizationId;
+        this.name = 'MerchantNeverRetried';
+    }
+}
+/** A body field that names the purchase's amount or currency, wherever a processor puts it. */
+const AMOUNT_KEY = /^(amount|amount_?cents|total|sum|currency|currency_?code)$/i;
+/**
+ * The amount and currency a body names, as `path=value` pairs: Adyen's
+ * `amount.value` and `amount.currency`, Razorpay's and Nuvei's `amount`
+ * and `currency`, Paysafe's `amount` and `currencyCode`, Tranzila's `sum`.
+ * A pure tokenization (Braintree, Square, Shopify, a Stripe PaymentMethod)
+ * names none and yields an empty list.
+ */
+function bodyAmounts(value, prefix, parentKey, out) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            bodyAmounts(item, `${prefix}[]`, parentKey, out);
+        return;
+    }
+    if (value === null || typeof value !== 'object') {
+        const key = prefix.split('.').pop() ?? '';
+        if (AMOUNT_KEY.test(key) || (key === 'value' && AMOUNT_KEY.test(parentKey)))
+            out.push(`${prefix}=${String(value)}`);
+        return;
+    }
+    const own = prefix.split('.').pop() ?? '';
+    for (const [key, child] of Object.entries(value))
+        bodyAmounts(child, prefix ? `${prefix}.${key}` : key, own, out);
+}
+/** The document a request came from, as compared between a request and its retry. */
+function documentKey(url) {
+    if (typeof url !== 'string')
+        return undefined;
+    try {
+        const parsed = new URL(url);
+        parsed.hash = '';
+        return parsed.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Luhn, on a run of digits: the placeholder card the agent typed passes it, most other long numbers do not. */
+function luhn(digits) {
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = digits.charCodeAt(digits.length - 1 - i) - 48;
+        if (i % 2 === 1) {
+            d *= 2;
+            if (d > 9)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return sum % 10 === 0;
+}
+/**
+ * The card-placeholder runs in a body: every 13 to 19 digit run that passes
+ * Luhn, sorted. The placeholder the agent typed (4242 4242 4242 4242, 4111
+ * 1111 1111 1111) passes; a millisecond timestamp or an order number fails
+ * nine times in ten, and when one passes it merely makes the match stricter.
+ * A client-side-encrypted body (Adyen) carries no digits at all and yields
+ * an empty list on both sides.
+ */
+function cardRuns(body) {
+    return (body.match(/\d{13,19}/g) ?? []).filter(luhn).sort();
+}
+/** Every key path in a JSON value, arrays flattened so an element's order or count does not count. */
+function jsonKeyPaths(value, prefix, out) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            jsonKeyPaths(item, `${prefix}[]`, out);
+        return;
+    }
+    if (value === null || typeof value !== 'object') {
+        if (prefix)
+            out.add(prefix);
+        return;
+    }
+    for (const [key, child] of Object.entries(value))
+        jsonKeyPaths(child, prefix ? `${prefix}.${key}` : key, out);
+}
+/**
+ * The shape of a body plus its card placeholder, as a string two bodies can
+ * be compared by. JSON: its sorted key paths and its card runs, so a body the
+ * client regenerated (a new session id, a new nonce, a fresh encryption of
+ * the same dummy card) still matches while a different operation, a saved
+ * card or another card does not. Form-encoded: its sorted keys and its card
+ * runs, so Stripe's per-attempt `time_on_page` and fraud ids do not break a
+ * match but a different field set does. Anything else: the body itself.
+ */
+function bodyShape(body) {
+    const runs = cardRuns(body).join(',');
+    const trimmed = body.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(body);
+            const paths = new Set();
+            jsonKeyPaths(parsed, '', paths);
+            const amounts = [];
+            bodyAmounts(parsed, '', '', amounts);
+            return { shape: `json:${[...paths].sort().join('|')};cards:${runs};amounts:${amounts.sort().join('|')}`, namesAmount: amounts.length > 0 };
+        }
+        catch { /* not JSON after all */ }
+    }
+    if (/^[^=&\s]+=[^&]*(&[^=&\s]+=[^&]*)*$/.test(body)) {
+        const params = new URLSearchParams(body);
+        const keys = [...new Set([...params.keys()])].sort();
+        const amounts = [...params.entries()].filter(([key]) => AMOUNT_KEY.test(key)).map(([key, value]) => `${key}=${value}`).sort();
+        return { shape: `form:${keys.join('|')};cards:${runs};amounts:${amounts.join('|')}`, namesAmount: amounts.length > 0 };
+    }
+    return { shape: `raw:${body}`, namesAmount: false };
+}
+/** The identity of a request from its parts; see CheckoutRequestIdentity. */
+function requestIdentity(opts, url, method, body, documentUrl, pageAmount) {
+    const shaped = bodyShape(body);
+    return { url, method, documentUrl, pageAmount, body: shaped.shape,
+        amountEvidence: opts.amount != null || pageAmount !== undefined || shaped.namesAmount };
+}
+/**
+ * May this request be answered from the approval the other one raised?
+ *
+ * The plan this implements says the rule starts strict and loosens per
+ * processor with evidence, so it is strict: the same processor endpoint (the
+ * full URL, query included), the same method, the same top-level document,
+ * the same page total when the integrator reads one, and a body of the same
+ * shape carrying the same card placeholder and the same amount when the
+ * request names one. A request from another page, to another endpoint, for
+ * another card, for another amount or with another set of fields is a new
+ * question and is refused here, which leaves it to the ordinary "an approval
+ * is already outstanding" path.
+ *
+ * An amount has to be in evidence somewhere: the integrator's hint (what the
+ * cardholder was shown), the page total, or the request's own bytes. A
+ * tokenization request names no amount, so on a checkout with no hint and no
+ * page reader nothing could tell a retry for the approved cart from one for
+ * a changed cart, and the approval is not reused. With a page reader, a
+ * changed total refuses the retry; the hint is the integrator's statement of
+ * the purchase, and the approval was given for it.
+ */
+function sameCheckoutRequest(first, retry) {
+    return first.amountEvidence && first.url === retry.url && first.method.toUpperCase() === retry.method.toUpperCase()
+        && first.documentUrl !== undefined && first.documentUrl === retry.documentUrl
+        && (first.pageAmount?.amount === retry.pageAmount?.amount && first.pageAmount?.currency === retry.pageAmount?.currency)
+        && first.body === retry.body;
+}
+/**
+ * Whether an approval may outlive the page's own request on this checkout.
+ *
+ * Yes for a plain tokenization or an encrypted-card request: the device's
+ * answer is a token or ciphertext, and any request for the same purchase can
+ * carry it. No for a hosted form (a navigation: there is no request to
+ * answer once the page has moved on), a prepared checkout (single use, bound
+ * to one native request by design), a native Stripe Checkout step, and a
+ * Mercado Pago request whose claim is bound to one document read. Unknown
+ * modes (a duck-typed vault without checkoutModeOf) are taken as `token`.
+ */
+function survivesAbandonment(opts, url, method, navigation, bound) {
+    if (navigation || bound)
+        return false;
+    const mode = typeof opts.vault?.checkoutModeOf === 'function' ? opts.vault.checkoutModeOf(url, method) : 'token';
+    return mode === 'token' || mode === 'cse';
+}
+/**
+ * One card request's attempt at an approval, and the browser request that
+ * currently carries it. Separate from explicit cancellation: the client can
+ * drain a late create ID.
+ *
+ * The request and the approval have different lives. The page's own script
+ * can abandon its request (Braintree's client gives up after 60 seconds,
+ * Square's after about 10) while the cardholder is still deciding on their
+ * phone; nothing about the checkout changed, the page asked and stopped
+ * listening. lose() records that: the approval keeps polling, the page's next
+ * request for the same purchase binds through bind() and is answered from the
+ * same authorization, and awaitTarget() is how the approval finds the request
+ * to answer, waiting for a retry when none is live. stop() is for the page
+ * itself going away (navigation of a prepared document, frame removal, close,
+ * crash), a request lost once delivery began, or an attempt that cannot
+ * survive abandonment at all: the approval cannot be reopened and the client
+ * cancels it.
+ */
+function merchantAttempt(lifecycle, survives) {
     const controller = new AbortController();
     let reason = 'merchant_request_aborted';
+    let target = null;
+    let lost = false;
+    let rebound = false;
+    let delivering = false;
+    let bound = null;
     const error = () => new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, reason);
-    return {
+    const attempt = {
         signal: controller.signal,
+        /** The browser request that currently carries this attempt; null while the page has none. */
+        get target() { return target; },
+        /** The page abandoned its request and has not asked again yet. */
+        get lost() { return lost; },
+        bind(next) { target = next; rebound = lost; lost = false; bound?.(); },
+        /** Delivery to the current target has begun; a loss from here on is an unknown outcome, never a retry. */
+        beginDelivery() { delivering = true; },
+        /** The page abandoned the current request. True when the approval survives it, false when the attempt stopped. */
+        lose() {
+            if (controller.signal.aborted)
+                return false;
+            if (!survives || delivering) {
+                attempt.stop();
+                return false;
+            }
+            target = null;
+            lost = true;
+            lifecycle.merchantRequestLost();
+            return true;
+        },
         stop(cause = 'merchant_request_aborted') {
             if (controller.signal.aborted)
                 return;
@@ -410,7 +662,82 @@ function merchantAttempt(lifecycle) {
         },
         assertLive() { if (controller.signal.aborted)
             throw error(); },
+        /**
+         * The request to answer: the live one at once, or the page's retry,
+         * waited for up to `waitMs`. Resolves `rebound` when the answer goes to
+         * a request other than the one that raised the approval, so the caller
+         * can re-run request attribution on it. Rejects with MerchantNeverRetried
+         * when the wait ends with no request, and with the attempt's own error
+         * when the page goes away meanwhile.
+         */
+        async awaitTarget(waitMs, stopSignals, onWaiting) {
+            attempt.assertLive();
+            if (target && !lost)
+                return { target, rebound };
+            onWaiting();
+            const signals = [controller.signal, ...stopSignals];
+            let timer;
+            let onAbort = () => { };
+            try {
+                await new Promise((resolve, reject) => {
+                    bound = resolve;
+                    onAbort = () => { try {
+                        attempt.assertLive();
+                        reject(new Error('checkout cancelled locally before the merchant asked again'));
+                    }
+                    catch (stopped) {
+                        reject(stopped);
+                    } };
+                    for (const signal of signals)
+                        signal.addEventListener('abort', onAbort, { once: true });
+                    if (signals.some((signal) => signal.aborted))
+                        onAbort();
+                    timer = setTimeout(() => reject(new MerchantNeverRetried(lifecycle.getState().authorizationId)), waitMs);
+                });
+            }
+            finally {
+                bound = null;
+                clearTimeout(timer);
+                for (const signal of signals)
+                    signal.removeEventListener('abort', onAbort);
+            }
+            attempt.assertLive();
+            if (!target)
+                throw new MerchantNeverRetried(lifecycle.getState().authorizationId);
+            return { target, rebound };
+        },
     };
+    return attempt;
+}
+/**
+ * The retry wait, capped by what is left of the approval window: a token
+ * must never sit usable past the moment the row itself would have expired.
+ */
+function boundedRetryWait(waitMs, approvalStartedAt, timeoutMs) {
+    const windowEnd = approvalStartedAt + (timeoutMs ?? 15 * 60_000);
+    return Math.max(0, Math.min(waitMs, windowEnd - Date.now()));
+}
+/**
+ * Retire an approval the page never asked for again, and tell the lifecycle
+ * what became of it. A confirmed retirement ends as `declined` with reason
+ * `merchant_never_retried` (the cardholder's screen says the merchant did
+ * not finish and nothing was charged, and the next card request is a new
+ * question); anything else is an unknown outcome the application must
+ * reconcile, which holds the attachment. A vault without cancelAuthorization
+ * (a duck-typed client) cannot retire anything and lands there too.
+ */
+async function retireUnusedApproval(opts, lifecycle, authorizationId) {
+    const cancel = typeof opts.vault?.cancelAuthorization === 'function' && authorizationId
+        ? opts.vault.cancelAuthorization(authorizationId, 'merchant_never_retried') : Promise.reject(new Error('no authorization to retire'));
+    try {
+        await cancel;
+        lifecycle.merchantNeverRetried(authorizationId);
+        opts.onEvent?.({ type: 'failed', detail: 'merchant_never_retried' });
+    }
+    catch {
+        lifecycle.failed(new PaymentOutcomeUnknownError(authorizationId, 'authorization_cancel_unconfirmed'), true);
+        opts.onEvent?.({ type: 'failed', detail: 'PaymentOutcomeUnknownError' });
+    }
 }
 /**
  * Take over card tokenization for a page.
@@ -507,6 +834,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    // How long an approval waits for the page to ask again; see MERCHANT_RETRY_WAIT_MS.
+    const retryWait = retryWaitMs(opts.merchantRetryWaitMs);
     let activeRequest = null;
     const sourceOwner = (source) => workerOwners.get(source.sessionId) ?? source.sessionId;
     const retireSource = (source) => {
@@ -716,6 +1045,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             }
             if (preparationGate.isEngaged())
                 activeRequest?.attempt.stop();
+            // The page that abandoned its request has moved to another document:
+            // its approval cannot be answered there and is cancelled. A reload of
+            // the same document is not that; its re-issued request is the retry.
+            if (method === 'Page.frameNavigated' && activeRequest?.attempt.lost
+                && documentKey(params.frame?.url) !== activeRequest.identity.documentUrl)
+                activeRequest.attempt.stop();
             return;
         }
         if ((method === 'Inspector.detached' && sessionId === pageSessionId)
@@ -761,9 +1096,26 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         if (method === 'Network.loadingFailed') {
-            if (activeRequest && activeRequest.networkId === params.requestId
-                && activeRequest.sourceSessionId === sessionId)
-                activeRequest.attempt.stop();
+            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
+                // stops the attempt. A worker's retry pauses on the owning frame and
+                // is attributed only through the worker's own Network events, and
+                // binding an approval across that attribution is not something this
+                // change claims to get right; the observed failure is page script.
+                const fromWorker = sessionId !== activeRequest.sessionId;
+                if (fromWorker ? (activeRequest.attempt.stop(), false) : activeRequest.attempt.lose()) {
+                    // The page's own script gave up on its request; the cardholder's
+                    // approval did not (see merchantAttempt). Release the dead
+                    // interception and forget the request's identity, so no later event
+                    // on it can pass for the retry's.
+                    activeRequest.networkId = '';
+                    activeRequest.frameId = undefined;
+                    activeRequest.sourceSessionId = undefined;
+                    opts.onEvent?.({ type: 'merchant_request_lost', detail: { authorizationId: lifecycle.getState().authorizationId } });
+                    cdp.send('Fetch.failRequest', { requestId: dead.requestId, errorReason: 'Aborted' }, dead.sessionId).catch(() => { });
+                }
+            }
             const key = requestKey(sessionId, params.requestId);
             retireSource(requestSources.get(key) ?? { sessionId, networkId: params.requestId });
             requestSources.delete(key);
@@ -940,13 +1292,37 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         let preparation;
         try {
-            preparation = stripeStep ? undefined : preparationGate.claim(request.url, pausedBody(request));
+            preparation = stripeStep ? undefined : preparationGate.claim(request.url, pausedBody(request), request.headers);
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
+        // The page asking again for the purchase an outstanding approval is for:
+        // its own request timed out while the cardholder decides (see
+        // merchantAttempt). Bind it to that approval instead of refusing it or
+        // raising a second prompt. A request that is not the same purchase falls
+        // through to the ordinary refusal below.
+        if (awaitingApproval && activeRequest?.attempt.lost && !terminal && !setupStop.signal.aborted && !lifecycle.isCancelled()
+            && typeof networkId === 'string' && networkId) {
+            const retryBody = pausedBody(request);
+            const retry = retryBody === null ? null : requestIdentity(opts, request.url, request.method, retryBody, documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts));
+            if (retry && activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+                activeRequest.requestId = requestId;
+                activeRequest.networkId = networkId;
+                activeRequest.sessionId = sessionId;
+                activeRequest.frameId = frameId;
+                activeRequest.request = request;
+                activeRequest.sourceSessionId = undefined;
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}),
+                        authorizationId: lifecycle.getState().authorizationId, retry: true } });
+                activeRequest.attempt.bind({ requestId, sessionId, request });
+                return;
+            }
+        }
         // Same stop condition as the Playwright adapter: once a failure proves
         // retrying is pointless, fail the request without calling the API again.
         if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
@@ -961,8 +1337,11 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         // requests can never both clear the check above and raise two prompts for
         // one checkout.
         awaitingApproval = true;
-        const attempt = merchantAttempt(lifecycle);
+        const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url, request.method, resourceType === 'Document', !!preparation || !!stripeStep || mercadoCheckout.requiresDocument(request.url, request.method)));
         let handoffStarted = false;
+        // The approval the device gave, and whether it reached a browser request.
+        let approvedId = null;
+        let deliveryBegun = false;
         try {
             const body = pausedBody(request);
             if (body === null) {
@@ -983,17 +1362,26 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
             lifecycle.begin();
+            const approvalStartedAt = Date.now();
             if (typeof networkId !== 'string' || !networkId) {
                 attempt.stop();
                 attempt.assertLive();
             }
-            activeRequest = { attempt, networkId, sessionId, frameId, request };
+            attempt.bind({ requestId, sessionId, request });
+            activeRequest = { attempt, requestId, networkId, sessionId, frameId, request,
+                identity: requestIdentity(opts, request.url, request.method, body, undefined, undefined) };
             await awaitRequestSource(activeRequest);
             if (preparation)
                 await preparationGate.assertDocument();
-            const pageOrigin = await pageOriginOf(readDocumentUrl, attempt.signal);
+            // One bounded read of the document serves both the merchant origin and
+            // the identity a retry has to repeat (see sameCheckoutRequest).
+            const documentUrl = await documentUrlOf(readDocumentUrl, attempt.signal);
+            const pageOrigin = pageOriginFrom(documentUrl);
             const pageAmount = await pageAmountOf(opts);
             attempt.assertLive();
+            activeRequest.identity.documentUrl = documentKey(documentUrl);
+            activeRequest.identity.pageAmount = pageAmount;
+            activeRequest.identity.amountEvidence ||= pageAmount !== undefined;
             if (stripeStep)
                 stripeCheckout.assertClaim(stripeStep);
             const merchantOrigin = preparation?.merchantOrigin ?? (opts.executionMode === 'user_approval'
@@ -1025,6 +1413,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                         ? { mercado_checkout: mercadoCheckout.claimToken(request.url, request.method, await readDocumentUrl()) } : {}) },
             });
             attempt.assertLive();
+            approvedId = replay.authorizationId;
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
             try {
@@ -1034,7 +1423,23 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 throw new PaymentOutcomeUnknownError(replay.authorizationId, 'mercado_checkout_metadata_invalid');
             }
             attempt.assertLive();
-            lifecycle.prepareHandoff(replay, request.url);
+            // The request to answer: the one that raised the approval while it is
+            // still paused, or the page's retry when the page gave up on the first
+            // (waited for, bounded; see merchantAttempt.awaitTarget). A retry is
+            // attributed to its frame or worker exactly as the first request was.
+            const delivery = await attempt.awaitTarget(boundedRetryWait(retryWait, approvalStartedAt, opts.timeoutMs), [lifecycle.abort.signal, setupStop.signal], () => {
+                lifecycle.awaitingMerchantRetry(replay.authorizationId);
+                opts.onEvent?.({ type: 'approval_awaiting_merchant_retry', detail: { authorizationId: replay.authorizationId } });
+            });
+            if (delivery.rebound) {
+                await awaitRequestSource(activeRequest);
+                attempt.assertLive();
+            }
+            const { requestId: deliverTo, sessionId: deliverOn, request: deliverRequest } = delivery.target;
+            const deliverBody = delivery.rebound ? pausedBody(deliverRequest) ?? body : body;
+            deliveryBegun = true;
+            attempt.beginDelivery();
+            lifecycle.prepareHandoff(replay, deliverRequest.url);
             handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
                 // The device submitted the processor's own form; the processor
@@ -1046,13 +1451,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // A navigation response is never CORS-checked, so the CORS wrap is
                 // inert here; it is applied so every fulfill goes through one path.
                 await cdp.send('Fetch.fulfillRequest', {
-                    requestId,
+                    requestId: deliverTo,
                     responseCode: page.status,
-                    responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
+                    responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(deliverRequest.url, deliverRequest.headers))),
                     body: Buffer.from(page.body).toString('base64'),
-                }, sessionId);
+                }, deliverOn);
                 attempt.assertLive();
-                lastSubmitted = { url: request.url, body, at: Date.now() };
+                lastSubmitted = { url: deliverRequest.url, body: deliverBody, at: Date.now() };
                 // Named for what it is: a device-attested submission with no
                 // processor evidence, never an `authorized` event.
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
@@ -1063,12 +1468,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // 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(body, replay)).toString('base64');
+                const postData = Buffer.from(cseBody(deliverBody, replay)).toString('base64');
                 handoffStarted = true;
                 await cdp.send('Fetch.continueRequest', {
-                    requestId,
+                    requestId: deliverTo,
                     postData,
-                }, sessionId);
+                }, deliverOn);
                 attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
@@ -1079,13 +1484,13 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // decision rides on the event, so a fulfill the page could not read
                 // (no usable Origin on a cross-origin request) is visible in telemetry
                 // rather than only as the page's own "connection error".
-                const cors = corsDecision(request.url, request.headers);
+                const cors = corsDecision(deliverRequest.url, deliverRequest.headers);
                 await cdp.send('Fetch.fulfillRequest', {
-                    requestId,
+                    requestId: deliverTo,
                     responseCode: replay.status,
                     responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
-                }, sessionId);
+                }, deliverOn);
                 attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
@@ -1093,6 +1498,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         catch (err) {
             // Ignore the failure event caused by our own safe decline/error abort.
+            const dead = attempt.target ?? { requestId, sessionId };
             if (activeRequest?.attempt === attempt)
                 activeRequest = null;
             // Vault clients may normalize a merchantSignal abort. Preserve the
@@ -1103,15 +1509,25 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             catch (stopped) {
                 err = stopped;
             }
-            // stop() already published the terminal state before aborting the Vault.
-            if (!attempt.signal.aborted)
-                lifecycle.failed(err, handoffStarted);
-            if (isTerminal(err))
-                terminal = err;
-            else if (isApprovalOutcome(err))
+            if (err instanceof MerchantNeverRetried || (attempt.signal.aborted && approvedId && !deliveryBegun)) {
+                // The device approved and no request ever carried the answer: the
+                // page never asked again, or went away while the approval waited.
+                // Retire it (see retireUnusedApproval) and quiet the page's next
+                // request as after any other answered approval.
+                await retireUnusedApproval(opts, lifecycle, approvedId);
                 quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            }
+            else {
+                // stop() already published the terminal state before aborting the Vault.
+                if (!attempt.signal.aborted)
+                    lifecycle.failed(err, handoffStarted);
+                if (isTerminal(err))
+                    terminal = err;
+                else if (isApprovalOutcome(err))
+                    quietUntil = Date.now() + cooldownMs;
+                opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+            }
+            await cdp.send('Fetch.failRequest', { requestId: dead.requestId, errorReason: 'Aborted' }, dead.sessionId).catch(() => { });
         }
         finally {
             if (activeRequest?.attempt === attempt)
@@ -1216,10 +1632,18 @@ export async function attachToPlaywright(page, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    // How long an approval waits for the page to ask again; see MERCHANT_RETRY_WAIT_MS.
+    const retryWait = retryWaitMs(opts.merchantRetryWaitMs);
     let activeRequest = null;
     page.on?.('requestfailed', (request) => {
-        if (activeRequest && activeRequest.request === request)
-            activeRequest.attempt.stop();
+        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
+            // so no later event on it can pass for the retry's.
+            activeRequest.request = null;
+            activeRequest.frames = [];
+            opts.onEvent?.({ type: 'merchant_request_lost', detail: { authorizationId: lifecycle.getState().authorizationId } });
+        }
     });
     page.on?.('close', () => { if (!attachmentReady)
         setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); stripeCheckout.invalidate(); mercadoCheckout.invalidate(); activeRequest?.attempt.stop(); });
@@ -1235,6 +1659,18 @@ export async function attachToPlaywright(page, opts) {
             }
             if (preparationGate.isEngaged())
                 activeRequest?.attempt.stop();
+            // The page that abandoned its request has moved to another document:
+            // its approval cannot be answered there and is cancelled. A reload of
+            // the same document is not that; its re-issued request is the retry.
+            let url;
+            try {
+                url = typeof frame.url === 'function' ? frame.url() : undefined;
+            }
+            catch {
+                url = undefined;
+            }
+            if (activeRequest?.attempt.lost && documentKey(url) !== activeRequest.identity.documentUrl)
+                activeRequest.attempt.stop();
         }
     });
     page.on?.('framedetached', (frame) => {
@@ -1347,12 +1783,33 @@ export async function attachToPlaywright(page, opts) {
             }
             let preparation;
             try {
-                preparation = stripeStep ? undefined : preparationGate.claim(request.url(), request.postData() ?? '');
+                preparation = stripeStep ? undefined : preparationGate.claim(request.url(), request.postData() ?? '', request.headers());
             }
             catch (error) {
                 opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
                 return route.abort('aborted');
             }
+            // The page asking again for the purchase an outstanding approval is
+            // for, after its own request timed out: bind it to that approval (see
+            // merchantAttempt and the same check in attachToCdp).
+            if (awaitingApproval && activeRequest?.attempt.lost && !terminal && !setupStop.signal.aborted && !lifecycle.isCancelled()) {
+                const retry = requestIdentity(opts, request.url(), request.method(), request.postData() ?? '', documentKey(await documentUrlOf(readDocumentUrl, lifecycle.abort.signal)), await pageAmountOf(opts));
+                if (activeRequest?.attempt.lost && sameCheckoutRequest(activeRequest.identity, retry)) {
+                    if (preparation)
+                        preparationGate.retireUnboundClaim();
+                    const retryFrames = [];
+                    try {
+                        for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                            retryFrames.push(frame);
+                    }
+                    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 } });
+                    activeRequest.attempt.bind({ route, request, frames: retryFrames });
+                    return;
+                }
+            }
             // Fail closed and stay quiet: no card may reach the PSP, but neither may
             // the page's retry loop turn into a stream of doomed API calls. Every
             // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
@@ -1367,19 +1824,34 @@ export async function attachToPlaywright(page, opts) {
             }
             // Reserved before anything that could yield, matching attachToCdp.
             awaitingApproval = true;
-            const attempt = merchantAttempt(lifecycle);
+            let navigation = false;
+            try {
+                navigation = typeof request.resourceType === 'function' && request.resourceType() === 'document';
+            }
+            catch {
+                navigation = false;
+            }
+            const attempt = merchantAttempt(lifecycle, survivesAbandonment(opts, request.url(), request.method(), navigation, !!preparation || !!stripeStep || mercadoCheckout.requiresDocument(request.url(), request.method())));
             const frames = [];
             try {
                 for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
                     frames.push(frame);
             }
             catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+            // Judged on the request that currently carries the attempt: after a
+            // retry binds, the first request's failure is history, not a loss.
             const assertRequestLive = () => {
-                if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                const current = attempt.target;
+                if (current && (current.request.failure?.() || current.frames.some((frame) => frame.isDetached?.())))
+                    attempt.lose();
+                if (page.isClosed?.())
                     attempt.stop();
                 attempt.assertLive();
             };
             let handoffStarted = false;
+            // The approval the device gave, and whether it reached a browser request.
+            let approvedId = null;
+            let deliveryBegun = false;
             try {
                 const body = request.postData() ?? '';
                 if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
@@ -1388,12 +1860,20 @@ export async function attachToPlaywright(page, opts) {
                 }
                 opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
                 lifecycle.begin();
-                activeRequest = { request, frames, attempt };
+                const approvalStartedAt = Date.now();
+                attempt.bind({ route, request, frames });
+                activeRequest = { request, frames, attempt,
+                    identity: requestIdentity(opts, request.url(), request.method(), body, undefined, undefined) };
                 if (preparation)
                     await preparationGate.assertDocument();
-                const pageOrigin = await pageOriginOf(readDocumentUrl, attempt.signal);
+                // One bounded read serves the merchant origin and the retry identity; see attachToCdp.
+                const documentUrl = await documentUrlOf(readDocumentUrl, attempt.signal);
+                const pageOrigin = pageOriginFrom(documentUrl);
                 const pageAmount = await pageAmountOf(opts);
                 assertRequestLive();
+                activeRequest.identity.documentUrl = documentKey(documentUrl);
+                activeRequest.identity.pageAmount = pageAmount;
+                activeRequest.identity.amountEvidence ||= pageAmount !== undefined;
                 if (stripeStep)
                     stripeCheckout.assertClaim(stripeStep);
                 const merchantOrigin = preparation?.merchantOrigin ?? (opts.executionMode === 'user_approval'
@@ -1425,6 +1905,7 @@ export async function attachToPlaywright(page, opts) {
                             ? { mercado_checkout: mercadoCheckout.claimToken(request.url(), request.method(), await readDocumentUrl()) } : {}) },
                 });
                 assertRequestLive();
+                approvedId = replay.authorizationId;
                 if (lifecycle.isCancelled())
                     throw new Error('checkout cancelled locally after approval');
                 try {
@@ -1434,25 +1915,35 @@ export async function attachToPlaywright(page, opts) {
                     throw new PaymentOutcomeUnknownError(replay.authorizationId, 'mercado_checkout_metadata_invalid');
                 }
                 assertRequestLive();
-                lifecycle.prepareHandoff(replay, request.url());
+                // The request to answer: the paused one, or the page's retry when the
+                // page gave up on the first (see attachToCdp for the same step).
+                const delivery = await attempt.awaitTarget(boundedRetryWait(retryWait, approvalStartedAt, opts.timeoutMs), [lifecycle.abort.signal, setupStop.signal], () => {
+                    lifecycle.awaitingMerchantRetry(replay.authorizationId);
+                    opts.onEvent?.({ type: 'approval_awaiting_merchant_retry', detail: { authorizationId: replay.authorizationId } });
+                });
+                const { route: deliverTo, request: deliverRequest } = delivery.target;
+                const deliverBody = delivery.rebound ? deliverRequest.postData() ?? '' : body;
+                deliveryBegun = true;
+                attempt.beginDelivery();
+                lifecycle.prepareHandoff(replay, deliverRequest.url());
                 handoffStarted = replay.mode !== 'cse';
                 if (replay.mode === 'hosted_form') {
                     // Same as the CDP path: the paused navigation resolves to the
                     // synthetic page, and a re-post of this form is refused.
                     const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
                     // Inert on a navigation (never CORS-checked); one path for every fulfill.
-                    await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                    await deliverTo.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(deliverRequest.url(), deliverRequest.headers())), body: synthetic.body });
                     assertRequestLive();
-                    lastSubmitted = { url: request.url(), body, at: Date.now() };
+                    lastSubmitted = { url: deliverRequest.url(), body: deliverBody, at: Date.now() };
                     opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
                 }
                 else if (replay.mode === 'cse') {
                     // Same as the CDP path: the request continues from this browser
                     // with the ciphertext swapped in and no header override; Playwright
                     // recomputes the length itself.
-                    const postData = cseBody(body, replay);
+                    const postData = cseBody(deliverBody, replay);
                     handoffStarted = true;
-                    await route.continue({ postData });
+                    await deliverTo.continue({ postData });
                     assertRequestLive();
                     opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
                 }
@@ -1460,23 +1951,39 @@ export async function attachToPlaywright(page, opts) {
                     // Playwright adds these itself when a cross-origin fulfill carries
                     // none; written here anyway (replacing a stale value) so a
                     // cross-origin answer is the same whichever adapter ran.
-                    const cors = corsDecision(request.url(), request.headers());
-                    await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                    const cors = corsDecision(deliverRequest.url(), deliverRequest.headers());
+                    await deliverTo.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
                     assertRequestLive();
                     opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
                 }
                 lifecycle.handedOff(replay);
             }
             catch (err) {
+                const dead = attempt.target?.route ?? route;
                 if (activeRequest?.attempt === attempt)
                     activeRequest = null;
-                lifecycle.failed(err, handoffStarted);
-                if (isTerminal(err))
-                    terminal = err;
-                else if (isApprovalOutcome(err))
+                try {
+                    attempt.assertLive();
+                }
+                catch (stopped) {
+                    err = stopped;
+                }
+                if (err instanceof MerchantNeverRetried || (attempt.signal.aborted && approvedId && !deliveryBegun)) {
+                    // The device approved and no request ever carried the answer; see
+                    // the same branch in attachToCdp.
+                    await retireUnusedApproval(opts, lifecycle, approvedId);
                     quietUntil = Date.now() + cooldownMs;
-                opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-                await route.abort('aborted').catch(() => { });
+                }
+                else {
+                    if (!attempt.signal.aborted)
+                        lifecycle.failed(err, handoffStarted);
+                    if (isTerminal(err))
+                        terminal = err;
+                    else if (isApprovalOutcome(err))
+                        quietUntil = Date.now() + cooldownMs;
+                    opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+                }
+                await dead.abort('aborted').catch(() => { });
             }
             finally {
                 if (activeRequest?.attempt === attempt)