@agent-cards/checkout 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.3.1
+
+- Detect a merchant request abort or owning frame/page closure while approval is pending. The attachment holds an unknown outcome and blocks automatic retries; an expired request is never reported as an authorized handoff.
+- Retire pending authorizations through the org-scoped cancellation endpoint when the merchant request disappears. Cancellation can win only before the processor-send boundary; started or completed replay remains unknown to this operation. A late creation response is drained so its authorization ID can be cancelled without exposing another approval link.
+- Square token mode uses the vault's verified browser TLS relay. The relay keeps TLS termination and card plaintext on the cardholder device and Square. SDK 0.2.1 can complete a prompt approval but does not contain the native-timeout lifecycle fixes; upgrade to 0.3.1 for Square checkout.
+- Square's native tokenization request still expires after about 10 seconds, including approval and token handoff. Delayed approval cannot complete that checkout; a later SCA challenge has its own lifetime after handoff. This release does not extend the deadline or retry a payment after timeout. Reconcile the merchant outcome and explicitly begin another checkout when required.
+
 ## 0.3.0
 
 ### Browser checkout lifecycle

package/README.md

@@ -30,7 +30,7 @@ your agent ──drives──> merchant checkout
 npm i @agent-cards/checkout
 ```
 
-Upgrading from 0.2.x? Read the [0.3.0 migration notes](./CHANGELOG.md), especially
+Upgrading from 0.2.x? Read the [migration notes](./CHANGELOG.md), especially
 the unknown-outcome, cancellation and browser-context requirements.
 
 ## Use it
@@ -79,8 +79,11 @@ Stripe's minor units, so the approval screen, the notifications and every
 read show one amount. Tokenization requests carry no amount, so there the
 pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
 
-Then let your agent click "Pay" like it always does. `attachToCdp` holds the
-request open until the cardholder approves, so the checkout simply continues.
+Then let your agent click "Pay" like it always does. `attachToCdp` pauses the
+request for approval and resumes it only while the merchant request remains
+live. Merchant timeouts still apply: Square's observed tokenization deadline
+is about 10 seconds for approval and token handoff, so delayed approval cannot
+complete that checkout.
 
 Playwright:
 
@@ -389,6 +392,8 @@ do not reuse that token in a new attachment as a workaround. Configuration and
 unsupported-mode failures require fixing the integration. Bank flows requiring
 another confirmation and other stored-token chains remain unverified.
 
+Square saved-card checkout requires SDK 0.3.1 for merchant-request lifetime handling. Its observed native tokenization request expires after about 10 seconds, including approval-page loading, unlocking, approval, relay and token handoff. An approval that exceeds this window cannot finish that checkout. A subsequent SCA challenge has its own lifetime after the token handoff. This SDK does not pause Square's timers or automatically retry an expired checkout. If the merchant request aborts or its frame closes, the attachment blocks further card requests and tries to retire a pre-replay approval. A started replay or unconfirmed cancellation remains unknown. General delayed human approval is not supported by this Square flow.
+
 Lost authorization polling, local approval timeouts, or interrupted browser
 handoffs produce `outcome_unknown` and block automatic retry. The thrown
 `PaymentOutcomeUnknownError` carries `authorizationId` when creation was

package/dist/cdp.js

@@ -284,6 +284,22 @@ 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) {
+    const controller = new AbortController();
+    const error = () => new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'merchant_request_aborted');
+    return {
+        signal: controller.signal,
+        stop() {
+            if (controller.signal.aborted)
+                return;
+            lifecycle.merchantRequestAborted();
+            controller.abort(error());
+        },
+        assertLive() { if (controller.signal.aborted)
+            throw error(); },
+    };
+}
 /**
  * Take over card tokenization for a page.
  *
@@ -313,6 +329,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
@@ -323,6 +340,10 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
+        // Fetch's interception ID differs from Network's ID. Enable failure events
+        // before intercepting and bind each attempt to both its ID and CDP session.
+        await cdp.send('Network.enable', {}, sessionId);
+        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
         await cdp.send('Fetch.enable', {
             patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
         }, sessionId);
@@ -333,6 +354,18 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         armed.add(key);
     };
     cdp.on(async (method, params, sessionId) => {
+        if (method === 'Network.loadingFailed') {
+            if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sessionId === sessionId)
+                activeRequest.attempt.stop();
+            return;
+        }
+        if (method === 'Target.detachedFromTarget' || method === 'Inspector.detached' || method === 'Page.frameDetached') {
+            if (activeRequest && (method === 'Target.detachedFromTarget' ? activeRequest.sessionId === params.sessionId
+                : method === 'Inspector.detached' ? activeRequest.sessionId === sessionId
+                    : activeRequest.sessionId === sessionId && activeRequest.frameId === params.frameId))
+                activeRequest.attempt.stop();
+            return;
+        }
         if (method === 'Target.attachedToTarget') {
             const child = params.sessionId;
             try {
@@ -351,7 +384,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if (method !== 'Fetch.requestPaused')
             return;
-        const { requestId, request, resourceType } = params;
+        const { requestId, request, resourceType, networkId, frameId } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
                 lifecycle.unsupported();
@@ -374,6 +407,7 @@ 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);
         let handoffStarted = false;
         try {
             const body = pausedBody(request);
@@ -395,6 +429,11 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
             lifecycle.begin();
+            if (typeof networkId !== 'string' || !networkId) {
+                attempt.stop();
+                attempt.assertLive();
+            }
+            activeRequest = { attempt, networkId, sessionId, frameId };
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
@@ -404,10 +443,15 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 cardId: opts.cardId,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
+                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
+            attempt.assertLive();
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
             lifecycle.prepareHandoff(replay, request.url);
@@ -427,6 +471,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
                     body: Buffer.from(page.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 lastSubmitted = { url: request.url, body, at: Date.now() };
                 // Named for what it is: a device-attested submission with no
                 // processor evidence, never an `authorized` event.
@@ -444,6 +489,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     requestId,
                     postData,
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -460,11 +506,15 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                     responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
                 }, sessionId);
+                attempt.assertLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
             lifecycle.handedOff(replay);
         }
         catch (err) {
+            // Ignore the failure event caused by our own safe decline/error abort.
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
@@ -474,6 +524,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
         }
@@ -520,6 +572,17 @@ export async function attachToPlaywright(page, opts) {
     let quietUntil = 0;
     // One outstanding approval at a time; see the note above isApprovalOutcome.
     let awaitingApproval = false;
+    let activeRequest = null;
+    page.on?.('requestfailed', (request) => {
+        if (activeRequest && activeRequest.request === request)
+            activeRequest.attempt.stop();
+    });
+    page.on?.('close', () => activeRequest?.attempt.stop());
+    page.on?.('crash', () => activeRequest?.attempt.stop());
+    page.on?.('framedetached', (frame) => {
+        if (activeRequest?.frames.includes(frame))
+            activeRequest.attempt.stop();
+    });
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
@@ -547,6 +610,18 @@ export async function attachToPlaywright(page, opts) {
         }
         // Reserved before anything that could yield, matching attachToCdp.
         awaitingApproval = true;
+        const attempt = merchantAttempt(lifecycle);
+        const frames = [];
+        try {
+            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                frames.push(frame);
+        }
+        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+        const assertRequestLive = () => {
+            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                attempt.stop();
+            attempt.assertLive();
+        };
         let handoffStarted = false;
         try {
             const body = request.postData() ?? '';
@@ -556,6 +631,8 @@ export async function attachToPlaywright(page, opts) {
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
             lifecycle.begin();
+            activeRequest = { request, frames, attempt };
+            assertRequestLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
@@ -565,10 +642,15 @@ export async function attachToPlaywright(page, opts) {
                 cardId: opts.cardId,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
+                merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
+                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                    lifecycle.approvalUrl(url);
+                    return opts.onApprovalUrl?.(url);
+                } },
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
+            assertRequestLive();
             if (lifecycle.isCancelled())
                 throw new Error('checkout cancelled locally after approval');
             lifecycle.prepareHandoff(replay, request.url());
@@ -579,6 +661,7 @@ export async function attachToPlaywright(page, opts) {
                 const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
                 // Inert on a navigation (never CORS-checked); one path for every fulfill.
                 await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                assertRequestLive();
                 lastSubmitted = { url: request.url(), body, at: Date.now() };
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
             }
@@ -589,6 +672,7 @@ export async function attachToPlaywright(page, opts) {
                 const postData = cseBody(body, replay);
                 handoffStarted = true;
                 await route.continue({ postData });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
@@ -597,20 +681,25 @@ export async function attachToPlaywright(page, opts) {
                 // cross-origin answer is the same whichever adapter ran.
                 const cors = corsDecision(request.url(), request.headers());
                 await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                assertRequestLive();
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
             lifecycle.handedOff(replay);
         }
         catch (err) {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
             opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await route.abort('aborted');
+            await route.abort('aborted').catch(() => { });
         }
         finally {
+            if (activeRequest?.attempt === attempt)
+                activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
         }

package/dist/client.d.ts

@@ -135,6 +135,8 @@ export interface AuthorizeInput {
     timeoutMs?: number;
     /** Stops local polling; it does not revoke a pending approval or undo a payment. */
     signal?: AbortSignal;
+    /** Adapter-owned merchant request lifetime. A failed request retires a pending approval before replay when possible. */
+    merchantSignal?: AbortSignal;
     /** Called before onApprovalUrl; lets a runtime reconcile an interrupted authorization. */
     onAuthorizationCreated?: (authorizationId: string) => void;
     /** Called once with the URL to surface to the user, if you deliver it yourself. */
@@ -336,6 +338,14 @@ export declare class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
+    cancelAuthorization(authorizationId: string): Promise<{
+        id: string;
+        status: 'declined';
+        reason: 'merchant_request_aborted';
+        cancelled: true;
+        processor_request_started: false;
+    }>;
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
      * (Stripe did not answer the read-back) is retried on a short backoff

package/dist/client.js

@@ -282,6 +282,8 @@ export class VaultClient {
     async authorize(input) {
         if (input.signal?.aborted)
             throw new CheckoutCancelledError();
+        if (input.merchantSignal?.aborted)
+            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
         const rec = findRecognizer(input.request.url, this.registry);
         if (!rec)
             throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
@@ -341,9 +343,11 @@ export class VaultClient {
             },
         };
         try {
-            created = await this.createAuthorization(payload, input.currency, operationSignal);
+            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
         }
         catch (error) {
+            if (error instanceof PaymentOutcomeUnknownError)
+                throw error;
             // A missing answer or generic 5xx can hide a committed row and a delivered approval link.
             // Only the documented pre-create read-back errors prove it is safe to retry.
             const safeReadFailure = error instanceof CheckoutApiError
@@ -357,125 +361,160 @@ export class VaultClient {
         if (!created || typeof created.id !== 'string' || !created.id)
             throw new PaymentOutcomeUnknownError(null, 'authorization_create_malformed');
         const authorizationId = created.id;
+        const stopSignal = input.merchantSignal
+            ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
         try {
-            Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
-        }
-        catch { /* observer only */ }
-        try {
-            Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
-        }
-        catch { /* approval delivery must not lose an existing authorization */ }
-        while (Date.now() < deadline) {
-            if (input.signal?.aborted)
-                throw new PaymentOutcomeUnknownError(authorizationId, 'local_cancel');
-            await interruptibleSleep(Math.min(this.pollIntervalMs, Math.max(0, deadline - Date.now())), input.signal);
-            if (input.signal?.aborted)
-                throw new PaymentOutcomeUnknownError(authorizationId, 'local_cancel');
-            let s;
-            const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
-            const pollSignal = input.signal ? AbortSignal.any([input.signal, deadlineSignal]) : deadlineSignal;
             try {
-                s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
+                Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
             }
-            catch {
-                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_poll_failed');
-            }
-            if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
-                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
+            catch { /* observer only */ }
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            try {
+                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
             }
-            const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
-                ? { amountAuthority: s.amount_authority }
-                : {};
-            if (s.status === 'submitted_on_device') {
-                // The device attested that the processor's form left it; the stamp
-                // is the whole fact and it is NOT an approval (see HostedFormReplay).
-                // Only a hosted_form row may carry this status; a stamp without its
-                // time is not one this SDK can act on. The device may already have paid,
-                // so the adapter holds the attempt until the merchant is reconciled.
-                const mode = typeof s.mode === 'string' ? s.mode : 'token';
-                if (mode !== 'hosted_form')
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'submission_mode_mismatch');
-                if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'submission_timestamp_missing');
+            catch { /* approval delivery must not lose an existing authorization */ }
+            while (Date.now() < deadline) {
+                if (stopSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
+                await interruptibleSleep(Math.min(this.pollIntervalMs, Math.max(0, deadline - Date.now())), stopSignal);
+                if (stopSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
+                let s;
+                const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+                const pollSignal = stopSignal ? AbortSignal.any([stopSignal, deadlineSignal]) : deadlineSignal;
+                try {
+                    s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
                 }
-                return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
-            }
-            if (s.status === 'approved') {
-                const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
-                if (approvedMode === 'hosted_form') {
-                    // Never: the API finishes a hosted form as submitted_on_device, and
-                    // its database refuses `approved` on that mode. An answer that says
-                    // otherwise is not one to act on as a payment.
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
+                catch {
+                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'authorization_poll_failed');
                 }
-                if (approvedMode === 'cse') {
-                    const sub = s.substitutions;
-                    const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
-                        && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
-                        && Object.values(sub.fields).every((v) => typeof v === 'string' && v.length > 0);
-                    if (!fieldsOk)
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
-                    // `remove`: sibling keys the API says to drop with the swap (Adyen's
-                    // `brand`, stamped by adyen-web from the agent's dummy digits). Absent
-                    // on an older API; anything but a list of names is refused, since a
-                    // half-understood instruction would continue a body Adyen refuses.
-                    const removeRaw = sub.remove;
-                    if (removeRaw !== undefined && !(Array.isArray(removeRaw) && removeRaw.every((k) => typeof k === 'string' && k.length > 0))) {
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'cse_remove_malformed');
+                if (input.merchantSignal?.aborted)
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+                if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
+                }
+                const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
+                    ? { amountAuthority: s.amount_authority }
+                    : {};
+                if (s.status === 'submitted_on_device') {
+                    // The device attested that the processor's form left it; the stamp
+                    // is the whole fact and it is NOT an approval (see HostedFormReplay).
+                    // Only a hosted_form row may carry this status; a stamp without its
+                    // time is not one this SDK can act on. The device may already have paid,
+                    // so the adapter holds the attempt until the merchant is reconciled.
+                    const mode = typeof s.mode === 'string' ? s.mode : 'token';
+                    if (mode !== 'hosted_form')
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'submission_mode_mismatch');
+                    if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'submission_timestamp_missing');
+                    }
+                    return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
+                }
+                if (s.status === 'approved') {
+                    const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
+                    if (approvedMode === 'hosted_form') {
+                        // Never: the API finishes a hosted form as submitted_on_device, and
+                        // its database refuses `approved` on that mode. An answer that says
+                        // otherwise is not one to act on as a payment.
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
+                    }
+                    if (approvedMode === 'cse') {
+                        const sub = s.substitutions;
+                        const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
+                            && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
+                            && Object.values(sub.fields).every((v) => typeof v === 'string' && v.length > 0);
+                        if (!fieldsOk)
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
+                        // `remove`: sibling keys the API says to drop with the swap (Adyen's
+                        // `brand`, stamped by adyen-web from the agent's dummy digits). Absent
+                        // on an older API; anything but a list of names is refused, since a
+                        // half-understood instruction would continue a body Adyen refuses.
+                        const removeRaw = sub.remove;
+                        if (removeRaw !== undefined && !(Array.isArray(removeRaw) && removeRaw.every((k) => typeof k === 'string' && k.length > 0))) {
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_remove_malformed');
+                        }
+                        return {
+                            mode: 'cse',
+                            authorizationId,
+                            substitutions: {
+                                encoding: 'json',
+                                at: sub.at,
+                                fields: { ...sub.fields },
+                                ...(removeRaw ? { remove: [...removeRaw] } : {}),
+                            },
+                            ...amountAuthority,
+                        };
+                    }
+                    if (approvedMode !== 'token')
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'approved_mode_unsupported');
+                    const response = s.response;
+                    if (!response || !Number.isInteger(response.status) || response.status < 100 || response.status > 599
+                        || typeof response.body !== 'string' || !response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'approved_response_malformed');
                     }
                     return {
-                        mode: 'cse',
+                        mode: 'token',
                         authorizationId,
-                        substitutions: {
-                            encoding: 'json',
-                            at: sub.at,
-                            fields: { ...sub.fields },
-                            ...(removeRaw ? { remove: [...removeRaw] } : {}),
-                        },
+                        ...response,
+                        amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
+                        chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
+                        chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
+                        chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
                         ...amountAuthority,
                     };
                 }
-                if (approvedMode !== 'token')
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'approved_mode_unsupported');
-                const response = s.response;
-                if (!response || !Number.isInteger(response.status) || response.status < 100 || response.status > 599
-                    || typeof response.body !== 'string' || !response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'approved_response_malformed');
-                }
-                return {
-                    mode: 'token',
-                    authorizationId,
-                    ...response,
-                    amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                    chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
-                    chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
-                    chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
-                    ...amountAuthority,
-                };
-            }
-            if (s.status === 'declined') {
-                // The pre-replay checks declined it: typed, with the numbers, so the
-                // caller can say what happened rather than "the user said no".
-                if (s.reason === 'amount_mismatch') {
-                    throw new AmountMismatchError(String(created.id), Number(s.expected_cents), Number(s.actual_cents), String(s.currency ?? input.currency ?? ''), s.actual_currency != null ? String(s.actual_currency) : undefined, 'pre_replay');
+                if (s.status === 'declined') {
+                    // The pre-replay checks declined it: typed, with the numbers, so the
+                    // caller can say what happened rather than "the user said no".
+                    if (s.reason === 'amount_mismatch') {
+                        throw new AmountMismatchError(String(created.id), Number(s.expected_cents), Number(s.actual_cents), String(s.currency ?? input.currency ?? ''), s.actual_currency != null ? String(s.actual_currency) : undefined, 'pre_replay');
+                    }
+                    if (s.reason === 'intent_not_confirmable')
+                        throw new IntentNotConfirmableError(String(created.id));
+                    if (s.reason === 'processor_refused') {
+                        throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                    }
+                    throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }
-                if (s.reason === 'intent_not_confirmable')
-                    throw new IntentNotConfirmableError(String(created.id));
-                if (s.reason === 'processor_refused') {
-                    throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                if (s.status === 'expired') {
+                    if (s.replay_attempted === false)
+                        throw new ApprovalTimeoutError(timeoutMs);
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
                 }
-                throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
+                if (s.status !== 'awaiting_approval')
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
             }
-            if (s.status === 'expired') {
-                if (s.replay_attempted === false)
-                    throw new ApprovalTimeoutError(timeoutMs);
-                throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
+            // A local deadline is not server-side expiry; the person may still use the approval link.
+            throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
+        }
+        catch (error) {
+            if (input.merchantSignal?.aborted)
+                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
+            throw error;
+        }
+        finally {
+            if (input.merchantSignal?.aborted) {
+                // Drain a create acknowledgement even after the merchant aborts so its
+                // known ID can be retired. An unacknowledged create remains unknown.
+                // A started/finalized replay or failed cleanup never becomes a claimed
+                // cancellation, and this best-effort cleanup never retries a payment.
+                await this.cancelAuthorization(authorizationId).catch(() => { });
             }
-            if (s.status !== 'awaiting_approval')
-                throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
         }
-        // A local deadline is not server-side expiry; the person may still use the approval link.
-        throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
+    }
+    /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
+    async cancelAuthorization(authorizationId) {
+        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
+            throw new Error('Invalid authorization ID.');
+        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/cancel`, {}, AbortSignal.timeout(5_000));
+        if (result?.id !== authorizationId || result.status !== 'declined'
+            || result.reason !== 'merchant_request_aborted' || result.cancelled !== true
+            || result.processor_request_started !== false) {
+            throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_cancel_unconfirmed');
+        }
+        return { id: authorizationId, status: 'declined', reason: 'merchant_request_aborted',
+            cancelled: true, processor_request_started: false };
     }
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
@@ -484,10 +523,12 @@ export class VaultClient {
      * `amount_mismatch` becomes an AmountMismatchError at stage 'create' so the
      * adapters treat it as an answered request, not a dead page.
      */
-    async createAuthorization(payload, currency, signal) {
+    async createAuthorization(payload, currency, signal, stopRetries) {
         for (let attempt = 0;; attempt++) {
+            if (stopRetries?.aborted)
+                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
             try {
-                return await this.post('/v2/checkout/authorizations', payload, signal);
+                return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
@@ -500,7 +541,7 @@ export class VaultClient {
                     && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
                 if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
                     throw err;
-                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], signal);
+                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], stopRetries ? AbortSignal.any([stopRetries, ...(signal ? [signal] : [])]) : signal);
                 if (signal?.aborted)
                     throw signal.reason;
             }
@@ -545,9 +586,14 @@ export class VaultClient {
         return this.inflight;
     }
     /** Authenticated request that retries ONCE on a 401 with a fresh token. */
-    async call(path, init = {}, retried = false) {
+    async call(path, init = {}, retried = false, stopNewRequests) {
         const signal = init.signal ?? AbortSignal.timeout(30_000);
         const token = await withSignal(this.accessToken(), signal);
+        // Auth can outlive the merchant request. Stop a create that has not left
+        // yet, while preserving the response of one already sent for cleanup.
+        if (stopNewRequests?.aborted)
+            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
+        signal.throwIfAborted();
         const r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
             ...init,
             signal,
@@ -555,15 +601,17 @@ export class VaultClient {
         }), signal);
         // A token can be revoked or expire early; one forced refresh, then give up.
         if (r.status === 401 && !retried) {
+            if (stopNewRequests?.aborted)
+                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
             await withSignal(this.accessToken(true), signal);
-            return this.call(path, { ...init, signal }, true);
+            return this.call(path, { ...init, signal }, true, stopNewRequests);
         }
         if (!r.ok)
             throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
         return withSignal(r.json(), signal);
     }
-    post(path, body, signal) {
-        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal });
+    post(path, body, signal, stopNewRequests) {
+        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
     }
     get(path, signal) {
         return this.call(path, { signal });

package/dist/lifecycle.d.ts

@@ -54,6 +54,7 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private held;
     private active;
     private cancelled;
+    private merchantAborted;
     private unboundStripeToken;
     private reconciliation;
     readonly abort: AbortController;
@@ -68,6 +69,8 @@ export declare class CheckoutLifecycle implements CheckoutController {
     approvalUrl(approvalUrl: string): void;
     private notify;
     cancel(): void;
+    /** The exact browser request is gone; a late approval cannot reopen it. */
+    merchantRequestAborted(): void;
     unsupported(): void;
     prepareHandoff(replay: ReplayResponse, requestUrl: string): void;
     handedOff(replay: ReplayResponse): void;

package/dist/lifecycle.js

@@ -6,6 +6,7 @@ export class CheckoutLifecycle {
     held = false;
     active = false;
     cancelled = false;
+    merchantAborted = false;
     unboundStripeToken = false;
     reconciliation = null;
     abort = new AbortController();
@@ -46,6 +47,12 @@ export class CheckoutLifecycle {
         this.abort.abort();
         this.set({ ...this.state, status: this.active || this.state.authorizationId ? 'outcome_unknown' : 'cancelled', reason: 'local_cancel' });
     }
+    /** The exact browser request is gone; a late approval cannot reopen it. */
+    merchantRequestAborted() {
+        this.merchantAborted = true;
+        this.held = true;
+        this.set({ ...this.state, status: 'outcome_unknown', reason: 'merchant_request_aborted' });
+    }
     unsupported() {
         this.held = true;
         if (this.state.authorizationId)
@@ -71,6 +78,8 @@ export class CheckoutLifecycle {
         }
     }
     handedOff(replay) {
+        if (this.merchantAborted)
+            return;
         const mismatch = (!replay.mode || replay.mode === 'token') && replay.amountVerified === false;
         this.held = !!this.options.requireMerchantResult || replay.mode === 'hosted_form' || mismatch || this.unboundStripeToken;
         this.set({ status: 'awaiting_merchant', authorizationId: replay.authorizationId, mode: replay.mode ?? 'token',
@@ -79,6 +88,10 @@ export class CheckoutLifecycle {
     failed(error, handoffStarted = false) {
         if (this.cancelled)
             return;
+        if (this.merchantAborted) {
+            this.merchantRequestAborted();
+            return;
+        }
         const authorizationId = error instanceof PaymentOutcomeUnknownError ? error.authorizationId : this.state.authorizationId;
         if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
             this.held = true;
@@ -160,6 +173,7 @@ export class CheckoutLifecycle {
         if (this.unboundStripeToken)
             throw new Error('This attachment delivered an unbound Stripe token; reconcile the merchant order and use a separately validated checkout flow.');
         this.held = false;
+        this.merchantAborted = false;
         this.set({ status: 'idle', authorizationId: null });
     }
 }

package/package.json

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