@agent-cards/checkout 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.1
+
+- Stop describing every processor request rejection as a card decline or proof that nothing was charged. `ProcessorRefusedError` keeps its existing class and code, with neutral wording and an optional `processorError` containing bounded Razorpay reason, source, step and payment/order identifiers from the matching API/Vault release. Older failure records cannot recover details that were not retained.
+- Hold further card requests within the attachment after a processor refusal, including when the merchant retries after the approval cooldown. Reconcile the merchant payment; only an explicit `retryAfterMerchantFailure({ status: 'failed' })` releases this hold and permits an immediate new attempt. This also applies to clear card declines. Ordinary user declines keep their approval cooldown. Do not automatically replace the attachment to bypass reconciliation.
+- Add deterministic refusal, diagnostic sanitization and retry-guard regressions. These tests do not establish a successful Razorpay purchase or processor capture.
+
+## 0.4.0
+
+- Add `controller.prepare({ psp: 'square', environment: 'production' | 'sandbox' })` to both browser adapters. The caller awaits cardholder consent and unlock before starting its first native Pay action. This requires the matching preparation API and Vault deployment.
+- Bind one fresh request to the selected card, declared merchant, merchant origin, amount, currency and Square environment. Readiness expires after at most 30 seconds; preparation failure, expiry, cancellation, navigation and reuse fail closed. Binding creates no second approval link or SMS. Square token amounts remain display-only.
+- Preserve native request deadlines and merchant-abort protections. The SDK never clicks Pay, changes Square timers or retries an abandoned prepared checkout. The post-submit relay and token handoff must still fit Square's native deadline; a disconnected or slow cardholder device can miss it.
+- Recover a lost bind acknowledgement through preparation metadata for cancellation and reconciliation only. Started replay or unconfirmed cleanup remains unknown. A parent CDP page disconnect now also stops a pending request in a child iframe.
+- Add preparation lifecycle tests and an isolated Chromium fixture that waits more than ten seconds before any card request, then permits one fresh request. These fixtures use no real processor and do not establish native Square or production checkout acceptance.
+
 ## 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.

package/README.md

@@ -82,8 +82,8 @@ pair is shown and reported (`amountAuthority: 'display_only'`), not enforced.
 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.
+is about 10 seconds for approval and token handoff. For human approval, use
+`controller.prepare()` before the first Pay action as shown below.
 
 Playwright:
 
@@ -248,11 +248,19 @@ one. `amountAuthority` on every replay is `stripe_payment_intent`,
   refused to replay a confirm at it. An `ApprovalDeclinedError` with
   `code: 'intent_not_confirmable'`. Deliberately not "nothing was charged":
   check the intent at Stripe before retrying.
-- `ProcessorRefusedError`: the cardholder's device sent the card and the
-  processor refused it outright (`pspErrorCode` is the processor's own code,
-  such as Stripe's `card_declined`). Nothing was charged. An
-  `ApprovalDeclinedError` with `code: 'processor_refused'`; the page's next
-  attempt raises a fresh approval where the person can pick another card.
+- `ProcessorRefusedError`: the cardholder's device reported a processor
+  request rejection. `pspErrorCode` carries the processor's code; optional
+  `processorError` carries bounded Razorpay reason, source, step and payment/order
+  identifiers when the API has them. A generic code such as `BAD_REQUEST_ERROR`
+  does not establish an issuer decline or prove no money moved. Reconcile the
+  merchant payment before retrying. This remains an `ApprovalDeclinedError`
+  with `code: 'processor_refused'` for compatibility.
+  The attachment records `status: 'declined', reason: 'processor_refused'`
+  and holds further card requests. After confirming merchant failure, call
+  `retryAfterMerchantFailure({ status: 'failed' })` to permit a deliberate new
+  attempt immediately, without waiting for the user-decline cooldown. Do not
+  automatically create a new attachment after this error;
+  the guard applies only within the existing attachment.
 - `CheckoutApiError` with `code === 'amount_unverifiable'`: Stripe could not
   be asked (502; the SDK retries twice, 500ms then 1500ms, before throwing)
   or the paused request lacked its client secret or publishable key (400).
@@ -392,7 +400,28 @@ 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.
+Square's observed native tokenization request expires after about 10 seconds. SDK 0.4.0 adds approval before submission, requiring the matching preparation API and Vault deployment. Start human approval before the caller's first Pay action:
+
+```ts
+const checkout = await attachToPlaywright(page, {
+  vault, user: 'your-user-id', merchant: 'Example merchant',
+  amountCents: 100, currency: 'USD',
+  onApprovalUrl: deliverPrivatelyToCardholder,
+});
+const preparation = await checkout.prepare({
+  psp: 'square',
+  environment: 'production', // explicit; use 'sandbox' for Square Sandbox
+});
+// The cardholder has consented and unlocked the same approval document.
+// No processor request or payment has started.
+await page.getByRole('button', { name: 'Pay', exact: true }).click();
+```
+
+`prepare()` is available on both Playwright and raw CDP controllers. It requires `amountCents` and `currency`, must precede the first recognized card request, and returns only when the cardholder's device is ready. It delivers the preparation URL through `onApprovalUrl` and `onUserAction`; binding the subsequent authorization sends no second approval link or SMS. The phone page must stay open. Its selected card, merchant origin, declared merchant, amount, currency and Square environment bind one fresh request. The amount remains `display_only`; a Square token does not enforce the merchant's eventual charge amount.
+
+Readiness lasts up to 30 seconds (`preparation.expiresAt`) and appears as `ready_to_submit`, with `paymentStatus: 'not_started'`. Trigger the caller-owned Pay action immediately after the promise resolves. Expiry, navigation, cancellation, an early request or a changed checkout fails closed. A preparation and its attachment are single use; reconcile any bound authorization before creating a new attachment. The SDK never clicks Pay, reuses a stale request, pauses Square timers, or automatically retries a failed prepared checkout.
+
+After Pay, Square's native deadline still covers fresh authorization binding, device replay, relay and token handoff. A disconnected/backgrounded phone or slow transport can still miss it. A subsequent SCA challenge has its own lifetime after token handoff. If the merchant request aborts or its frame closes, the attachment blocks further requests and tries to retire the pre-replay authorization; a started replay or unconfirmed cancellation remains unknown. Without `prepare()`, approval loading and human interaction still share the native deadline, so delayed approval cannot finish that request.
 
 Lost authorization polling, local approval timeouts, or interrupted browser
 handoffs produce `outcome_unknown` and block automatic retry. The thrown
@@ -439,8 +468,11 @@ pnpm test:browser
 The browser fixtures never contact a payment service. The general suite uses
 `psp.invalid`; the Stripe continuation suite forces `api.stripe.com` through an
 allowlisted loopback proxy and a temporary self-signed TLS stub (requires the
-`openssl` CLI). All other proxy destinations are rejected. Both suites use an
-in-process Agentcard API fixture and loopback merchant pages. It proves nested-frame pause/resume, agent control during approval,
+`openssl` CLI). All other proxy destinations are rejected. These suites use an
+in-process Agentcard API fixture and loopback merchant pages. The preparation
+fixture denies all external traffic, waits more than ten seconds before any
+card request, and then checks one fresh request with an unchanged ten-second
+fixture abort timer. It exercises SDK ordering, not the native Square SDK. It proves nested-frame pause/resume, agent control during approval,
 post-payment tasks in the same page, decline/expiry/cancel, unknown-outcome retry
 blocking, explicit unsupported endpoint behavior, and blocking an immediate real-browser
 Stripe token-to-intent fetch chain, including unrelated first intents, changed

package/dist/cdp.js

@@ -1,5 +1,6 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
-import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, UnsupportedModeError, redactUrl, } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
+import { PreparationGate } from './preparation.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -79,6 +80,11 @@ const APPROVAL_COOLDOWN_MS = 5_000;
  * quiet window absorbs the burst; the next request past it is judged afresh.
  */
 function isApprovalOutcome(err) {
+    // Processor refusals are held by the lifecycle until explicit merchant
+    // reconciliation and retry. A second timer would outlive that release and
+    // reject the application's deliberate retry even after confirmed failure.
+    if (err instanceof ProcessorRefusedError)
+        return false;
     if (err instanceof CheckoutApiError)
         return err.code === 'duplicate_submission';
     return err instanceof ApprovalDeclinedError || err instanceof ApprovalTimeoutError;
@@ -97,7 +103,9 @@ function isApprovalOutcome(err) {
  * a misconfiguration or an unsupported PSP. Nothing a person does changes
  * those, so asking again is pure waste.
  *
- * Everything else stays retryable. A 5xx or a 429 clears on its own, and a
+ * Other errors may be retryable unless the lifecycle holds the attachment
+ * for merchant reconciliation, as it does after a processor refusal.
+ * A 5xx or a 429 clears on its own, and a
  * decline or a timeout is answered by the cooldown above rather than by
  * killing the page: the person said no to one authorization, not to every
  * checkout they will ever make in this session. A 409 duplicate_submission
@@ -320,6 +328,14 @@ function merchantAttempt(lifecycle) {
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
     const lifecycle = new CheckoutLifecycle(opts);
+    let preparationFrameId;
+    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+        const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
+        if (typeof tree?.frameTree?.frame?.url !== 'string')
+            throw new Error('merchant_document_unavailable');
+        preparationFrameId = tree.frameTree.frame.id;
+        return tree.frameTree.frame.url;
+    });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     // Set once a failure proves that retrying cannot help; see isTerminal.
@@ -354,6 +370,18 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         armed.add(key);
     };
     cdp.on(async (method, params, sessionId) => {
+        if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
+            preparationGate.invalidate('merchant_document_changed');
+            if (preparationGate.isEngaged())
+                activeRequest?.attempt.stop();
+            return;
+        }
+        if ((method === 'Inspector.detached' && sessionId === pageSessionId)
+            || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            preparationGate.invalidate('merchant_document_closed');
+            // The root page owns every attached OOPIF; its loss ends child requests too.
+            activeRequest?.attempt.stop();
+        }
         if (method === 'Network.loadingFailed') {
             if (activeRequest && activeRequest.networkId === params.requestId && activeRequest.sessionId === sessionId)
                 activeRequest.attempt.stop();
@@ -387,6 +415,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         const { requestId, request, resourceType, networkId, frameId } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
             if (guards.matches(request.url, request.method)) {
+                preparationGate.invalidate('unsupported_checkout');
                 lifecycle.unsupported();
                 opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url), method: request.method } });
                 await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
@@ -395,11 +424,22 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
+        let preparation;
+        try {
+            preparation = preparationGate.claim(request.url);
+        }
+        catch (error) {
+            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            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) {
             const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+            if (preparation)
+                preparationGate.retireUnboundClaim();
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
@@ -434,18 +474,22 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 attempt.assertLive();
             }
             activeRequest = { attempt, networkId, sessionId, frameId };
+            if (preparation)
+                await preparationGate.assertDocument();
+            attempt.assertLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                cardId: opts.cardId,
+                cardId: preparation?.cardId ?? opts.cardId,
+                preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
                 merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
                     lifecycle.approvalUrl(url);
                     return opts.onApprovalUrl?.(url);
                 } },
@@ -528,6 +572,8 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
+            if (preparation)
+                preparationGate.retireUnboundClaim();
         }
     });
     await arm(pageSessionId);
@@ -552,6 +598,11 @@ export async function attachToPlaywright(page, opts) {
         throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
     }
     const lifecycle = new CheckoutLifecycle(opts);
+    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+        if (page.isClosed?.() || typeof page.url !== 'function')
+            throw new Error('merchant_document_unavailable');
+        return page.url();
+    });
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
@@ -577,8 +628,15 @@ export async function attachToPlaywright(page, opts) {
         if (activeRequest && activeRequest.request === request)
             activeRequest.attempt.stop();
     });
-    page.on?.('close', () => activeRequest?.attempt.stop());
-    page.on?.('crash', () => activeRequest?.attempt.stop());
+    page.on?.('close', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('crash', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('framenavigated', (frame) => {
+        if (frame === page.mainFrame?.()) {
+            preparationGate.invalidate('merchant_document_changed');
+            if (preparationGate.isEngaged())
+                activeRequest?.attempt.stop();
+        }
+    });
     page.on?.('framedetached', (frame) => {
         if (activeRequest?.frames.includes(frame))
             activeRequest.attempt.stop();
@@ -592,12 +650,21 @@ export async function attachToPlaywright(page, opts) {
         // untouched or the browser's CORS check fails on our synthetic answer.
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
             if (guards.matches(request.url(), request.method())) {
+                preparationGate.invalidate('unsupported_checkout');
                 lifecycle.unsupported();
                 opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
                 return route.abort('aborted');
             }
             return route.fallback();
         }
+        let preparation;
+        try {
+            preparation = preparationGate.claim(request.url());
+        }
+        catch (error) {
+            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+            return route.abort('aborted');
+        }
         // Fail closed and stay quiet: no card may reach the PSP, but neither may
         // the page's retry loop turn into a stream of doomed API calls. Every
         // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
@@ -606,6 +673,8 @@ export async function attachToPlaywright(page, opts) {
         if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
             const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
             opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+            if (preparation)
+                preparationGate.retireUnboundClaim();
             return route.abort('aborted');
         }
         // Reserved before anything that could yield, matching attachToCdp.
@@ -632,6 +701,8 @@ export async function attachToPlaywright(page, opts) {
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
             lifecycle.begin();
             activeRequest = { request, frames, attempt };
+            if (preparation)
+                await preparationGate.assertDocument();
             assertRequestLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
@@ -639,12 +710,13 @@ export async function attachToPlaywright(page, opts) {
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                cardId: opts.cardId,
+                cardId: preparation?.cardId ?? opts.cardId,
+                preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
                 merchantSignal: attempt.signal,
                 onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { if (!attempt.signal.aborted) {
+                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
                     lifecycle.approvalUrl(url);
                     return opts.onApprovalUrl?.(url);
                 } },
@@ -702,6 +774,8 @@ export async function attachToPlaywright(page, opts) {
                 activeRequest = null;
             awaitingApproval = false;
             lifecycle.end();
+            if (preparation)
+                preparationGate.retireUnboundClaim();
         }
     });
     return lifecycle;

package/dist/client.d.ts

@@ -98,6 +98,46 @@ export interface HostedFormReplay {
 }
 /** What authorize() resolves with; branch on `mode` (absent means token). */
 export type ReplayResponse = TokenReplay | CseReplay | HostedFormReplay;
+export interface PrepareCheckoutOptions {
+    psp: 'square';
+    /** The processor environment, independent of your Agentcard client's mode. */
+    environment: 'production' | 'sandbox';
+    signal?: AbortSignal;
+}
+export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
+    user: string;
+    merchant: string;
+    amountCents: number;
+    currency: string;
+    cardId?: string;
+    merchantOrigin: string;
+    checkoutKey: string;
+    timeoutMs?: number;
+    onPreparationCreated?: (id: string) => void;
+    onApprovalUrl?: (url: string) => void;
+}
+/** Real user consent and an unlocked device; no processor request or payment yet. */
+export interface PreparedCheckout {
+    readonly id: string;
+    readonly status: 'ready';
+    readonly psp: 'square';
+    readonly environment: 'production' | 'sandbox';
+    readonly expiresAt: string;
+    readonly cardId: string;
+    readonly user: string;
+    readonly merchant: string;
+    readonly amountCents: number;
+    readonly currency: string;
+    readonly merchantOrigin: string;
+    readonly checkoutKey: string;
+    readonly paymentStatus: 'not_started';
+    readonly amountAuthority: 'display_only';
+}
+export declare class CheckoutPreparationError extends Error {
+    preparationId: string | null;
+    reason: string;
+    constructor(preparationId: string | null, reason: string);
+}
 export interface AuthorizeInput {
     /** Your identifier for the person whose card should pay. */
     user: string;
@@ -141,6 +181,8 @@ export interface AuthorizeInput {
     onAuthorizationCreated?: (authorizationId: string) => void;
     /** Called once with the URL to surface to the user, if you deliver it yourself. */
     onApprovalUrl?: (url: string) => void;
+    /** One-use preparation returned by this client. Never resumes an older request. */
+    preparation?: PreparedCheckout;
 }
 export declare class CardEncryptedError extends Error {
     psp: string;
@@ -229,20 +271,27 @@ export declare class IntentNotConfirmableError extends ApprovalDeclinedError {
     readonly code: "intent_not_confirmable";
     constructor(authorizationId: string);
 }
+/** Bounded processor identifiers, never a raw response or free-form description. */
+export interface RazorpayProcessorError {
+    reason?: string;
+    source?: string;
+    step?: string;
+    payment_id?: string;
+    order_id?: string;
+}
 /**
- * The cardholder's device sent the card and the processor refused it
- * outright (a card decline, a bad CVC, an invalid request). Nothing was
- * charged; the authorization is `declined` with reason `processor_refused`
- * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
- * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
- * request is aborted and the page's retry gets a fresh approval, where the
- * person can pick another card.
+ * The device reported a processor request rejection. A generic processor
+ * code does not establish an issuer decline or prove no money moved. Read
+ * the bounded processor evidence and reconcile the merchant before retrying.
+ * The authorization remains `declined` with reason `processor_refused` for
+ * compatibility; no successful processor response is handed to the merchant.
  */
 export declare class ProcessorRefusedError extends ApprovalDeclinedError {
     authorizationId: string;
     pspErrorCode: string | null;
     readonly code: "processor_refused";
-    constructor(authorizationId: string, pspErrorCode: string | null);
+    readonly processorError: RazorpayProcessorError | null;
+    constructor(authorizationId: string, pspErrorCode: string | null, processorError?: RazorpayProcessorError | null);
 }
 /**
  * A non-2xx from the Agentcard API, carrying the status so callers can tell a
@@ -315,6 +364,8 @@ export declare class VaultClient {
     private readonly pollIntervalMs;
     private readonly unverifiableRetryDelaysMs;
     private registry;
+    private readonly preparations;
+    private readonly usedPreparations;
     constructor(opts: VaultClientOptions);
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     syncRegistry(): Promise<void>;
@@ -332,12 +383,18 @@ export declare class VaultClient {
      * these patterns pause.
      */
     cardUrlPatterns(): string[];
+    /** Wait for real device approval before the caller starts native tokenization. */
+    prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
+    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
+    cancelPreparation(id: string): Promise<void>;
     /**
      * Hand us a paused tokenization request. We ask the cardholder to approve,
      * their device supplies the card and calls the merchant, and you get back the
      * response to replay into the browser. Your process never sees a card.
      */
     authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
+    private retireUncertainPreparation;
     /** Retire only a pre-replay authorization. A 409 or missing response remains unknown. */
     cancelAuthorization(authorizationId: string): Promise<{
         id: string;

package/dist/client.js

@@ -6,6 +6,16 @@ import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecogni
  */
 export const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
 const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
+export class CheckoutPreparationError extends Error {
+    preparationId;
+    reason;
+    constructor(preparationId, reason) {
+        super(`Checkout preparation unavailable: ${reason}`);
+        this.preparationId = preparationId;
+        this.reason = reason;
+        this.name = 'CheckoutPreparationError';
+    }
+}
 export class CardEncryptedError extends Error {
     psp;
     constructor(psp) {
@@ -118,25 +128,49 @@ export class IntentNotConfirmableError extends ApprovalDeclinedError {
             + 'it cannot be confirmed again. Check the intent at Stripe before retrying.';
     }
 }
+function parseProcessorError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const fields = value;
+    const result = {};
+    const exact = (pattern, field) => pattern.exec(field)?.[0] === field;
+    for (const [key, field] of Object.entries(fields)) {
+        if (typeof field !== 'string')
+            return null;
+        if (key === 'reason' || key === 'source' || key === 'step') {
+            if (!exact(/^[a-z][a-z_]{0,63}$/, field))
+                return null;
+            result[key] = field;
+        }
+        else if (key === 'payment_id' || key === 'order_id') {
+            if (!exact(key === 'payment_id' ? /^pay_[A-Za-z0-9]{1,128}$/ : /^order_[A-Za-z0-9]{1,128}$/, field))
+                return null;
+            result[key] = field;
+        }
+        else
+            return null;
+    }
+    return Object.keys(result).length ? result : null;
+}
 /**
- * The cardholder's device sent the card and the processor refused it
- * outright (a card decline, a bad CVC, an invalid request). Nothing was
- * charged; the authorization is `declined` with reason `processor_refused`
- * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
- * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
- * request is aborted and the page's retry gets a fresh approval, where the
- * person can pick another card.
+ * The device reported a processor request rejection. A generic processor
+ * code does not establish an issuer decline or prove no money moved. Read
+ * the bounded processor evidence and reconcile the merchant before retrying.
+ * The authorization remains `declined` with reason `processor_refused` for
+ * compatibility; no successful processor response is handed to the merchant.
  */
 export class ProcessorRefusedError extends ApprovalDeclinedError {
     authorizationId;
     pspErrorCode;
     code = 'processor_refused';
-    constructor(authorizationId, pspErrorCode) {
+    processorError;
+    constructor(authorizationId, pspErrorCode, processorError = null) {
         super('processor_refused');
         this.authorizationId = authorizationId;
         this.pspErrorCode = pspErrorCode;
         this.name = 'ProcessorRefusedError';
-        this.message = `the processor refused the card on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Nothing was charged.`;
+        this.processorError = parseProcessorError(processorError);
+        this.message = `the processor rejected the payment request on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Check the merchant payment status before retrying.`;
     }
 }
 /**
@@ -223,6 +257,8 @@ export class VaultClient {
     pollIntervalMs;
     unverifiableRetryDelaysMs;
     registry;
+    preparations = new WeakSet();
+    usedPreparations = new WeakSet();
     constructor(opts) {
         this.opts = opts;
         this.baseUrl = (opts.baseUrl ?? 'https://api.agentcard.sh').replace(/\/$/, '');
@@ -274,12 +310,121 @@ export class VaultClient {
     cardUrlPatterns() {
         return deriveCardUrlPatterns(this.registry);
     }
+    /** Wait for real device approval before the caller starts native tokenization. */
+    async prepareCheckout(input) {
+        input = { ...input };
+        const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
+        if (input.psp !== 'square' || !['production', 'sandbox'].includes(input.environment))
+            throw fail('unsupported_processor');
+        if (!Number.isSafeInteger(input.amountCents) || input.amountCents <= 0 || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
+            throw fail('amount_required');
+        const origin = new URL(input.merchantOrigin);
+        if (!(origin.protocol === 'https:' || (origin.protocol === 'http:' && origin.hostname === 'localhost')) || origin.origin !== input.merchantOrigin)
+            throw fail('merchant_origin_invalid');
+        if (!input.checkoutKey || !input.user || !input.merchant)
+            throw fail('checkout_context_required');
+        const timeoutMs = input.timeoutMs ?? 15 * 60_000;
+        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
+            throw fail('timeout_invalid');
+        const signal = input.signal ? AbortSignal.any([input.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
+        if (signal.aborted)
+            throw fail('cancelled');
+        let id = null;
+        let ready = false;
+        try {
+            // Drain a sent creation even after caller cancellation to retire its ID.
+            // The separate stop signal prevents dispatch after a slow OAuth exchange.
+            const created = await this.post('/v2/checkout/preparations', {
+                user: input.user, merchant: input.merchant, amount_cents: input.amountCents, currency: input.currency.toLowerCase(),
+                ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: 'token',
+                environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
+            }, AbortSignal.timeout(30_000), signal);
+            if (!created || typeof created.id !== 'string' || !/^cprep_[A-Za-z0-9_-]{1,128}$/.test(created.id))
+                throw fail('create_unconfirmed');
+            const preparationId = created.id;
+            id = preparationId;
+            try {
+                Promise.resolve(input.onPreparationCreated?.(preparationId)).catch(() => { });
+            }
+            catch { /* observer only */ }
+            if (signal.aborted)
+                throw fail('cancelled', id);
+            if (typeof created.approvalUrl !== 'string')
+                throw fail('approval_url_missing', id);
+            try {
+                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
+            }
+            catch { /* observer only */ }
+            while (!signal.aborted) {
+                const state = await this.get(`/v2/checkout/preparations/${id}`, signal);
+                if (signal.aborted)
+                    throw fail('cancelled', id);
+                if (state?.id !== id)
+                    throw fail('status_unconfirmed', id);
+                if (state.status === 'ready') {
+                    const expiry = Date.parse(state.ready_expires_at);
+                    if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
+                        || state.payment_status !== 'not_started' || state.amount_authority !== 'display_only'
+                        || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
+                        || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
+                        || state.psp !== 'square' || state.mode !== 'token' || state.environment !== input.environment
+                        || state.checkout_key !== input.checkoutKey)
+                        throw fail('ready_unconfirmed', id);
+                    const prepared = Object.freeze({
+                        id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, expiresAt: state.ready_expires_at,
+                        cardId: state.card_id, user: input.user, merchant: input.merchant, amountCents: input.amountCents,
+                        currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
+                        paymentStatus: 'not_started', amountAuthority: 'display_only',
+                    });
+                    this.preparations.add(prepared);
+                    ready = true;
+                    return prepared;
+                }
+                if (state.status !== 'awaiting_approval')
+                    throw fail(['cancelled', 'expired', 'bound'].includes(state.status) ? state.status : 'status_unconfirmed', id);
+                await interruptibleSleep(this.pollIntervalMs, signal);
+            }
+            throw fail('cancelled', id);
+        }
+        catch (error) {
+            if (error instanceof CheckoutPreparationError)
+                throw error;
+            throw fail(signal.aborted ? 'cancelled' : 'preparation_unconfirmed', id);
+        }
+        finally {
+            if (id && !ready)
+                await this.cancelPreparation(id).catch(() => { });
+        }
+    }
+    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
+    async cancelPreparation(id) {
+        if (!/^cprep_[A-Za-z0-9_-]{1,128}$/.test(id))
+            throw new CheckoutPreparationError(null, 'id_invalid');
+        const state = await this.post(`/v2/checkout/preparations/${id}/cancel`, {}, AbortSignal.timeout(5_000));
+        if (state?.id !== id || !['cancelled', 'expired'].includes(state.status))
+            throw new CheckoutPreparationError(id, 'cancel_unconfirmed');
+    }
     /**
      * Hand us a paused tokenization request. We ask the cardholder to approve,
      * their device supplies the card and calls the merchant, and you get back the
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        const preparation = input.preparation;
+        if (preparation) {
+            if (!this.preparations.has(preparation) || this.usedPreparations.has(preparation))
+                throw new CheckoutPreparationError(preparation.id ?? null, 'already_used_or_foreign');
+            // Consume locally before any await, including OAuth, and never recycle it.
+            this.usedPreparations.add(preparation);
+            const url = new URL(input.request.url);
+            const host = preparation.environment === 'production' ? 'pci-connect.squareup.com' : 'pci-connect.squareupsandbox.com';
+            if (Date.parse(preparation.expiresAt) <= Date.now())
+                throw new CheckoutPreparationError(preparation.id, 'expired');
+            if (input.user !== preparation.user || input.merchant !== preparation.merchant || input.amountCents !== preparation.amountCents
+                || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
+                || url.origin !== `https://${host}` || url.pathname !== '/v2/card-nonce' || url.username || url.password)
+                throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        }
         if (input.signal?.aborted)
             throw new CheckoutCancelledError();
         if (input.merchantSignal?.aborted)
@@ -335,6 +480,7 @@ export class VaultClient {
             // the recognizer and refuses a disagreement before a row exists.
             mode,
             ...(input.cardId ? { cardId: input.cardId } : {}),
+            ...(preparation ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
@@ -346,21 +492,35 @@ export class VaultClient {
             created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
         }
         catch (error) {
-            if (error instanceof PaymentOutcomeUnknownError)
+            if (error instanceof PaymentOutcomeUnknownError) {
+                if (preparation && !error.authorizationId)
+                    throw new PaymentOutcomeUnknownError(await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated), error.reason);
                 throw error;
+            }
+            if (preparation && error instanceof CheckoutApiError && error.code === 'preparation_bound') {
+                const id = typeof error.details.authorization_id === 'string' && /^cauth_[A-Za-z0-9_-]+$/.test(error.details.authorization_id) ? error.details.authorization_id : null;
+                if (id) {
+                    try {
+                        Promise.resolve(input.onAuthorizationCreated?.(id)).catch(() => { });
+                    }
+                    catch { /* observer only */ }
+                }
+                throw new PaymentOutcomeUnknownError(id, 'preparation_already_bound');
+            }
             // 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
                 && error.status === 502 && (error.code === 'amount_unverifiable' || error.code === 'cse_key_unavailable');
             if ((error instanceof CheckoutApiError && error.status >= 500 && !safeReadFailure)
                 || (!(error instanceof CheckoutApiError) && !(error instanceof ApprovalDeclinedError))) {
-                throw new PaymentOutcomeUnknownError(null, 'authorization_create_unanswered');
+                throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_unanswered');
             }
             throw error;
         }
         if (!created || typeof created.id !== 'string' || !created.id)
-            throw new PaymentOutcomeUnknownError(null, 'authorization_create_malformed');
+            throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_malformed');
         const authorizationId = created.id;
+        let failed = false;
         const stopSignal = input.merchantSignal
             ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
         try {
@@ -370,10 +530,12 @@ export class VaultClient {
             catch { /* observer only */ }
             if (input.merchantSignal?.aborted)
                 throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-            try {
-                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
+            if (!preparation) {
+                try {
+                    Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
+                }
+                catch { /* approval delivery must not lose an existing authorization */ }
             }
-            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');
@@ -473,7 +635,7 @@ export class VaultClient {
                     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 ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null, s.psp === 'razorpay' ? parseProcessorError(s.processor_error) : null);
                     }
                     throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
                 }
@@ -489,12 +651,13 @@ export class VaultClient {
             throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
         }
         catch (error) {
+            failed = true;
             if (input.merchantSignal?.aborted)
                 throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
             throw error;
         }
         finally {
-            if (input.merchantSignal?.aborted) {
+            if (input.merchantSignal?.aborted || (preparation && failed)) {
                 // 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
@@ -503,6 +666,29 @@ export class VaultClient {
             }
         }
     }
+    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
+    async retireUncertainPreparation(preparation, onCreated) {
+        // Race cancellation atomically against a create still arriving at the API.
+        // A bound preparation refuses cancellation; resolve its ID exactly once below.
+        await this.cancelPreparation(preparation.id).catch(() => { });
+        let state;
+        try {
+            state = await this.get(`/v2/checkout/preparations/${preparation.id}`, AbortSignal.timeout(3_000));
+        }
+        catch {
+            return null;
+        }
+        if (state?.id !== preparation.id || state.status !== 'bound' || typeof state.authorization_id !== 'string'
+            || !/^cauth_[A-Za-z0-9_-]{1,128}$/.test(state.authorization_id))
+            return null;
+        const id = state.authorization_id;
+        try {
+            Promise.resolve(onCreated?.(id)).catch(() => { });
+        }
+        catch { /* observer only */ }
+        await this.cancelAuthorization(id).catch(() => { });
+        return id;
+    }
     /** 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))
@@ -537,7 +723,7 @@ export class VaultClient {
                 }
                 // Two 502s the API asks to be retried: Stripe did not answer the
                 // amount read-back, or Adyen did not answer the public-key fetch.
-                const retryable = err instanceof CheckoutApiError && err.status === 502
+                const retryable = !payload.preparation_id && err instanceof CheckoutApiError && err.status === 502
                     && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
                 if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
                     throw err;

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/lifecycle.d.ts

@@ -1,4 +1,4 @@
-import { type ReplayResponse } from './client.js';
+import { CheckoutPreparationError, type PrepareCheckoutOptions, type PreparedCheckout, type ReplayResponse } from './client.js';
 import type { CheckoutMode } from './registry.js';
 /** A processor approval is not an order. Only the merchant can confirm this result. */
 export type MerchantResult = {
@@ -13,8 +13,9 @@ export type MerchantResult = {
     reason: '3ds' | 'redirect' | 'other';
 };
 export interface CheckoutState {
-    status: 'idle' | 'awaiting_approval' | 'awaiting_merchant' | 'requires_user_action' | 'completed' | 'declined' | 'timed_out' | 'cancelled' | 'unsupported' | 'outcome_unknown' | 'failed';
+    status: 'idle' | 'awaiting_approval' | 'ready_to_submit' | 'awaiting_merchant' | 'requires_user_action' | 'completed' | 'declined' | 'timed_out' | 'cancelled' | 'unsupported' | 'outcome_unknown' | 'failed';
     authorizationId: string | null;
+    preparationId?: string;
     mode?: CheckoutMode;
     orderId?: string;
     /** Stable SDK category; never includes a request body, processor response, or approval link. */
@@ -36,7 +37,9 @@ export interface LifecycleOptions {
 }
 export interface CheckoutController {
     getState(): Readonly<CheckoutState>;
-    /** Stop this attachment locally. Does not revoke an approval link or cancel a processor payment. */
+    /** Await device consent before the caller starts the first native Pay action. One use per attachment. */
+    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
+    /** Stop locally and best-effort retire an unbound preparation. Does not cancel a processor payment. */
     cancel(): void;
     /** Ask the application's merchant resolver. A rejection records unknown; never automatically retries payment. */
     reconcile(): Promise<Readonly<CheckoutState>>;
@@ -57,9 +60,17 @@ export declare class CheckoutLifecycle implements CheckoutController {
     private merchantAborted;
     private unboundStripeToken;
     private reconciliation;
+    private preparationHandler?;
+    private preparationUsed;
     readonly abort: AbortController;
     constructor(options: LifecycleOptions);
     getState(): Readonly<CheckoutState>;
+    setPreparationHandler(handler: (options: PrepareCheckoutOptions) => Promise<PreparedCheckout>): void;
+    prepare(options: PrepareCheckoutOptions): Promise<PreparedCheckout>;
+    preparing(): void;
+    preparationCreated(preparationId: string): void;
+    prepared(preparation: PreparedCheckout): void;
+    preparationFailed(error: CheckoutPreparationError): void;
     isBlocked(): boolean;
     isCancelled(): boolean;
     begin(): void;

package/dist/lifecycle.js

@@ -1,4 +1,4 @@
-import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, IntentNotConfirmableError, PaymentOutcomeUnknownError } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CheckoutCancelledError, CheckoutPreparationError, IntentNotConfirmableError, PaymentOutcomeUnknownError, ProcessorRefusedError } from './client.js';
 /** Shared by the raw CDP and Playwright transports. No browser ownership or payment execution lives here. */
 export class CheckoutLifecycle {
     options;
@@ -9,16 +9,38 @@ export class CheckoutLifecycle {
     merchantAborted = false;
     unboundStripeToken = false;
     reconciliation = null;
+    preparationHandler;
+    preparationUsed = false;
     abort = new AbortController();
     constructor(options) {
         this.options = options;
     }
     getState() { return { ...this.state }; }
+    setPreparationHandler(handler) { this.preparationHandler = handler; }
+    prepare(options) {
+        if (!this.preparationHandler)
+            return Promise.reject(new CheckoutPreparationError(null, 'transport_unavailable'));
+        return this.preparationHandler(options);
+    }
+    preparing() {
+        this.preparationUsed = true;
+        this.set({ status: 'awaiting_approval', authorizationId: null });
+    }
+    preparationCreated(preparationId) { this.set({ ...this.state, preparationId }); }
+    prepared(preparation) {
+        this.set({ status: 'ready_to_submit', authorizationId: null, preparationId: preparation.id });
+    }
+    preparationFailed(error) {
+        this.held = true;
+        if (this.cancelled)
+            return;
+        this.set({ ...this.state, status: error.reason === 'expired' ? 'timed_out' : error.reason === 'cancelled' ? 'cancelled' : 'failed', reason: error.reason });
+    }
     isBlocked() { return this.held || this.cancelled; }
     isCancelled() { return this.cancelled; }
     begin() {
         this.active = true;
-        this.set({ status: 'awaiting_approval', authorizationId: null });
+        this.set({ status: 'awaiting_approval', authorizationId: null, ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}) });
     }
     end() { this.active = false; }
     set(state) {
@@ -83,6 +105,7 @@ export class CheckoutLifecycle {
         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',
+            ...(this.state.preparationId ? { preparationId: this.state.preparationId } : {}),
             ...(mismatch ? { reason: 'charged_amount_mismatch' } : this.unboundStripeToken ? { reason: 'stripe_tokenization_unbound' } : {}) });
     }
     failed(error, handoffStarted = false) {
@@ -92,7 +115,7 @@ export class CheckoutLifecycle {
             this.merchantRequestAborted();
             return;
         }
-        const authorizationId = error instanceof PaymentOutcomeUnknownError ? error.authorizationId : this.state.authorizationId;
+        const authorizationId = error instanceof PaymentOutcomeUnknownError || error instanceof ProcessorRefusedError ? error.authorizationId : this.state.authorizationId;
         if (handoffStarted || error instanceof PaymentOutcomeUnknownError || error instanceof IntentNotConfirmableError) {
             this.held = true;
             this.set({ ...this.state, authorizationId, status: 'outcome_unknown', reason: error instanceof PaymentOutcomeUnknownError ? error.reason : error instanceof IntentNotConfirmableError ? 'intent_not_confirmable' : 'browser_handoff_failed' });
@@ -100,9 +123,19 @@ export class CheckoutLifecycle {
         else if (error instanceof CheckoutCancelledError) {
             this.cancel();
         }
+        else if (error instanceof CheckoutPreparationError) {
+            this.preparationFailed(error);
+        }
         else if (error instanceof ApprovalTimeoutError) {
             this.set({ ...this.state, status: 'timed_out', reason: 'approval_expired' });
         }
+        else if (error instanceof ProcessorRefusedError) {
+            // A rejected processor request is not proof that the merchant cannot
+            // collect this payment. Keep native retries held until the application
+            // checks the merchant and explicitly starts another attempt.
+            this.held = true;
+            this.set({ ...this.state, authorizationId, status: 'declined', reason: 'processor_refused' });
+        }
         else if (error instanceof ApprovalDeclinedError) {
             this.set({ ...this.state, status: 'declined', reason: 'approval_declined' });
         }
@@ -162,6 +195,8 @@ export class CheckoutLifecycle {
         return this.getState();
     }
     retryAfterMerchantFailure(result) {
+        if (this.preparationUsed)
+            throw new Error('Prepared checkouts are single use. Reconcile this attempt and create a new attachment.');
         if (this.active || this.reconciliation)
             throw new Error('Cannot start another attempt while payment or reconciliation is in progress.');
         if (this.cancelled)

package/dist/preparation.d.ts

@@ -0,0 +1,25 @@
+import { type PreparedCheckout } from './client.js';
+import type { AttachOptions } from './cdp.js';
+import type { CheckoutLifecycle } from './lifecycle.js';
+/** A local, one-use rendezvous. It never starts or retries a merchant request. */
+export declare class PreparationGate {
+    private readonly opts;
+    private readonly lifecycle;
+    private readonly readDocumentUrl;
+    private state;
+    private observedRequest;
+    private documentUrl;
+    private prepared?;
+    private stop;
+    private expiryTimer?;
+    constructor(opts: AttachOptions, lifecycle: CheckoutLifecycle, readDocumentUrl: () => Promise<string>);
+    private prepare;
+    /** Called for every recognized card mutation, before any await or local retry guard. */
+    claim(requestUrl: string): PreparedCheckout | undefined;
+    assertDocument(): Promise<void>;
+    private readDocument;
+    isEngaged(): boolean;
+    retireUnboundClaim(): void;
+    /** A bound native request has its own cancellation/unknown-outcome machinery. */
+    invalidate(reason: string): void;
+}

package/dist/preparation.js

@@ -0,0 +1,150 @@
+import { CheckoutPreparationError } from './client.js';
+/** A local, one-use rendezvous. It never starts or retries a merchant request. */
+export class PreparationGate {
+    opts;
+    lifecycle;
+    readDocumentUrl;
+    state = 'unused';
+    observedRequest = false;
+    documentUrl = '';
+    prepared;
+    stop = new AbortController();
+    expiryTimer;
+    constructor(opts, lifecycle, readDocumentUrl) {
+        this.opts = opts;
+        this.lifecycle = lifecycle;
+        this.readDocumentUrl = readDocumentUrl;
+        lifecycle.setPreparationHandler(options => this.prepare(options));
+        lifecycle.abort.signal.addEventListener('abort', () => this.invalidate('cancelled'), { once: true });
+    }
+    async prepare(options) {
+        options = { ...options };
+        if (this.state !== 'unused' || this.observedRequest || this.lifecycle.getState().status !== 'idle' || this.lifecycle.isBlocked()) {
+            // A late opt-in cannot turn the next native retry into ordinary approval.
+            // Preserve any existing authorization's state for reconciliation.
+            if (this.state === 'unused')
+                this.state = 'failed';
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'must_prepare_before_first_request');
+        }
+        // Reserve synchronously, including while origin discovery/OAuth is pending.
+        this.state = 'preparing';
+        this.lifecycle.preparing();
+        const signal = AbortSignal.any([this.stop.signal, this.lifecycle.abort.signal, ...(options?.signal ? [options.signal] : [])]);
+        const onAbort = () => this.invalidate('cancelled');
+        signal.addEventListener('abort', onAbort, { once: true });
+        try {
+            if (!options || options.psp !== 'square' || !['production', 'sandbox'].includes(options.environment))
+                throw new CheckoutPreparationError(null, 'unsupported_processor');
+            const tokenizer = options.environment === 'production' ? 'https://pci-connect.squareup.com/v2/card-nonce' : 'https://pci-connect.squareupsandbox.com/v2/card-nonce';
+            if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
+                throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
+            if (!Number.isSafeInteger(this.opts.amountCents) || (this.opts.amountCents ?? 0) <= 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
+                throw new CheckoutPreparationError(null, 'amount_required');
+            if (signal.aborted)
+                throw new CheckoutPreparationError(null, 'cancelled');
+            this.documentUrl = await this.readDocument();
+            const page = new URL(this.documentUrl);
+            if (!(page.protocol === 'https:' || (page.protocol === 'http:' && page.hostname === 'localhost')) || page.username || page.password)
+                throw new CheckoutPreparationError(null, 'merchant_origin_invalid');
+            const prepared = await this.opts.vault.prepareCheckout({
+                ...options, user: this.opts.user, merchant: this.opts.merchant,
+                amountCents: this.opts.amountCents, currency: this.opts.currency, cardId: this.opts.cardId,
+                merchantOrigin: page.origin, checkoutKey: crypto.randomUUID(), timeoutMs: this.opts.timeoutMs, signal,
+                onPreparationCreated: id => this.lifecycle.preparationCreated(id),
+                onApprovalUrl: url => {
+                    if (!signal.aborted) {
+                        this.lifecycle.approvalUrl(url);
+                        try {
+                            Promise.resolve(this.opts.onApprovalUrl?.(url)).catch(() => { });
+                        }
+                        catch { /* observer only */ }
+                    }
+                },
+            });
+            this.prepared = prepared;
+            if (signal.aborted || this.state !== 'preparing') {
+                void this.opts.vault.cancelPreparation(prepared.id).catch(() => { });
+                throw new CheckoutPreparationError(prepared.id, 'cancelled');
+            }
+            await this.assertDocument();
+            if (signal.aborted || this.state !== 'preparing')
+                throw new CheckoutPreparationError(prepared.id, 'cancelled');
+            const remaining = Date.parse(prepared.expiresAt) - Date.now();
+            if (!(remaining > 0))
+                throw new CheckoutPreparationError(prepared.id, 'expired');
+            this.state = 'ready';
+            this.expiryTimer = setTimeout(() => this.invalidate('expired'), remaining);
+            this.expiryTimer.unref?.();
+            this.lifecycle.prepared(prepared);
+            return prepared;
+        }
+        catch (error) {
+            const failure = error instanceof CheckoutPreparationError ? error : new CheckoutPreparationError(this.prepared?.id ?? null, 'preparation_unconfirmed');
+            this.invalidate(failure.reason);
+            throw failure;
+        }
+        // Keep the signal listener after ready: caller cancellation retires the handle too.
+    }
+    /** Called for every recognized card mutation, before any await or local retry guard. */
+    claim(requestUrl) {
+        this.observedRequest = true;
+        if (this.state === 'unused')
+            return undefined;
+        if (this.state !== 'ready' || !this.prepared) {
+            this.invalidate(this.state === 'preparing' ? 'submitted_before_ready' : 'already_used_or_unavailable');
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'already_used_or_unavailable');
+        }
+        const prepared = this.prepared;
+        const request = new URL(requestUrl);
+        const origin = prepared.environment === 'production' ? 'https://pci-connect.squareup.com' : 'https://pci-connect.squareupsandbox.com';
+        if (Date.parse(prepared.expiresAt) <= Date.now() || request.origin !== origin || request.pathname !== '/v2/card-nonce' || request.username || request.password) {
+            const reason = Date.parse(prepared.expiresAt) <= Date.now() ? 'expired' : 'checkout_changed';
+            this.invalidate(reason);
+            throw new CheckoutPreparationError(prepared.id, reason);
+        }
+        this.state = 'consumed';
+        clearTimeout(this.expiryTimer);
+        return prepared;
+    }
+    async assertDocument() {
+        if (this.documentUrl && await this.readDocument() !== this.documentUrl)
+            throw new CheckoutPreparationError(this.prepared?.id ?? null, 'merchant_document_changed');
+    }
+    async readDocument() {
+        const signal = AbortSignal.any([this.stop.signal, this.lifecycle.abort.signal, AbortSignal.timeout(5_000)]);
+        const failure = () => new CheckoutPreparationError(this.prepared?.id ?? null, 'merchant_document_unavailable');
+        if (signal.aborted)
+            throw failure();
+        let aborted;
+        const stopped = new Promise((_, reject) => {
+            aborted = () => reject(failure());
+            signal.addEventListener('abort', aborted, { once: true });
+        });
+        try {
+            return await Promise.race([this.readDocumentUrl(), stopped]);
+        }
+        finally {
+            signal.removeEventListener('abort', aborted);
+        }
+    }
+    isEngaged() { return this.state !== 'unused'; }
+    retireUnboundClaim() {
+        if (this.state !== 'consumed' || !this.prepared || this.lifecycle.getState().authorizationId)
+            return;
+        void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+        // No bound ID means the adapter must not leave a spent handle appearing ready.
+        if (this.lifecycle.getState().status === 'ready_to_submit')
+            this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared.id, 'request_not_bound'));
+    }
+    /** A bound native request has its own cancellation/unknown-outcome machinery. */
+    invalidate(reason) {
+        if (this.state === 'unused' || this.state === 'consumed' || this.state === 'failed')
+            return;
+        this.state = 'failed';
+        clearTimeout(this.expiryTimer);
+        this.stop.abort();
+        if (this.prepared)
+            void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+        this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared?.id ?? null, reason));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-cards/checkout",
-  "version": "0.3.1",
+  "version": "0.4.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,8 +23,8 @@
     "_comment_build": "TypeScript is fetched rather than declared as a devDependency ON PURPOSE. This package ships zero dependencies, which is why pnpm writes no importer for it in the workspace lockfile; adding any dep here creates one, and an importer the lockfile has not been regenerated for fails every Vercel build with ERR_PNPM_OUTDATED_LOCKFILE. Pinned so the published output is reproducible.",
     "build": "npx -y -p typescript@5.9.3 tsc",
     "prepublishOnly": "pnpm build",
-    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs",
-    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs"
+    "test": "node test.mjs && node --test lifecycle.test.mjs merchant-abort.test.mjs preparation.test.mjs",
+    "test:browser": "node browser.test.mjs && node stripe-browser.test.mjs && node preparation-browser.test.mjs"
   },
   "keywords": [
     "payments",