@visa/cli 4.1.0-rc.24 → 4.1.0-rc.241

package/dist/checkout-engine/receipt.js

@@ -1,11 +1,12 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
 import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
 /**
  * What the operator still owes after this run. Empty for a clean dry-run fill
  * and for a definitive submit outcome whose VIC confirmation posted.
  */
-function reconciliationFor(result, vicConfirmation) {
+function reconciliationFor(result, vicConfirmation, mode) {
     const reasons = [];
     if (submitClickedWithoutConfirmation(result)) {
         reasons.push('the pay control was clicked but no definitive outcome was observed — ' +
@@ -21,7 +22,7 @@ function reconciliationFor(result, vicConfirmation) {
         reasons.push('confirmed without a merchant confirmation reference — ' +
             'record the order number from the merchant dashboard');
     }
-    if (result.outcome === 'action-required') {
+    if (mode === 'submit' && result.outcome === 'action-required') {
         reasons.push('an issuer verification challenge was shown and not completed — ' +
             'finish the purchase manually if still wanted, or confirm with the merchant that no order exists');
     }
@@ -29,23 +30,60 @@ function reconciliationFor(result, vicConfirmation) {
 }
 export function buildReceipt(input) {
     const { result } = input;
+    const reconciliation = reconciliationFor(result, input.vicConfirmation, input.mode);
+    const fallbackAction = input.mode === 'dry-run'
+        ? 'Dry run only — nothing was submitted; safe to run again.'
+        : result.outcome === 'confirmed'
+            ? 'No action needed.'
+            : result.outcome === 'declined'
+                ? 'Review the decline before trying again.'
+                : result.outcome === 'unverified'
+                    ? // Defensive: reconciliationFor() already pushes the richer
+                        // submit-clicked reason for this outcome, so this line is only
+                        // reached if that ever stops firing. It must still not invite a
+                        // retry.
+                        'The charge may have gone through. Confirm with the merchant before retrying.'
+                    : result.outcome === 'partial-fill'
+                        ? // A v2 receipt carries no evidence log, so this line is the only
+                            // place the CAUSE survives — which field refused and why. An
+                            // operator opening this a week later can act on it; "could not
+                            // be filled" alone means reproducing a live merchant to learn
+                            // anything.
+                            `${result.detail ?? 'Nothing was submitted and nothing was charged.'} Safe to try again once the checkout can be filled.`
+                        : 'Review this outcome before retrying.';
+    const recoveryActions = reconciliation.reasons.length > 0 ? reconciliation.reasons : [fallbackAction];
+    const cardLast4 = input.cardLast4 && /^\d{4}$/.test(input.cardLast4) ? input.cardLast4 : null;
+    const checkoutUrl = input.merchant.url && KNOWN_MERCHANT_IDENTITIES[input.merchant.url] ? input.merchant.url : null;
+    const networkConfirmation = input.vicConfirmation?.posted === true ? input.vicConfirmation.transactionStatus : null;
+    const capability = result.failureCode || result.requiresAdapter.length > 0
+        ? {
+            failureCode: result.failureCode ?? null,
+            detectedRoles: Object.keys(result.fields).sort(),
+            requiresAdapter: [...result.requiresAdapter].sort(),
+        }
+        : null;
     return {
-        schema: 'checkout-agent-receipt/v1',
+        schema: 'checkout-agent-receipt/v2',
         recordedAt: (input.recordedAt ?? new Date()).toISOString(),
-        mode: input.mode,
-        reviewId: input.reviewId,
-        merchant: { name: input.merchant.name, host: input.merchant.host },
+        ...(input.observationId ? { observationId: input.observationId } : {}),
+        ...(input.observationId && input.reviewId === null ? { phase: 'review' } : {}),
+        merchant: { name: input.merchant.name, host: input.merchant.host, checkoutUrl },
         transaction: input.transaction,
         outcome: result.outcome,
-        detail: result.detail ?? null,
-        confirmationRef: result.confirmationRef ?? null,
-        vicConfirmation: input.vicConfirmation,
-        credentialLifecycle: result.credentialLifecycle,
-        credentialTiming: result.credentialTiming,
-        detectedRoles: Object.keys(result.fields),
-        requiresAdapter: [...result.requiresAdapter],
-        reconciliation: reconciliationFor(result, input.vicConfirmation),
-        evidence: result.evidence.toObject(),
+        agent: input.agentName ? { name: input.agentName } : null,
+        rail: { type: 'card', cardLast4 },
+        network: { confirmation: networkConfirmation },
+        ...(capability ? { capability } : {}),
+        receiptId: input.reviewId,
+        reference: result.confirmationRef ?? null,
+        recovery: {
+            required: reconciliation.required,
+            // A clean dry-run did not submit anything, so repeating inspection is
+            // safe. Every submit outcome requires either no retry or owner review.
+            retrySafe: input.mode === 'dry-run' && !reconciliation.required,
+            action: recoveryActions[0],
+            actions: recoveryActions,
+        },
     };
 }
 function luhnValid(digits) {
@@ -88,7 +126,8 @@ export function serializeReceipt(receipt) {
 }
 export function receiptFileName(receipt) {
     const ts = receipt.recordedAt.replace(/[:.]/g, '-');
-    const review = (receipt.reviewId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
+    const receiptId = receipt.schema === 'checkout-agent-receipt/v1' ? receipt.reviewId : receipt.receiptId;
+    const review = (receiptId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
     return `receipt-${ts}-${review || 'no-review'}.json`;
 }
 /**

package/dist/checkout-engine/trace-handles.d.ts

@@ -0,0 +1,8 @@
+export declare function safeTraceHandle(value: unknown): string | undefined;
+export declare function traceHandleFields(value: {
+    vgsTraceId?: unknown;
+    networkCorrelationId?: unknown;
+}): {
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
+};

package/dist/checkout-engine/trace-handles.js

@@ -0,0 +1,12 @@
+const SAFE_TRACE_HANDLE_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+export function safeTraceHandle(value) {
+    return typeof value === 'string' && SAFE_TRACE_HANDLE_RE.test(value) ? value : undefined;
+}
+export function traceHandleFields(value) {
+    const vgsTraceId = safeTraceHandle(value.vgsTraceId);
+    const networkCorrelationId = safeTraceHandle(value.networkCorrelationId);
+    return {
+        ...(vgsTraceId ? { vgsTraceId } : {}),
+        ...(networkCorrelationId ? { networkCorrelationId } : {}),
+    };
+}

package/dist/checkout-engine/types.d.ts

@@ -1,5 +1,4 @@
-export type Contact = {
-    email?: string;
+export type PostalAddress = {
     firstName?: string;
     lastName?: string;
     fullName?: string;
@@ -10,6 +9,11 @@ export type Contact = {
     postalCode?: string;
     country?: string;
 };
+export type Contact = PostalAddress & {
+    email?: string;
+    phone?: string;
+    billingAddress?: PostalAddress;
+};
 export type FilledField = {
     role: string;
     locator: string;
@@ -19,8 +23,30 @@ export type FilledField = {
     value: string;
     ok: boolean;
     error?: string;
+    /**
+     * The detected node was gone by the time this field's turn came (the merchant
+     * re-mounted that part of the form mid-fill) and a fresh detection pass was
+     * used to find it again. Worth surfacing: a merchant that re-mounts is a
+     * merchant whose fills are order-sensitive, which is the first thing to know
+     * when one of them later refuses.
+     */
+    relocated?: boolean;
 };
 export type FillResult = {
     ok: boolean;
     filled: FilledField[];
+    detail?: string;
+};
+export type OtpRequest = {
+    /** ISO watermark captured BEFORE the click that triggers the OTP email. */
+    after: string;
+    /** The merchant hostname; the sender's registrable domain must match it. */
+    merchantHost: string;
+};
+export type OtpResolution = {
+    /** The single-use code. The executor fills it exactly once; never retried. */
+    code: string;
+    /** The sender's registrable domain — a trust signal, safe to log (no PII). */
+    fromDomain: string;
 };
+export type OtpResolver = (req: OtpRequest) => Promise<OtpResolution | null>;

package/dist/checkout-engine/unresolved-charges.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export declare const MAY_HAVE_CHARGED_OUTCOMES: ReadonlySet<string>;
+/** One local attempt that may have taken money and was never resolved. */
+export type UnresolvedCharge = {
+    recordedAt: string;
+    host: string;
+    amount: string;
+    amountMinor: number;
+    currency: string;
+    outcome: string;
+    /** Receipt file basename, so a caller can name the evidence a human must check. */
+    receiptFile: string;
+};
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export declare function readUnresolvedCharges(receiptDir?: string): Promise<UnresolvedCharge[]>;

package/dist/checkout-engine/unresolved-charges.js

@@ -0,0 +1,134 @@
+// "Did this device already submit this exact purchase?", read back from the
+// checkout receipts on disk.
+//
+// The engine now reports a submitted-but-unobserved checkout as `unverified`
+// instead of `failed`, and pay_merchant tells the caller not to retry it. This
+// module is the belt to that suspenders: even a caller that ignores the words
+// can be stopped, because the previous attempt left a receipt.
+//
+// It answers one question — which local receipts record an attempt that MAY
+// HAVE CHARGED and was never resolved — and deliberately answers nothing else.
+// The matching (same merchant, same amount, recent enough) lives in the caller,
+// which owns the policy; this side owns only the read.
+//
+// Sibling of confirmed-merchants.ts and loaded through the same seam: it
+// imports node built-ins and types only, so reading receipts never pulls
+// playwright into the CLI process.
+//
+// Reading is best-effort by construction. The receipts directory is an operator
+// artifact that anything on the box can touch, so an unreadable or malformed
+// file is skipped rather than failing the whole read.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export const MAY_HAVE_CHARGED_OUTCOMES = new Set([
+    'unverified',
+    'action-required',
+]);
+/**
+ * Every field this module reads, validated. Deliberately permissive about
+ * everything else: older and newer engines only have to carry these.
+ *
+ * Both receipt schemas expose all of them at the same paths, so unlike
+ * confirmed-merchants.ts there is nothing here that needs a per-schema branch.
+ */
+function parseUnresolved(json, receiptFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const receipt = parsed;
+    if (receipt.schema !== 'checkout-agent-receipt/v1' &&
+        receipt.schema !== 'checkout-agent-receipt/v2') {
+        return null;
+    }
+    // Terminal review observations are useful capability evidence, but no pay
+    // control, credential, or submission exists yet. They must never poison the
+    // double-charge ledger even when the observed page showed a Shop Pay or 3DS
+    // action-required surface.
+    if (receipt.schema === 'checkout-agent-receipt/v2' &&
+        (receipt.phase === 'review' ||
+            (typeof receipt.observationId === 'string' && receipt.receiptId === null))) {
+        return null;
+    }
+    if (typeof receipt.outcome !== 'string' || !MAY_HAVE_CHARGED_OUTCOMES.has(receipt.outcome)) {
+        return null;
+    }
+    if (typeof receipt.recordedAt !== 'string' || Number.isNaN(Date.parse(receipt.recordedAt))) {
+        return null;
+    }
+    const host = receipt.merchant?.host;
+    if (typeof host !== 'string' || host.length === 0)
+        return null;
+    const transaction = receipt.transaction;
+    if (typeof transaction?.amount !== 'string')
+        return null;
+    if (typeof transaction.currency !== 'string')
+        return null;
+    // A receipt whose amount cannot be compared cannot gate a retry on amount, and
+    // a guard that silently matched every amount would be worse than none.
+    if (typeof transaction.amountMinor !== 'number' || !Number.isFinite(transaction.amountMinor)) {
+        return null;
+    }
+    return {
+        recordedAt: receipt.recordedAt,
+        host,
+        amount: transaction.amount,
+        amountMinor: transaction.amountMinor,
+        currency: transaction.currency,
+        outcome: receipt.outcome,
+        receiptFile,
+    };
+}
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export async function readUnresolvedCharges(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const charges = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const charge = parseUnresolved(raw, name);
+        if (charge)
+            charges.push(charge);
+    }
+    charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    return charges;
+}

package/dist/checkout-engine/vgs-gateway/server-mint-client.d.ts

@@ -6,15 +6,67 @@ export type ServerMintDeps = {
     sleep?: (ms: number) => Promise<void>;
     env?: NodeJS.ProcessEnv;
 };
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export declare function merchantOrigin(url: string): string;
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export declare class ServerCryptogramRefusedError extends Error {
+    readonly status: number;
+    readonly terminal: true;
+    constructor(status: number, detail: string);
+}
+/**
+ * Optional mandate override for serverCreateIntent. Absent → the default
+ * intent shape (cap = ceil(amount)+10 min 25, quantity 1, 30-day window).
+ * Present → the card-mandate (budget) layer sets a CEILING decline threshold
+ * and a multi-draw quantity so one passkey approves a spend ceiling and later
+ * draws pull cryptograms under it without a fresh tap. Whether the network
+ * honors a ceiling-scoped assurance across multiple sub-amount draws is
+ * UNPROVEN — see packages/checkout-engine/src/mandate/.
+ */
+export type ServerIntentMandateOverride = {
+    /** Wire decline-threshold amount (major-unit decimal string), e.g. "500.00". */
+    declineThresholdAmount?: string;
+    /** Number of draws the intent may fulfil (VGS mandate `quantity`). */
+    quantity?: number;
+    /** ISO 8601 mandate validity end. */
+    effectiveUntil?: string;
+    /** Human-readable consumer prompt describing the ceiling grant. */
+    consumerPrompt?: string;
+};
 /**
  * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
  * credential and calls the gateway; we send the same mandate shape the local
- * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999).
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
  */
 export declare function serverCreateIntent(base: string, mintToken: string, input: {
     tokenId: string;
     assuranceData: unknown;
     transaction: VgsCheckoutTarget;
+    mandate?: ServerIntentMandateOverride;
 }, deps?: ServerMintDeps): Promise<{
     intentId: string;
     status: string | null;

package/dist/checkout-engine/vgs-gateway/server-mint-client.js

@@ -11,6 +11,7 @@
 // Request derivation here mirrors ../fetch-credential.mjs EXACTLY (mandate cap,
 // consumer prompt, PENDING retry cadence) — the only change is the transport:
 // verify-web routes + Bearer mint token, never the VGS gateway + VGS secret.
+import { traceHandleFields } from '../trace-handles.js';
 const defaultSleep = (ms) => new Promise((r) => {
     const t = setTimeout(r, ms);
     t.unref?.();
@@ -21,10 +22,62 @@ function stripTrailingSlashes(value) {
         out = out.slice(0, -1);
     return out;
 }
+/**
+ * The merchant ORIGIN (scheme + host) — not the full checkout URL. A merchant's
+ * identity is its origin; a real checkout URL can carry hundreds of chars of
+ * campaign/tracking query params. Confirmed live: an oversized `merchantUrl`
+ * (a ~280-char Wikimedia donation URL) makes the cryptogram mint fail downstream
+ * with a vague `502 "card network could not complete"`, while the same merchant
+ * with a trimmed URL mints fine. Sending the origin is both correct (that IS the
+ * merchant) and safely bounded. Falls back to the raw value if it does not parse
+ * — the mint must never throw here.
+ */
+export function merchantOrigin(url) {
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * A definitive refusal from the cryptogram mint route — the request will not
+ * succeed if retried unchanged.
+ *
+ * `terminal` is the load-bearing field. Draw terminality used to be decided by
+ * regex over the error MESSAGE, which made it hostage to text nobody controls:
+ * this client now interpolates the provider's own `upstream_codes` into the
+ * message for diagnosability, and a provider identifier such as
+ * `request_timeout` would match the transient matcher's unanchored
+ * `tim(e|ed)-out` alternative — flipping a permanent 422 back to "transient",
+ * skipping markUnhonored, and stranding the mandate in the exact retry-forever
+ * loop this whole change exists to kill. Terminality is therefore carried
+ * structurally, and consumers must consult it BEFORE any message matching.
+ */
+export class ServerCryptogramRefusedError extends Error {
+    status;
+    terminal = true;
+    constructor(status, detail) {
+        super(`server cryptogram refused (${status}): ${detail}`);
+        this.name = 'ServerCryptogramRefusedError';
+        this.status = status;
+    }
+}
 /** Read a stable, non-secret error message from a route's JSON body. */
 async function routeError(res) {
     const doc = (await res.json().catch(() => null));
-    return doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    const base = doc?.error || doc?.error_code || `HTTP ${res.status}`;
+    // Carry the provider's own status and rejected-attribute identifiers into the
+    // message when the route reflected them. Without this the operator sees only
+    // our status and has to go log-diving to learn WHICH field the gateway
+    // objected to — the gap that left a live create_intent 422 undiagnosable.
+    const parts = [];
+    if (typeof doc?.upstream_status === 'number')
+        parts.push(`upstream_status=${doc.upstream_status}`);
+    if (Array.isArray(doc?.upstream_codes) && doc.upstream_codes.length > 0) {
+        parts.push(`upstream_codes=${doc.upstream_codes.join(',')}`);
+    }
+    return parts.length > 0 ? `${base} [${parts.join(' ')}]` : base;
 }
 function bearer(mintToken) {
     return { 'content-type': 'application/json', authorization: `Bearer ${mintToken}` };
@@ -32,29 +85,37 @@ function bearer(mintToken) {
 /**
  * Create a fresh intent via POST {base}/api/vgs/intent. The server holds the VGS
  * credential and calls the gateway; we send the same mandate shape the local
- * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999).
+ * path built (cap = ceil(amount)+10, min 25; merchant category Retail/5999) —
+ * unless `input.mandate` overrides the threshold/quantity/window for the
+ * card-mandate (budget) layer.
  */
 export async function serverCreateIntent(base, mintToken, input, deps = {}) {
     const fetchImpl = deps.fetchImpl ?? fetch;
     const { tokenId, assuranceData, transaction: t } = input;
-    const cap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const override = input.mandate ?? {};
+    const defaultCap = Math.max(Math.ceil(Number(t.transactionAmount) || 0) + 10, 25);
+    const declineThresholdAmount = override.declineThresholdAmount ?? String(defaultCap);
+    const quantity = override.quantity ?? 1;
+    const effectiveUntil = override.effectiveUntil ?? new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString();
+    const consumerPrompt = override.consumerPrompt ??
+        `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`;
     const res = await fetchImpl(`${stripTrailingSlashes(base)}/api/vgs/intent`, {
         method: 'POST',
         headers: bearer(mintToken),
         body: JSON.stringify({
             tokenId,
-            consumerPrompt: `Buy an item from ${t.merchantName} for ${t.transactionCurrencyCode.toUpperCase()} ${t.transactionAmount}`,
+            consumerPrompt,
             assuranceData,
             mandates: [
                 {
                     description: `Purchase at ${t.merchantName}`,
-                    declineThresholdAmount: String(cap),
+                    declineThresholdAmount,
                     declineThresholdCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
-                    effectiveUntil: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+                    effectiveUntil,
                     merchantCategory: 'Retail',
                     merchantCategoryCode: '5999',
                     preferredMerchantName: t.merchantName,
-                    quantity: 1,
+                    quantity,
                 },
             ],
         }),
@@ -89,7 +150,9 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
         intentId,
         transaction: {
             merchantName: t.merchantName,
-            merchantUrl: t.merchantUrl,
+            // Send the merchant ORIGIN, not the full (possibly huge) checkout URL — an
+            // oversized merchantUrl makes the downstream cryptogram mint 502 (proven live).
+            merchantUrl: merchantOrigin(t.merchantUrl),
             merchantCountryCode: t.merchantCountryCode,
             transactionAmount: t.transactionAmount,
             transactionCurrencyCode: t.transactionCurrencyCode.toUpperCase(),
@@ -116,11 +179,16 @@ export async function serverFetchCryptogram(base, mintToken, input, deps = {}) {
                 ...(typeof c.cryptogramExpiresAt === 'string'
                     ? { cryptogramExpiresAt: c.cryptogramExpiresAt }
                     : {}),
+                ...traceHandleFields(c),
             };
         }
         // A 4xx (bad request / binding refusal / auth) is terminal — never retry it.
-        if (res.status >= 400 && res.status < 500) {
-            throw new Error(`server cryptogram refused (${res.status}): ${await routeError(res)}`);
+        // 429 is the sole exception: it is an explicitly retryable 4xx, and treating
+        // it as terminal would let a transient rate limit permanently disable a
+        // healthy mandate. The route maps upstream rate limits to 503 today, so this
+        // is a guard against a future emitter, not a live path.
+        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            throw new ServerCryptogramRefusedError(res.status, await routeError(res));
         }
         lastError = `${res.status}: ${await routeError(res)}`;
         if (attempt < attempts)

package/dist/checkout-engine/vgs-live-instrument.d.ts

@@ -42,6 +42,15 @@ export type PurchaseAssurance = {
     transactionAmount: string;
     /** ISO 4217 currency the ceremony was scoped to. */
     transactionCurrencyCode: string;
+    /**
+     * True iff the approval server marked this token passkey-exempt ('otp'
+     * cardholder ID&V / 'none' — verified against the owner's account card
+     * record at complete-time): no ceremony ran, `assuranceData` is null by
+     * design, and the intent is minted without it (the signed mint token
+     * carries the same exemption for the server's own check). Absent/false →
+     * assuranceData is REQUIRED, exactly the historical contract.
+     */
+    assuranceExempt?: boolean;
 };
 /**
  * Our fail-closed freshness bound, matching the runner's 15-minute checkout
@@ -57,6 +66,8 @@ export type VgsPaymentCredential = {
     cryptogramType: string;
     cryptogramValue: string;
     cryptogramExpiresAt?: string;
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type FetchVgsPaymentCredential = (input: {
     tokenId: string;
@@ -69,20 +80,39 @@ export type FetchVgsPaymentCredential = (input: {
         transactionCurrencyCode: string;
     };
 }) => Promise<VgsPaymentCredential>;
-export type MintFreshVgsPaymentCredential = (input: {
-    tokenId: string;
-    assuranceData: unknown;
-    transaction: VgsCheckoutTarget;
-}) => Promise<{
-    payment: VgsPaymentCredential;
-    intentId: string;
-}>;
 /** The (token, intent) pair a VIC confirmation is posted against. */
 export type VicConfirmationTarget = {
     tokenId: string;
     intentId: string;
 };
 export declare function decimalToMinor(value: unknown): number | null;
+/**
+ * Currencies whose minor unit is 1/100 of the major unit (2 decimal places).
+ * minorToDecimal's /100 + pad-to-2 rendering is ONLY correct for these. The
+ * card mandate path accepts any 3-letter ISO code, so a 0- or 3-decimal
+ * currency (JPY, BHD, …) would otherwise be emitted with a wrong wire amount.
+ * We only support USD/USDC today; extend deliberately (and fix the exponent)
+ * before adding any non-2-decimal currency.
+ *
+ * NOTE (scanner FP pre-empt): this is a CLIENT-SIDE currency-exponent lookup for
+ * rendering a wire amount in @visa/checkout-engine — it is NOT the cross-store
+ * `PAYMENT_CURRENCIES` enum governed by apps/auth/src/shared-validators.ts, and
+ * this package cannot import from apps/auth (no dependency edge). It intentionally
+ * does not mirror that enum's membership; do not "reconcile" the two.
+ */
+export declare const TWO_DECIMAL_CURRENCIES: Set<string>;
+/**
+ * Inverse of decimalToMinor: render integer minor units as a major-unit decimal
+ * string ("D.DD") for the VGS wire (e.g. a ceiling of 50000 minor → "500.00").
+ * Integer-only; never floating-point money. Throws on a non-integer/negative so
+ * a bad accounting value cannot silently reach the network.
+ *
+ * The /100 + pad-to-2 rendering assumes a 2-decimal (exponent-2) currency. Pass
+ * `currencyCode` on any path that accepts arbitrary currencies (the mandate
+ * path) and it REFUSES a non-2-decimal currency rather than emit a wrong wire
+ * amount. Omit it only where the currency is already known to be USD/USDC.
+ */
+export declare function minorToDecimal(minor: number, currencyCode?: string): string;
 /**
  * Refuse to mint an intent unless the assurance is fresh and its declared
  * scope matches the checkout target exactly. `now` is injectable so the
@@ -112,30 +142,3 @@ export declare class VgsLiveInstrument implements Instrument {
     confirmationTarget(): VicConfirmationTarget | null;
     getCredential(ctx: InstrumentContext): Promise<CardCredential>;
 }
-/**
- * Consumes #5614's claimed CLI enrollment artifact (for the tokenId) plus a
- * FRESH purchase-scoped assurance, and creates a fresh, transaction-scoped VIC
- * intent + credential after checkout approval. This is the production-shaped
- * bridge; unlike VgsLiveInstrument it never needs a pre-created intent ID.
- *
- * The enrollment artifact's stored assuranceData is deliberately never sent:
- * replaying it makes intent creation succeed (HTTP 201) while the cryptogram
- * deterministically never completes — the #5709 dead end. Purchase
- * authorization is the fresh, merchant+amount+currency-scoped assurance,
- * validated against the checkout target BEFORE any intent is minted so a
- * doomed intent is never created.
- */
-export declare class VgsAssuranceInstrument implements Instrument {
-    private readonly enrollment;
-    private readonly purchase;
-    private readonly target;
-    private readonly cardholderName;
-    private readonly mintCredential;
-    readonly kind: "agentic-token";
-    private used;
-    private minted;
-    constructor(enrollment: CliAgentCredential, purchase: PurchaseAssurance, target: VgsCheckoutTarget, cardholderName: string, mintCredential: MintFreshVgsPaymentCredential);
-    /** See VgsLiveInstrument.confirmationTarget — same contract. */
-    confirmationTarget(): VicConfirmationTarget | null;
-    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
-}