@agent-cards/checkout 0.6.0 → 0.8.0

package/dist/client.d.ts

@@ -19,12 +19,28 @@ export declare const SUPPORTED_MODES: readonly CheckoutMode[];
  * (hosted_form: the bytes the device submits name the amount), or a display
  * fact on a template that carries no amount.
  */
-export type AmountAuthority = 'stripe_payment_intent' | 'hosted_form_sum' | 'display_only';
+/**
+ * Who named the amount an authorization carries: `processor` (the paused
+ * request's own bytes, or the Stripe intent it names, read back by Agentcard),
+ * `agent` (the `amount` you passed), `page` (the total read off the checkout
+ * page), or `none` (nobody yet; the processor is read right before the card
+ * is sent).
+ */
+export type AmountAuthority = 'processor' | 'agent' | 'page' | 'none';
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export declare function validAmountInput(amount: unknown): amount is number | string;
+/** How an existing authorization is being handled; omitted by older APIs. */
+export interface ExecutionMetadata {
+    executionMode?: 'user_approval' | 'autopilot';
+    grantId?: string;
+}
 /**
  * The token flow: the cardholder's device called the processor itself, and
  * this is the processor's answer to replay into the paused request.
  */
-export interface TokenReplay {
+export interface TokenReplay extends ExecutionMetadata {
+    /** Present only after validating the explicit owned-shop purchase receipt. */
+    shopOrderId?: string;
     /** Absent on older API versions; always 'token' here. */
     mode?: 'token';
     /** The approved authorization (`cauth_…`). */
@@ -41,17 +57,18 @@ export interface TokenReplay {
      * moved) and Agentcard also sent your server checkout_authorization.amount_mismatch.
      */
     amountVerified?: boolean | null;
-    chargedAmountCents?: number | null;
+    /** What the processor collected, an integer in the currency's smallest unit (Stripe's `amount`). */
+    chargedAmount?: number | null;
     chargedCurrency?: string | null;
     /**
-     * What `chargedAmountCents` is: 'captured' (the intent succeeded; this is
+     * What `chargedAmount` is: 'captured' (the intent succeeded; this is
      * amount_received), 'authorized' (requires_capture; amount_capturable, the
      * merchant captures later), 'none' (a PaymentIntent was reported but
      * nothing is collected yet: processing, requires_action), or null when no
      * PaymentIntent was reported at all (a tokenization request).
      */
     chargedKind?: 'captured' | 'authorized' | 'none' | null;
-    /** 'stripe_payment_intent' when the amount was held to a Stripe intent; 'display_only' otherwise. */
+    /** Who named the amount the person approved. */
     amountAuthority?: AmountAuthority;
 }
 /**
@@ -63,7 +80,7 @@ export interface TokenReplay {
  * The processor's answer then reaches the page as it normally would; the
  * merchant's order state is where the outcome shows up.
  */
-export interface CseReplay {
+export interface CseReplay extends ExecutionMetadata {
     mode: 'cse';
     authorizationId: string;
     substitutions: Substitutions;
@@ -86,7 +103,7 @@ export interface CseReplay {
  * processor evidence on this mode and cannot obtain any. Treat it as "the
  * person paid, or tried to, on their own device" and confirm with the merchant.
  */
-export interface HostedFormReplay {
+export interface HostedFormReplay extends ExecutionMetadata {
     mode: 'hosted_form';
     /** What this resolution is: a device-attested submission, not a processor answer. */
     kind: 'submitted_on_device';
@@ -108,7 +125,8 @@ export interface PrepareCheckoutOptions {
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
     user: string;
     merchant: string;
-    amountCents: number;
+    /** An integer in the currency's smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06"). */
+    amount: number | string;
     currency: string;
     cardId?: string;
     merchantOrigin: string;
@@ -127,42 +145,50 @@ export interface PreparedCheckout {
     readonly cardId: string;
     readonly user: string;
     readonly merchant: string;
-    readonly amountCents: number;
+    /** The approved amount, an integer in the currency's smallest unit, as the API confirmed it. */
+    readonly amount: number;
+    readonly amountDisplay: string | null;
     readonly currency: string;
     readonly merchantOrigin: string;
     readonly checkoutKey: string;
     readonly paymentStatus: 'not_started';
-    readonly amountAuthority: 'display_only';
+    readonly amountAuthority: 'agent';
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
     reason: string;
     constructor(preparationId: string | null, reason: string);
 }
-export interface AuthorizeInput {
+export interface AuthorizeInput extends ExecutionMetadata {
+    /** Observed top-level HTTPS merchant origin; a routing hint, never payment authority. */
+    merchantOrigin?: string;
     /** Your identifier for the person whose card should pay. */
     user: string;
-    /** Shown to the user on the approval screen. */
+    /** Shown to the user on the approval screen. Judged by nothing: the merchant comes from the checkout page. */
     merchant: string;
     /**
-     * The display string the approval screen shows ("$23.06"). Optional when
-     * amountCents + currency are given, and IGNORED then: Agentcard derives the
-     * string from the number so every surface shows one amount.
+     * Your hint at the amount: an integer in the currency's smallest unit (2306
+     * for $23.06), or a decimal string in normal units ("23.06"), with its ISO
+     * 4217 code ("usd"). Optional: the processor's own amount is the higher
+     * authority, read from the paused request or from the Stripe intent it
+     * names right before the cardholder's device replays, and the company's
+     * caps are judged on it. A hint lets a bad purchase be refused the moment
+     * you open it, and a hint that disagrees with the processor beyond one
+     * smallest unit is refused with nothing charged (an AmountMismatchError;
+     * `stage` says which check). Agentcard derives the display string; you
+     * never send one. Both or neither: one without the other is refused.
      */
-    amount?: string;
+    amount?: number | string;
+    currency?: string;
     /**
-     * The amount as a number in the smallest currency unit (2306 for $23.06)
-     * with its ISO 4217 code ("usd"). On a Stripe PaymentIntent confirm this
-     * pair is BOUND to the intent: Agentcard reads the intent back from Stripe
-     * at create and again right before the cardholder's device replays, and a
-     * different amount is refused with nothing charged (an AmountMismatchError
-     * either way: `stage` says which check). After the replay the charge is
-     * reconciled against the approval (see ReplayResponse.amountVerified).
-     * Tokenization requests carry no amount, so there it is display-only.
-     * Both or neither: one without the other is refused.
+     * The total read off the checkout page, the lowest authority: used only
+     * when neither the processor's request nor your hint names an amount. The
+     * adapters fill it from `[data-agentcard-amount]` when a page carries one.
      */
-    amountCents?: number;
-    currency?: string;
+    pageAmount?: {
+        amount: number;
+        currency: string;
+    };
     /**
      * WHICH stored card should pay — a vault card id from
      * GET /api/v2/vault_cards. The approval page preselects it (the human can
@@ -171,6 +197,14 @@ export interface AuthorizeInput {
      * `card_not_found`.
      */
     cardId?: string;
+    /**
+     * The origin of the checkout page the payment form was on
+     * (https://shop.example.com). The adapters read it from the page; pass it
+     * yourself when you run your own interception. With the processor identity
+     * in the paused request this is what names the merchant for the company's
+     * presets; `merchant` above is shown to the person and judged by nothing.
+     */
+    pageOrigin?: string;
     request: PausedRequest;
     /** Abort if the user has not approved within this many ms. Default 15 min. */
     timeoutMs?: number;
@@ -300,6 +334,69 @@ export declare class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export declare class PresetRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: string;
+    readonly detail: string | null;
+    readonly preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null;
+    readonly rule: string | null;
+    readonly stage: 'create' | 'pre_replay';
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    readonly attachment: PresetAttachment | null;
+    /** The preset's name. */
+    readonly presetName: string | null;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    readonly refusals: readonly PresetRefusal[];
+    constructor(authorizationId: string | null, code: string, detail: string | null, preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null, rule: string | null, stage: 'create' | 'pre_replay', 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment?: PresetAttachment | null, refusals?: readonly PresetRefusal[]);
+}
+/** The stored card a preset is attached to, with its last four digits. */
+export interface PresetAttachment {
+    kind: 'card';
+    targetId: string | null;
+    last4: string | null;
+}
+/** One preset's refusal of a purchase. */
+export interface PresetRefusal {
+    preset: {
+        id: string;
+        version: number;
+        name: string;
+    };
+    attachment: PresetAttachment | null;
+    rule: string | null;
+    code: string;
+    detail: string | null;
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export declare const PRESET_REFUSAL_REASONS: ReadonlySet<string>;
 export declare class CheckoutApiError extends Error {
     status: number;
     path: string;

package/dist/client.js

@@ -1,12 +1,19 @@
 import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
 import { matchesPreparedRequest, validPreparationEnvironment } from './prepared-processor.js';
+import { hasOwnedShopMarker, parseOwnedShopOrder, parseOwnedShopReceipt } from './owned-shop.generated.js';
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
  * is never paused) and sent on every create.
  */
 export const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
-const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export function validAmountInput(amount) {
+    if (typeof amount === 'number')
+        return Number.isSafeInteger(amount) && amount >= 0;
+    return typeof amount === 'string' && /^\d{1,15}\.\d{1,3}$/.test(amount.trim());
+}
+const AMOUNT_AUTHORITIES = ['processor', 'agent', 'page', 'none'];
 export class CheckoutPreparationError extends Error {
     preparationId;
     reason;
@@ -180,6 +187,94 @@ export class ProcessorRefusedError extends ApprovalDeclinedError {
  * retrying is worth anything: a 404 `connection_not_found` will answer the same
  * way forever, while a 429 or a 502 will not.
  */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export class PresetRefusedError extends ApprovalDeclinedError {
+    authorizationId;
+    code;
+    detail;
+    preset;
+    rule;
+    stage;
+    attachment;
+    /** The preset's name. */
+    presetName;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    refusals;
+    constructor(authorizationId, code, detail, preset, rule, stage, 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment = null, refusals = []) {
+        super(code);
+        this.authorizationId = authorizationId;
+        this.code = code;
+        this.detail = detail;
+        this.preset = preset;
+        this.rule = rule;
+        this.stage = stage;
+        this.attachment = attachment;
+        this.name = 'PresetRefusedError';
+        this.presetName = preset?.name ?? null;
+        this.refusals = refusals.length ? refusals : preset ? [{ preset, attachment, rule, code, detail }] : [];
+        const others = this.refusals.slice(1).map((r) => `"${r.preset.name}"`);
+        const also = others.length ? ` Also refused by ${others.length === 1 ? 'preset' : 'presets'} ${others.join(', ')}.` : '';
+        this.message = `refused by the company preset${preset ? ` "${preset.name}"` : ''} (${code}${stage === 'create' ? ', before any authorization was created' : ''}): ${detail ?? 'this purchase is outside the rules the company set'}${also}`;
+    }
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export const PRESET_REFUSAL_REASONS = new Set([
+    'spend_total_exceeded', 'spend_rate_exceeded', 'spend_rate_unknown', 'amount_unknown', 'rate_unavailable',
+    'category_denied', 'category_unknown', 'merchant_denied', 'merchant_unknown',
+    'geo_denied', 'geo_unknown', 'currency_denied', 'currency_unknown',
+    'time_window_denied', 'surface_denied', 'surface_unknown',
+]);
+function presetOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const p = v;
+    if (typeof p.id !== 'string' || typeof p.version !== 'number' || typeof p.name !== 'string')
+        return null;
+    return { id: p.id, version: p.version, name: p.name };
+}
+function attachmentOf(v) {
+    if (!v || typeof v !== 'object')
+        return null;
+    const a = v;
+    if (a.kind !== 'card')
+        return null;
+    return { kind: a.kind, targetId: typeof a.target_id === 'string' ? a.target_id : null, last4: typeof a.last4 === 'string' ? a.last4 : null };
+}
+/** The `refusals` list of a refusal envelope: every entry that names a preset. */
+function refusalsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const r = item;
+        const preset = presetOf(r.preset);
+        if (!preset || typeof r.reason !== 'string')
+            continue;
+        out.push({ preset, attachment: attachmentOf(r.attachment), rule: typeof r.rule === 'string' ? r.rule : null, code: r.reason, detail: typeof r.message === 'string' ? r.message : null });
+    }
+    return out;
+}
 export class CheckoutApiError extends Error {
     status;
     path;
@@ -218,6 +313,12 @@ export class CheckoutApiError extends Error {
     get permanent() {
         if (this.code === 'amount_mismatch' || this.code === 'duplicate_submission')
             return false;
+        // Nor a refusal by the company preset (a 403 carrying `preset` in the
+        // envelope): the company's rules refused THIS purchase, at this merchant,
+        // for this amount, at this hour. The next one on the same page may pass,
+        // so the page is quieted like a decline, never latched.
+        if (this.details.preset && typeof this.details.preset === 'object')
+            return false;
         return this.status >= 400 && this.status < 500 && this.status !== 429;
     }
 }
@@ -317,7 +418,7 @@ export class VaultClient {
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
         if (!validPreparationEnvironment(input.psp, 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))
+        if (!validAmountInput(input.amount) || 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)
@@ -336,7 +437,7 @@ export class VaultClient {
             // 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(),
+                user: input.user, merchant: input.merchant, amount: input.amount, 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);
@@ -365,17 +466,18 @@ export class VaultClient {
                 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.payment_status !== 'not_started' || state.amount_authority !== 'agent'
                         || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
-                        || state.amount_cents !== input.amountCents || state.currency !== input.currency.toLowerCase()
+                        || !Number.isSafeInteger(state.amount) || (typeof input.amount === 'number' && state.amount !== input.amount) || state.currency !== input.currency.toLowerCase()
                         || state.psp !== input.psp || 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,
+                        cardId: state.card_id, user: input.user, merchant: input.merchant, amount: state.amount,
+                        amountDisplay: typeof state.amount_display === 'string' ? state.amount_display : null,
                         currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
-                        paymentStatus: 'not_started', amountAuthority: 'display_only',
+                        paymentStatus: 'not_started', amountAuthority: 'agent',
                     });
                     this.preparations.add(prepared);
                     ready = true;
@@ -411,6 +513,27 @@ export class VaultClient {
      * response to replay into the browser. Your process never sees a card.
      */
     async authorize(input) {
+        const ownedShop = hasOwnedShopMarker(input.request);
+        const shopOrder = ownedShop ? parseOwnedShopOrder(input.request) : null;
+        if (ownedShop) {
+            if (!shopOrder || input.preparation || input.executionMode === 'user_approval' ||
+                !input.merchantOrigin || (input.amount != null && input.amount !== shopOrder.amount &&
+                !(typeof input.amount === 'string' && Number(input.amount) * 100 === shopOrder.amount)) ||
+                (input.currency !== undefined && input.currency.toLowerCase() !== shopOrder.currency))
+                throw new Error('The shop order cannot use this checkout configuration.');
+            input = { ...input, amount: shopOrder.amount, currency: shopOrder.currency };
+        }
+        if (input.executionMode !== undefined && !['user_approval', 'autopilot'].includes(input.executionMode))
+            throw new Error('Unsupported checkout execution mode.');
+        if (input.grantId !== undefined && !/^apg_[A-Za-z0-9_-]{1,128}$/.test(input.grantId))
+            throw new Error('Invalid autopilot grant ID.');
+        if (input.preparation && (input.executionMode === 'autopilot' || input.grantId))
+            throw new Error('A device preparation cannot also select autopilot.');
+        if (input.merchantOrigin !== undefined && !input.preparation) {
+            const merchantUrl = new URL(input.merchantOrigin);
+            if (merchantUrl.protocol !== 'https:' || merchantUrl.origin !== input.merchantOrigin)
+                throw new Error('merchantOrigin must be an exact HTTPS origin.');
+        }
         const preparation = input.preparation;
         if (preparation) {
             if (!this.preparations.has(preparation) || this.usedPreparations.has(preparation))
@@ -419,7 +542,7 @@ export class VaultClient {
             this.usedPreparations.add(preparation);
             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
+            if (input.user !== preparation.user || input.merchant !== preparation.merchant || (typeof input.amount === 'number' && input.amount !== preparation.amount) || (typeof input.amount === 'string' && !validAmountInput(input.amount))
                 || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
                 || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
@@ -452,16 +575,16 @@ export class VaultClient {
             throw new Error(`checkout authorization is POST-only; got ${method} for ${redactUrl(input.request.url)}. ` +
                 'A non-POST tokenizer needs recognizer support before it can be intercepted.');
         }
-        // The amount travels as a display string, a number with its currency, or
-        // both. Refuse half a pair here, before a network call: the API would too,
-        // and a retry loop cannot fix a missing field.
-        const hasCents = input.amountCents != null;
+        // The amount is a hint: a pair or nothing. Refuse half a pair here, before
+        // a network call: the API would too, and a retry loop cannot fix a
+        // missing field. The processor's own amount is read by Agentcard.
+        const hasAmount = input.amount != null;
         const hasCurrency = typeof input.currency === 'string' && input.currency.length > 0;
-        if (hasCents !== hasCurrency) {
-            throw new Error('amountCents and currency go together: pass both or neither.');
+        if (hasAmount !== hasCurrency) {
+            throw new Error('amount and currency go together: pass both or neither.');
         }
-        if (!input.amount && !hasCents) {
-            throw new Error('authorize needs amount (a display string), or amountCents with currency.');
+        if (hasAmount && !validAmountInput(input.amount)) {
+            throw new Error('amount is an integer in the currency\'s smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06").');
         }
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
         if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
@@ -473,15 +596,21 @@ export class VaultClient {
         const payload = {
             user: input.user,
             merchant: input.merchant,
-            ...(input.amount ? { amount: input.amount } : {}),
             // snake_case on the wire; camelCase is this SDK's convention.
-            ...(hasCents ? { amount_cents: input.amountCents, currency: input.currency } : {}),
+            ...(hasAmount ? { amount: input.amount, currency: input.currency } : {}),
+            ...(input.pageAmount ? { page_amount: input.pageAmount.amount, page_currency: input.pageAmount.currency } : {}),
             psp: rec.psp,
             // The mode this request will be finished in. The API checks it against
             // 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 } : {}),
+            ...(input.executionMode ? { execution_mode: input.executionMode } : {}),
+            ...(input.grantId ? { grant_id: input.grantId } : {}),
+            ...(input.merchantOrigin && !preparation ? { merchant_origin: input.merchantOrigin } : {}),
+            // A prepared checkout already carries the page origin as merchant_origin.
+            ...(preparation
+                ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin }
+                : input.pageOrigin ? { checkout_origin: input.pageOrigin } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
@@ -521,6 +650,20 @@ export class VaultClient {
         if (!created || typeof created.id !== 'string' || !created.id)
             throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_malformed');
         const authorizationId = created.id;
+        let execution = {};
+        let approvalDelivered = false;
+        const deliverApproval = (state) => {
+            if (ownedShop || preparation || approvalDelivered || execution.executionMode === 'autopilot')
+                return;
+            const url = state.approvalUrl ?? state.approval_url;
+            if (typeof url !== 'string' || !url)
+                return;
+            approvalDelivered = true;
+            try {
+                Promise.resolve(input.onApprovalUrl?.(url)).catch(() => { });
+            }
+            catch { /* observer only */ }
+        };
         let failed = false;
         const stopSignal = input.merchantSignal
             ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
@@ -531,12 +674,8 @@ export class VaultClient {
             catch { /* observer only */ }
             if (input.merchantSignal?.aborted)
                 throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-            if (!preparation) {
-                try {
-                    Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
-                }
-                catch { /* approval delivery must not lose an existing authorization */ }
-            }
+            execution = executionMetadata(created, authorizationId);
+            deliverApproval(created);
             while (Date.now() < deadline) {
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
@@ -557,6 +696,11 @@ export class VaultClient {
                 if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
                     throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
                 }
+                execution = executionMetadata(s, authorizationId, execution);
+                if (shopOrder && (s.status === 'submitted_on_device' ||
+                    (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'))))
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'shop_receipt_unconfirmed');
+                deliverApproval(s);
                 const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
                     ? { amountAuthority: s.amount_authority }
                     : {};
@@ -572,7 +716,9 @@ export class VaultClient {
                     if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
                         throw new PaymentOutcomeUnknownError(authorizationId, 'submission_timestamp_missing');
                     }
-                    return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
+                    if (execution.executionMode === 'autopilot')
+                        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
+                    return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority, ...execution };
                 }
                 if (s.status === 'approved') {
                     const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
@@ -583,6 +729,8 @@ export class VaultClient {
                         throw new PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
                     }
                     if (approvedMode === 'cse') {
+                        if (execution.executionMode === 'autopilot')
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
                         const sub = s.substitutions;
                         const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
                             && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
@@ -607,6 +755,7 @@ export class VaultClient {
                                 ...(removeRaw ? { remove: [...removeRaw] } : {}),
                             },
                             ...amountAuthority,
+                            ...execution,
                         };
                     }
                     if (approvedMode !== 'token')
@@ -616,15 +765,29 @@ export class VaultClient {
                         || typeof response.body !== 'string' || !response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
                         throw new PaymentOutcomeUnknownError(authorizationId, 'approved_response_malformed');
                     }
+                    if (shopOrder) {
+                        let receipt;
+                        try {
+                            receipt = parseOwnedShopReceipt(JSON.parse(response.body), shopOrder);
+                        }
+                        catch { /* No raw error or token replay. */ }
+                        if (execution.executionMode !== 'autopilot' || response.status !== 200 || !receipt)
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'shop_receipt_unconfirmed');
+                        // Only canonical receipt fields and our content type enter the page.
+                        response.body = JSON.stringify(receipt);
+                        response.headers = { 'content-type': 'application/json' };
+                    }
                     return {
                         mode: 'token',
                         authorizationId,
+                        ...(shopOrder ? { shopOrderId: shopOrder.order_id } : {}),
                         ...response,
                         amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                        chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : null,
+                        chargedAmount: typeof s.charged_amount === 'number' ? s.charged_amount : null,
                         chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
                         chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
                         ...amountAuthority,
+                        ...execution,
                     };
                 }
                 if (s.status === 'declined') {
@@ -635,6 +798,9 @@ export class VaultClient {
                     }
                     if (s.reason === 'intent_not_confirmable')
                         throw new IntentNotConfirmableError(String(created.id));
+                    if (typeof s.reason === 'string' && PRESET_REFUSAL_REASONS.has(s.reason)) {
+                        throw new PresetRefusedError(String(created.id), s.reason, typeof s.message === 'string' ? s.message : null, presetOf(s.preset), typeof s.rule === 'string' ? s.rule : null, 'pre_replay', attachmentOf(s.attachment), refusalsOf(s.refusals));
+                    }
                     if (s.reason === 'processor_refused') {
                         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);
                     }
@@ -718,6 +884,11 @@ export class VaultClient {
                 return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
             }
             catch (err) {
+                if (err instanceof CheckoutApiError && err.code && err.status === 403 && presetOf(err.details.preset)) {
+                    // A company preset refused this purchase before a row existed.
+                    const d = err.details;
+                    throw new PresetRefusedError(null, err.code, typeof d.message === 'string' ? d.message : null, presetOf(d.preset), typeof d.rule === 'string' ? d.rule : null, 'create', attachmentOf(d.attachment), refusalsOf(d.refusals));
+                }
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
                     const d = err.details;
                     throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create');
@@ -804,6 +975,19 @@ export class VaultClient {
         return this.call(path, { signal });
     }
 }
+function executionMetadata(state, authorizationId, previous = {}) {
+    if (state.execution_mode === undefined)
+        return previous;
+    if (state.execution_mode !== 'user_approval' && state.execution_mode !== 'autopilot')
+        throw new PaymentOutcomeUnknownError(authorizationId, 'execution_mode_unrecognized');
+    if (state.execution_mode === 'user_approval')
+        return { executionMode: 'user_approval' };
+    if (typeof state.grant_id !== 'string' || !/^apg_[A-Za-z0-9_-]{1,128}$/.test(state.grant_id))
+        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_grant_unconfirmed');
+    if (previous.grantId && previous.grantId !== state.grant_id)
+        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_grant_changed');
+    return { executionMode: 'autopilot', grantId: state.grant_id };
+}
 /**
  * Forward only the headers the merchant needs to accept the replay. Everything
  * else (cookies, UA, tracing) is dropped so we transmit as little as possible.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, PresetRefusedError, PRESET_REFUSAL_REASONS, 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, ExecutionMetadata, } from './client.js';
 export { attachToCdp, attachToPlaywright, corsHeadersFor, corsDecision, withCorsHeaders } from './cdp.js';
 export { CheckoutAttachmentError } from './attachment.js';
 export type { CdpLike, AttachOptions, CorsOutcome } from './cdp.js';