@agent-cards/checkout 0.2.0 → 0.3.0

package/dist/cdp.js

@@ -1,7 +1,8 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
-import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, UnsupportedModeError, redactUrl, } from './client.js';
+import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, UnsupportedModeError, redactUrl, } from './client.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
+import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
 // Every URL that leaves this module through onEvent is redacted to origin +
 // path first. A paused PaymentIntent confirm can carry the client secret in
 // its query string (Stripe.js puts it in the body; hand-rolled runtimes and
@@ -141,6 +142,128 @@ function pausedBody(request) {
     return Buffer.concat(entries.map((e) => Buffer.from(e.bytes, 'base64'))).toString('utf8');
 }
 const BODY_UNREADABLE_REASON = 'the paused request\'s body could not be read (no postData and no postDataEntries)';
+/**
+ * The CORS headers a fulfilled CROSS-ORIGIN request needs, or null when the
+ * request is same-origin (or carries no Origin, so no CORS check applies).
+ *
+ * The browser checks a fulfilled response exactly as it checks a real one. A
+ * page that fetches a processor on another origin therefore needs
+ * `access-control-allow-origin` on the synthetic answer, or its fetch rejects
+ * with "Failed to fetch" and the page never sees the processor's reply, even
+ * though the cardholder approved and the processor answered the vault.
+ * Shopify never hit this on its current host: the checkout.pci.shopifyinc.com
+ * card iframe posts to its own origin (its older deposit.<region>.shopifycs.com
+ * host is called from the checkout.shopifycs.com frame, cross-origin, and gets
+ * the answer like everyone else). Stripe hits it on every surface (Checkout on
+ * checkout.stripe.com or a merchant domain, and Elements in the js.stripe.com
+ * frame, all call api.stripe.com), and so does every other processor whose
+ * card frame calls a separate API host. Observed live on
+ * 2026-09-03: the vault replayed a Stripe PaymentMethod into a raw-CDP
+ * runtime, the browser refused the answer for want of this header, and
+ * Stripe Checkout showed "We are experiencing connection issues".
+ *
+ * The exact Origin is echoed rather than `*`: a credentialed request refuses
+ * `*`, the echo satisfies both. The processor's own value can never reach
+ * this adapter (a browser does not expose that header to the page that
+ * replayed the call), so whatever the replay carries under these names is
+ * replaced by the one value that is right for THIS request. Playwright adds
+ * the same headers inside route.fulfill when a cross-origin fulfill carries
+ * none (microsoft/playwright#12929), which is why attachToPlaywright never
+ * needed this; it writes them itself anyway, replacing a stale value, so both
+ * adapters answer the vault's replays identically.
+ *
+ * This widens nothing. A tokenization endpoint is built for anonymous
+ * browsers and answers every origin (`access-control-allow-origin: *` on
+ * Stripe's and Shopify's own replies), so the page that made the request
+ * could always read the processor's answer to it; the replay is made exactly
+ * as visible, to exactly that page. Whether a card goes anywhere at all is
+ * decided by the cardholder on the approval screen, never by this header.
+ *
+ * Only what a browser serializes is ever echoed: one canonical http(s)
+ * origin (`new URL(origin).origin === origin`), or the opaque `null` a
+ * sandboxed or data: document sends, which Chrome matches against
+ * `access-control-allow-origin: null` and which Playwright echoes too. That
+ * refuses userinfo, a path, an explicit default port, several origins in one
+ * value, or a control character that would break the fulfill after the
+ * cardholder already approved. Anything refused simply gets no CORS answer,
+ * which is what every fulfill got before this existed.
+ */
+export function corsHeadersFor(url, requestHeaders) {
+    return corsDecision(url, requestHeaders).headers;
+}
+/** The CORS answer and its reason: `none` when no usable Origin was sent (or the url is not http(s)), `same_origin` when no check applies. */
+export function corsDecision(url, requestHeaders) {
+    const none = { headers: null, outcome: 'none' };
+    const originEntry = Object.entries(requestHeaders ?? {}).find(([name]) => name.toLowerCase() === 'origin');
+    const origin = typeof originEntry?.[1] === 'string' ? originEntry[1].trim() : '';
+    if (!origin)
+        return none;
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return none;
+    }
+    if (target.protocol !== 'https:' && target.protocol !== 'http:')
+        return none;
+    if (origin !== 'null') {
+        let originUrl;
+        try {
+            originUrl = new URL(origin);
+        }
+        catch {
+            return none;
+        }
+        if (originUrl.protocol !== 'https:' && originUrl.protocol !== 'http:')
+            return none;
+        if (originUrl.origin !== origin)
+            return none;
+        if (target.origin === origin)
+            return { headers: null, outcome: 'same_origin' };
+    }
+    return { headers: { 'access-control-allow-origin': origin, 'access-control-allow-credentials': 'true' }, outcome: 'echoed' };
+}
+/**
+ * `headers` with the CORS answer for this request written in; the object
+ * itself when none is needed. Any header the answer names is replaced
+ * whatever its case, so a name is never sent twice. The answer varies by
+ * Origin, and a `vary` the replay already carries is extended rather than
+ * replaced (or left alone when it already covers Origin or is `*`); a `vary`
+ * the answer itself names is taken as given.
+ */
+export function withCorsHeaders(headers, cors) {
+    if (!cors)
+        return headers;
+    const replaced = new Set(Object.keys(cors).map((name) => name.toLowerCase()));
+    const out = {};
+    let varyName = null;
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        if (replaced.has(lower))
+            continue;
+        if (lower === 'vary')
+            varyName = name;
+        out[name] = value;
+    }
+    Object.assign(out, cors);
+    if (replaced.has('vary'))
+        return out;
+    if (varyName === null) {
+        out.vary = 'Origin';
+    }
+    else {
+        const existing = String(out[varyName]);
+        const members = existing.split(',').map((m) => m.trim().toLowerCase());
+        if (!members.includes('origin') && !members.includes('*'))
+            out[varyName] = `${existing}, Origin`;
+    }
+    return out;
+}
+/** CDP's header shape: `{ name, value }` entries. */
+function headerEntries(headers) {
+    return Object.entries(headers).map(([name, value]) => ({ name, value: String(value) }));
+}
 /**
  * Last-resort patterns: the built-in recognizers' hosts, derived the same way
  * as everything else. Used only when the vault hands back nothing at all (a
@@ -148,6 +271,19 @@ const BODY_UNREADABLE_REASON = 'the paused request\'s body could not be read (no
  * that drifts from the registry is exactly the bug this adapter used to have.
  */
 const FALLBACK_CARD_PATTERNS = cardUrlPatterns(BUILTIN_REGISTRY);
+/** Observer exceptions and server error envelopes must not interrupt or leak a processor handoff. */
+function safeOptions(opts) {
+    const observer = opts.onEvent;
+    return { ...opts, onEvent: (event) => { try {
+            Promise.resolve(observer?.(event)).catch(() => { });
+        }
+        catch { /* observer only */ } } };
+}
+function failureSummary(error) {
+    if (error instanceof CheckoutApiError)
+        return `${error.name}: ${error.code ?? `http_${error.status}`}`;
+    return error instanceof Error ? error.name : 'CheckoutError';
+}
 /**
  * Take over card tokenization for a page.
  *
@@ -166,6 +302,9 @@ const FALLBACK_CARD_PATTERNS = cardUrlPatterns(BUILTIN_REGISTRY);
  * armed identically.
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
+    opts = safeOptions(opts);
+    const lifecycle = new CheckoutLifecycle(opts);
+    const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
     // Set once a failure proves that retrying cannot help; see isTerminal.
     let terminal = null;
@@ -178,25 +317,34 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
     const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
-    const urlPatterns = derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS;
+    const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns])];
     opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
     const arm = async (sessionId) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
-        armed.add(key);
         await cdp.send('Fetch.enable', {
             patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-        }, sessionId).catch(() => { });
+        }, sessionId);
         // Descend into this target's own children (iframes inside iframes).
         await cdp.send('Target.setAutoAttach', {
             autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
-        }, sessionId).catch(() => { });
+        }, sessionId);
+        armed.add(key);
     };
     cdp.on(async (method, params, sessionId) => {
         if (method === 'Target.attachedToTarget') {
             const child = params.sessionId;
-            await arm(child);
+            try {
+                await arm(child);
+            }
+            catch {
+                terminal = new Error('browser_interception_unavailable');
+                lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
+                opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
+                // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
+                return;
+            }
             // Child targets start paused when waitForDebuggerOnStart is set.
             await cdp.send('Runtime.runIfWaitingForDebugger', {}, child).catch(() => { });
             return;
@@ -205,14 +353,20 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         const { requestId, request, resourceType } = params;
         if (!opts.vault.isCardRequest(request.url, request.method)) {
+            if (guards.matches(request.url, request.method)) {
+                lifecycle.unsupported();
+                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url), method: request.method } });
+                await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+                return;
+            }
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             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 || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+        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) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
             return;
         }
@@ -220,6 +374,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;
+        let handoffStarted = false;
         try {
             const body = pausedBody(request);
             if (body === null) {
@@ -239,15 +394,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 return;
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url), ...(resourceType ? { resourceType } : {}) } });
+            lifecycle.begin();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                onApprovalUrl: opts.onApprovalUrl,
+                cardId: opts.cardId,
+                timeoutMs: opts.timeoutMs,
+                signal: lifecycle.abort.signal,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
                 request: { url: request.url, method: request.method, headers: request.headers, body },
             });
+            if (lifecycle.isCancelled())
+                throw new Error('checkout cancelled locally after approval');
+            lifecycle.prepareHandoff(replay, request.url);
+            handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
                 // The device submitted the processor's own form; the processor
                 // answered the device. The paused NAVIGATION is fulfilled with a page
@@ -255,10 +419,12 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // why not a fake result page), and the same form is refused if the
                 // page posts it again.
                 const page = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                // A navigation response is never CORS-checked, so the CORS wrap is
+                // inert here; it is applied so every fulfill goes through one path.
                 await cdp.send('Fetch.fulfillRequest', {
                     requestId,
                     responseCode: page.status,
-                    responseHeaders: Object.entries(page.headers).map(([name, value]) => ({ name, value })),
+                    responseHeaders: headerEntries(withCorsHeaders(page.headers, corsHeadersFor(request.url, request.headers))),
                     body: Buffer.from(page.body).toString('base64'),
                 }, sessionId);
                 lastSubmitted = { url: request.url, body, at: Date.now() };
@@ -272,35 +438,48 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 // and cookies, and only the four ciphertext fields swapped in. Only
                 // postData rides on the command: no header override, ever (see
                 // cseBody for why a recomputed Content-Length is refused by Chromium).
+                const postData = Buffer.from(cseBody(body, replay)).toString('base64');
+                handoffStarted = true;
                 await cdp.send('Fetch.continueRequest', {
                     requestId,
-                    postData: Buffer.from(cseBody(body, replay)).toString('base64'),
+                    postData,
                 }, sessionId);
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
+                // The processor's answer, handed to the page as if the processor had
+                // sent it. Cross-origin, the browser then runs its CORS check on it:
+                // see corsHeadersFor for why the answer has to carry the headers. The
+                // decision rides on the event, so a fulfill the page could not read
+                // (no usable Origin on a cross-origin request) is visible in telemetry
+                // rather than only as the page's own "connection error".
+                const cors = corsDecision(request.url, request.headers);
                 await cdp.send('Fetch.fulfillRequest', {
                     requestId,
                     responseCode: replay.status,
-                    responseHeaders: Object.entries(replay.headers).map(([name, value]) => ({ name, value: String(value) })),
+                    responseHeaders: headerEntries(withCorsHeaders(replay.headers, cors.headers)),
                     body: Buffer.from(replay.body).toString('base64'),
                 }, sessionId);
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: String(err) });
+            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
             await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
         }
         finally {
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
     await arm(pageSessionId);
+    return lifecycle;
 }
 /**
  * Playwright convenience wrapper — the path for cloud browsers that hand you a
@@ -314,6 +493,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
  * the note in the body for why a hand-rolled CDPSession does not work here.
  */
 export async function attachToPlaywright(page, opts) {
+    opts = safeOptions(opts);
+    // Routing cannot see requests owned by a service worker. Existing controlled
+    // contexts must be recreated with serviceWorkers: 'block' before checkout.
+    if (page.context?.().serviceWorkers?.().length) {
+        throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
+    }
+    const lifecycle = new CheckoutLifecycle(opts);
+    const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
     // A CDPSession from `newCDPSession(page)` is bound to the PAGE target and its
@@ -336,11 +523,16 @@ export async function attachToPlaywright(page, opts) {
     // 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;
-    await page.route((url) => opts.vault.isCardRequest(url.toString()), async (route) => {
+    await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
         const request = route.request();
         // The matcher only sees the URL; a preflight or a GET must pass through
         // untouched or the browser's CORS check fails on our synthetic answer.
         if (!opts.vault.isCardRequest(request.url(), request.method())) {
+            if (guards.matches(request.url(), request.method())) {
+                lifecycle.unsupported();
+                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+                return route.abort('aborted');
+            }
             return route.fallback();
         }
         // Fail closed and stay quiet: no card may reach the PSP, but neither may
@@ -348,13 +540,14 @@ export async function attachToPlaywright(page, opts) {
         // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
         // CDP adapter's Fetch.failRequest uses, so a refused navigation
         // resolves identically whichever adapter is attached.
-        if (terminal || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: String(why) });
+        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) });
             return route.abort('aborted');
         }
         // Reserved before anything that could yield, matching attachToCdp.
         awaitingApproval = true;
+        let handoffStarted = false;
         try {
             const body = request.postData() ?? '';
             if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
@@ -362,20 +555,30 @@ export async function attachToPlaywright(page, opts) {
                 return await route.abort('aborted');
             }
             opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+            lifecycle.begin();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
                 amountCents: opts.amountCents,
                 currency: opts.currency,
-                onApprovalUrl: opts.onApprovalUrl,
+                cardId: opts.cardId,
+                timeoutMs: opts.timeoutMs,
+                signal: lifecycle.abort.signal,
+                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                onApprovalUrl: (url) => { lifecycle.approvalUrl(url); return opts.onApprovalUrl?.(url); },
                 request: { url: request.url(), method: request.method(), headers: request.headers(), body },
             });
+            if (lifecycle.isCancelled())
+                throw new Error('checkout cancelled locally after approval');
+            lifecycle.prepareHandoff(replay, request.url());
+            handoffStarted = replay.mode !== 'cse';
             if (replay.mode === 'hosted_form') {
                 // Same as the CDP path: the paused navigation resolves to the
                 // synthetic page, and a re-post of this form is refused.
                 const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
-                await route.fulfill({ status: synthetic.status, headers: synthetic.headers, body: synthetic.body });
+                // 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 });
                 lastSubmitted = { url: request.url(), body, at: Date.now() };
                 opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
             }
@@ -383,24 +586,34 @@ export async function attachToPlaywright(page, opts) {
                 // Same as the CDP path: the request continues from this browser
                 // with the ciphertext swapped in and no header override; Playwright
                 // recomputes the length itself.
-                await route.continue({ postData: cseBody(body, replay) });
+                const postData = cseBody(body, replay);
+                handoffStarted = true;
+                await route.continue({ postData });
                 opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
             }
             else {
-                await route.fulfill({ status: replay.status, headers: replay.headers, body: replay.body });
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null } });
+                // Playwright adds these itself when a cross-origin fulfill carries
+                // none; written here anyway (replacing a stale value) so a
+                // cross-origin answer is the same whichever adapter ran.
+                const cors = corsDecision(request.url(), request.headers());
+                await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
             }
+            lifecycle.handedOff(replay);
         }
         catch (err) {
+            lifecycle.failed(err, handoffStarted);
             if (isTerminal(err))
                 terminal = err;
             else if (isApprovalOutcome(err))
                 quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: String(err) });
+            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
             await route.abort('aborted');
         }
         finally {
             awaitingApproval = false;
+            lifecycle.end();
         }
     });
+    return lifecycle;
 }

package/dist/client.d.ts

@@ -133,6 +133,10 @@ export interface AuthorizeInput {
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
+    /** Stops local polling; it does not revoke a pending approval or undo a payment. */
+    signal?: 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. */
     onApprovalUrl?: (url: string) => void;
 }
@@ -141,10 +145,9 @@ export declare class CardEncryptedError extends Error {
     constructor(psp: string);
 }
 /**
- * The API approved an authorization in a mode this SDK build cannot finish.
- * Unreachable by construction (syncRegistry asks only for SUPPORTED_MODES and
- * every create names its mode), so it is treated as terminal: retrying the
- * same page could only raise more prompts for the same dead end.
+ * The registry requests a mode this SDK build cannot finish, before creation.
+ * A response in an unexpected mode after creation has an unknown payment
+ * outcome instead and raises PaymentOutcomeUnknownError.
  */
 export declare class UnsupportedModeError extends Error {
     mode: string;
@@ -153,6 +156,15 @@ export declare class UnsupportedModeError extends Error {
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
+export declare class CheckoutCancelledError extends Error {
+    constructor();
+}
+/** The payment may have reached the processor. Reconcile the merchant order before any new attempt. */
+export declare class PaymentOutcomeUnknownError extends Error {
+    authorizationId: string | null;
+    reason: string;
+    constructor(authorizationId: string | null, reason: string);
+}
 export declare class ApprovalDeclinedError extends Error {
     constructor(reason: string);
 }