@visa/cli 4.1.0-rc.42 → 4.1.0-rc.43

package/dist/checkout-engine/cli-engine.js

@@ -264,6 +264,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     amountMinor,
                     currency: input.currency,
                     browser,
+                    contact: input.contact,
                 }, store);
                 if (prep.status !== 'ready') {
                     await browser.close();

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

@@ -1,6 +1,6 @@
 import type { Page } from 'playwright-core';
 export type FieldSource = 'autocomplete' | 'attr-heuristic' | 'label-text' | 'iframe-psp' | 'type-inference';
-export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
+export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'phone' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
 export declare const ALL_ROLES: FieldRole[];
 export type SelectOption = {
     value: string;

package/dist/checkout-engine/detect.js

@@ -21,6 +21,7 @@ export const ALL_ROLES = [
     'nameFirst',
     'nameLast',
     'email',
+    'phone',
     'oneTimeCode',
     'addressLine1',
     'addressLine2',
@@ -38,6 +39,7 @@ const expMonthRe = /(exp.?month|expmonth|exp_mm|(^|[^a-z])mm([^a-z]|$)|(^|[^a-z]
 const expYearRe = /(exp.?year|expyear|exp_yy|(^|[^a-z])yy(yy)?([^a-z]|$)|(^|[^a-z])year([^a-z]|$)|jahr|annee|(^|[^a-z])ano([^a-z]|$))/;
 const expCombinedRe = /(exp(iry|iration)?(.?date)?|mm.?\/.?yy|mm.?jj|valid.?thru|ablauf|caducidad)/;
 const emailRe = /(e-?mail|correo|courriel)/;
+const phoneRe = /(phone|telephone|mobile|(^|[^a-z])tel([^a-z]|$)|telefono|téléphone)/;
 // One-time verification code (merchant email/SMS OTP). Ordered AFTER cvcRe in
 // attrClassify so a card CVC ("security code"/"card code") still wins — this
 // regex deliberately omits those card phrasings. It also OMITS a bare "code":
@@ -67,6 +69,8 @@ const AUTOCOMPLETE_MAP = {
     'cc-name': 'name',
     name: 'name',
     email: 'email',
+    tel: 'phone',
+    'tel-national': 'phone',
     'one-time-code': 'oneTimeCode',
     'given-name': 'nameFirst',
     'family-name': 'nameLast',
@@ -167,6 +171,8 @@ function attrClassify(text, m) {
     // OTP comes after cvc (checked above) so card CVC still classifies as 'cvc'.
     if (oneTimeCodeRe.test(text))
         return 'oneTimeCode';
+    if (phoneRe.test(text))
+        return 'phone';
     if (postalRe.test(text))
         return 'postalCode';
     if (countryRe.test(text))

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

@@ -1,4 +1,4 @@
-export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'credential-minted' | 'credential-skipped' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
+export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'contact-prefill' | 'credential-minted' | 'credential-skipped' | 'credential-expiry-check' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
 export type EvidenceStep = {
     ts: string;
     type: EvidenceStepType;

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

@@ -5,6 +5,7 @@ import type { Instrument } from './instrument.js';
 import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
+export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutOutcome = 'reviewed-dry-run'
 /** Historical receipt value from the credential-disclosing dry-run. */
@@ -30,6 +31,7 @@ export type PrepareCheckoutOptions = {
     url: string;
     mandate: Mandate;
     browser: Browser;
+    contact?: Contact;
     amountMinor?: number;
     currency?: string;
     debugShotsDir?: string;
@@ -91,8 +93,6 @@ export type SubmitApprovedCheckoutOptions = {
     onChallengeHold?: (signal: string | null) => void;
     resolveEmailOtp?: OtpResolver;
 };
-export declare function minorFromDecimal(text: string): number | null;
-export declare function pageCurrency(text: string): string | null;
 export type PreparedCheckoutSession = {
     checkout: PreparedCheckout;
     context: BrowserContext;

package/dist/checkout-engine/executor.js

@@ -22,6 +22,10 @@ import { checkMandate, checkMandatePreFill } from './mandate.js';
 import { EvidenceLog, maskOtp } from './evidence.js';
 import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
+import { traceHandleFields } from './trace-handles.js';
+import { readGenericPageAmount } from './amount.js';
+import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, } from './adapters/shopify.js';
+export { minorFromDecimal, pageCurrency } from './amount.js';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
 const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
 // Post-submit confirmed/declined/challenge signals live in outcome.ts
@@ -36,92 +40,6 @@ async function settle(page) {
     await page.waitForTimeout(200);
     await page.waitForLoadState('networkidle', { timeout: 1500 }).catch(() => { });
 }
-// Convert a human decimal like "$50.00" to integer minor units without
-// floats. Fail-closed on separator ambiguity: only layouts with exactly one
-// reading are parsed; anything else returns null and the caller refuses. The
-// dangerous direction is UNDER-reading (an EU "1.234,56" read as 1.23 lets an
-// over-cap total pass the gate), so no layout is ever guessed.
-// Only 2-decimal currencies are supported (see pageCurrency's ISO allowlist).
-export function minorFromDecimal(text) {
-    const m = text.match(/\d[\d.,]*/);
-    if (!m)
-        return null;
-    const token = m[0].replace(/[.,]+$/, '');
-    // "1234" — plain integer major units.
-    if (/^\d+$/.test(token))
-        return Number.parseInt(token, 10) * 100;
-    // "1,234.56" — thousands groups of exactly 3 plus a 2-digit decimal.
-    if (/^\d{1,3}(,\d{3})+\.\d{2}$/.test(token)) {
-        const [whole, frac] = token.replace(/,/g, '').split('.');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
-    }
-    // "1.234,56" — the EU mirror: dot thousands, comma decimal.
-    if (/^\d{1,3}(\.\d{3})+,\d{2}$/.test(token)) {
-        const [whole, frac] = token.replace(/\./g, '').split(',');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
-    }
-    // "49.99" / "49.9" — dot decimal. A 3-digit dot group ("1.234") is EU
-    // thousands, not a decimal, so only 1-2 fraction digits qualify.
-    if (/^\d+\.\d{1,2}$/.test(token)) {
-        const [whole, frac] = token.split('.');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
-    }
-    // "49,99" / "49,9" — comma decimal. Unambiguous: a thousands group is
-    // always exactly 3 digits, so a 1-2 digit comma tail can only be a decimal.
-    if (/^\d+,\d{1,2}$/.test(token)) {
-        const [whole, frac] = token.split(',');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
-    }
-    // Everything else ("1,234" thousands-or-3-decimals, "1.2.3", ...) is
-    // ambiguous: refuse rather than guess.
-    return null;
-}
-// Currency stated by the page's total text, when unambiguous. "$" is shared
-// by USD/CAD/AUD/... and never qualifies. The ISO allowlist is 2-decimal
-// currencies only, matching minorFromDecimal's scaling.
-const ISO_CURRENCIES = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'CHF', 'NZD'];
-export function pageCurrency(text) {
-    const iso = text.match(/\b([A-Z]{3})\b/);
-    if (iso && ISO_CURRENCIES.includes(iso[1]))
-        return iso[1];
-    if (text.includes('€'))
-        return 'EUR';
-    if (text.includes('£'))
-        return 'GBP';
-    return null;
-}
-// Read the order total from the page. Prefers an explicit data-total-minor
-// attribute (machine-readable), else parses a labelled total from the page.
-// Either way the currency comes from the element's text, or stays null. A
-// total that is present but ambiguous is 'unreadable' — the executor refuses
-// rather than falling back to the caller amount, because the page is showing
-// the user a number we cannot verify against the mandate.
-async function readPageAmount(page) {
-    const explicitLoc = page.locator('[data-total-minor]').first();
-    if ((await explicitLoc.count().catch(() => 0)) > 0) {
-        const explicit = await explicitLoc.getAttribute('data-total-minor').catch(() => null);
-        if (explicit && /^\d+$/.test(explicit)) {
-            const text = (await explicitLoc.textContent().catch(() => null)) ?? '';
-            return {
-                kind: 'ok',
-                amountMinor: Number.parseInt(explicit, 10),
-                currency: pageCurrency(text),
-                source: 'page-attr',
-            };
-        }
-    }
-    const totalLoc = page.locator('#order-total, .order-total, [data-testid="order-total"]').first();
-    if ((await totalLoc.count().catch(() => 0)) > 0) {
-        const totalText = await totalLoc.textContent().catch(() => null);
-        if (totalText && /\d/.test(totalText)) {
-            const amountMinor = minorFromDecimal(totalText);
-            if (amountMinor == null)
-                return { kind: 'unreadable' };
-            return { kind: 'ok', amountMinor, currency: pageCurrency(totalText), source: 'page-text' };
-        }
-    }
-    return { kind: 'none' };
-}
 async function tryReveal(page, evidence, clicked) {
     // 1) A payment-method radio for card/credit/debit (accordion layouts).
     const radios = page.locator('input[type="radio"]');
@@ -445,8 +363,19 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
         ...(confirmationRef ? { confirmationRef } : {}),
     };
 }
-async function readTransactionFacts(page, opts) {
-    const pageAmount = await readPageAmount(page);
+async function readTransactionFacts(page, opts, phase) {
+    const shopify = await isShopifyCheckoutPage(page);
+    const amountRead = shopify
+        ? phase === 'review'
+            ? await readStableShopifyAmount(page)
+            : await readShopifyAmount(page, true)
+        : await readGenericPageAmount(page);
+    const pageAmount = shopify && amountRead.kind === 'none'
+        ? {
+            kind: 'unreadable',
+            reason: 'Shopify final tax and total summary is not available',
+        }
+        : amountRead;
     const amountMinor = pageAmount.kind === 'ok'
         ? pageAmount.amountMinor
         : pageAmount.kind === 'none'
@@ -475,10 +404,10 @@ async function readTransactionFacts(page, opts) {
             currency,
             source,
             reason: pageAmount.kind === 'unreadable'
-                ? 'page total is displayed but cannot be parsed unambiguously'
+                ? (pageAmount.reason ?? 'page total is displayed but cannot be parsed unambiguously')
                 : 'transaction amount could not be determined',
             detail: pageAmount.kind === 'unreadable'
-                ? 'transaction amount could not be determined (page total present but ambiguous, e.g. separator layout); refusing fail-closed'
+                ? `transaction amount could not be determined (${pageAmount.reason ?? 'page total present but ambiguous'}); refusing fail-closed`
                 : 'transaction amount could not be determined (no readable page total, no amountMinor provided); refusing fail-closed',
         };
     }
@@ -788,7 +717,61 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         }
         // Detection is read-only here. In particular, no adapter fill and no
         // Instrument.getCredential() call can occur before an explicit approval.
-        const detected = await detectFields(page);
+        let detected = await detectFields(page);
+        let adapter = selectAdapter(detected);
+        if (options.contact && adapter.prepareContact) {
+            const preparedContact = await adapter.prepareContact(page, options.contact);
+            for (const field of preparedContact.filled) {
+                evidence.step('contact-prefill', {
+                    role: field.role,
+                    confidence: field.confidence,
+                    source: field.source,
+                    frame: field.frame,
+                    value: field.value,
+                    ok: field.ok,
+                    error: field.error,
+                });
+            }
+            const challenge = await detectShopifyChallenge(page);
+            if (challenge) {
+                evidence.step('outcome', {
+                    outcome: 'action-required',
+                    signal: challenge.signal,
+                    phase: 'contact-prefill',
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('action-required', fields, evidence, requiresAdapter, `Shop Pay verification requires a human before review (${challenge.signal}); no payment credential was requested`),
+                };
+            }
+            if (!preparedContact.ok) {
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('failed', fields, evidence, requiresAdapter, preparedContact.detail ??
+                        'Shopify contact prefill did not complete; no payment credential was requested'),
+                };
+            }
+            await settle(page);
+            const prefillHost = new URL(page.url()).hostname;
+            if (prefillHost !== merchantHost) {
+                const reason = `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
+                evidence.step('mandate-verdict', {
+                    phase: 'contact-prefill',
+                    ok: false,
+                    reason,
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason),
+                };
+            }
+            detected = await detectFields(page);
+            adapter = selectAdapter(detected);
+            evidence.step('adapter-selected', { adapter: adapter.name, phase: 'review' });
+        }
         fields = detected.fields;
         evidence.step('detect', {
             phase: 'review',
@@ -802,7 +785,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
             }
         }
-        const facts = await readTransactionFacts(page, options);
+        const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {
             evidence.step('mandate-verdict', { phase: 'review', ok: false, reason: facts.reason });
@@ -913,7 +896,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, preFill.reason);
         }
-        const approvedFacts = await readTransactionFacts(page, options);
+        const approvedFacts = await readTransactionFacts(page, options, 'approval');
         recordTransactionFacts(evidence, 'approval', approvedFacts);
         if (!approvedFacts.ok) {
             evidence.step('mandate-verdict', {
@@ -987,11 +970,14 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             ...(credential.credentialExpiresAt
                 ? { credentialExpiresAt: credential.credentialExpiresAt }
                 : {}),
+            ...traceHandleFields(credential),
         });
         // Reveal + fill loop: fills whatever is present, then reveals the next
         // surface (card radio / next step) until the card number is filled.
         const clicked = new Set();
         let adapterName = null;
+        let adapterFillOk = true;
+        let adapterFillDetail = null;
         for (let attempt = 0; attempt < 4; attempt++) {
             // A reveal/continue action can navigate between attempts. Never expose
             // the credential to a host other than the one the human reviewed.
@@ -1026,6 +1012,8 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 evidence.step('adapter-selected', { adapter: adapter.name });
             }
             const fill = await adapter.fill(page, detected.fields, credential, opts.contact);
+            adapterFillOk = fill.ok;
+            adapterFillDetail = fill.detail ?? null;
             for (const f of fill.filled) {
                 evidence.step('field-fill', {
                     role: f.role,
@@ -1067,7 +1055,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // Re-run the full gate after fill as well. Contact/shipping fields can
         // change the total; any drift from the approved review refuses before a
         // submit click and requires the caller to prepare a new review.
-        const submitFacts = await readTransactionFacts(page, options);
+        const submitFacts = await readTransactionFacts(page, options, 'pre-submit');
         recordTransactionFacts(evidence, 'pre-submit', submitFacts);
         if (!submitFacts.ok) {
             evidence.step('mandate-verdict', {
@@ -1110,6 +1098,10 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick);
         }
+        if (!adapterFillOk) {
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('failed', state.fields, evidence, requiresAdapter, adapterFillDetail ?? `${adapterName ?? 'checkout'} adapter fill incomplete`);
+        }
         if (missingCredentialRoles.length > 0) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
@@ -1129,6 +1121,30 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // Stripe's submit chain mid-flight (#5879) — see waitForLinkLookupQuiet.
         const linkQuiet = await waitForLinkLookupQuiet(page);
         evidence.step('note', { linkQuiet });
+        // This is deliberately the last await before the irreversible click.
+        // Mint-time validation is not enough: reveal/fill and Link suppression can
+        // consume a short-lived DAVV. Refuse malformed or <60s credentials so an
+        // expiry decline cannot masquerade as a form-fill failure.
+        const credentialExpiresAt = credential.credentialExpiresAt;
+        const expiryMissing = opts.instrument.kind === 'agentic-token' && credentialExpiresAt === undefined;
+        const expiresMs = credentialExpiresAt === undefined ? Number.NaN : Date.parse(credentialExpiresAt);
+        if (expiryMissing ||
+            (credentialExpiresAt !== undefined &&
+                (!Number.isFinite(expiresMs) || expiresMs - Date.now() < 60_000))) {
+            evidence.step('credential-expiry-check', {
+                ok: false,
+                reason: expiryMissing ? 'missing' : 'invalid-or-expiring',
+                ...(credentialExpiresAt !== undefined ? { credentialExpiresAt } : {}),
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('failed', state.fields, evidence, requiresAdapter, 'credential expired before submit; obtain a fresh intent and re-review');
+        }
+        if (credentialExpiresAt !== undefined) {
+            evidence.step('credential-expiry-check', {
+                ok: true,
+                credentialExpiresAt,
+            });
+        }
         evidence.step('submit', { clicked: true, target: submit.desc });
         await submit.click();
         await settle(page);
@@ -1292,7 +1308,7 @@ export async function cancelPreparedCheckout(reviewId, detail = 'checkout cancel
 // explicit prepareCheckout()/submitApprovedCheckout() pair instead.
 export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
     const { instrument, contact, mode, outcomeDeadlineMs, resolveEmailOtp, ...prepareOptions } = opts;
-    const preparation = await prepareCheckout(prepareOptions, store);
+    const preparation = await prepareCheckout({ ...prepareOptions, contact }, store);
     if (preparation.status === 'finished')
         return preparation.result;
     return submitApprovedCheckout(preparation.checkout.review.id, {

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

@@ -6,6 +6,12 @@ export type CardCredential = {
     cardholderName: string;
     /** Dynamic payment credential expiry, distinct from the card expiration. */
     credentialExpiresAt?: string;
+    /**
+     * Non-sensitive, bounded request-correlation handles returned by the mint
+     * route. These are evidence pointers, not card credential material.
+     */
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type InstrumentContext = {
     merchantHost: string;

package/dist/checkout-engine/run-live-fill.js

@@ -341,6 +341,7 @@ try {
         amountMinor,
         currency,
         browser,
+        contact,
         debugShotsDir,
     });
     if (preparation.status === 'finished') {

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;
@@ -23,6 +27,7 @@ export type FilledField = {
 export type FillResult = {
     ok: boolean;
     filled: FilledField[];
+    detail?: string;
 };
 export type OtpRequest = {
     /** ISO watermark captured BEFORE the click that triggers the OTP email. */

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?.();
@@ -144,6 +145,7 @@ 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.

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

@@ -57,6 +57,8 @@ export type VgsPaymentCredential = {
     cryptogramType: string;
     cryptogramValue: string;
     cryptogramExpiresAt?: string;
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
 };
 export type FetchVgsPaymentCredential = (input: {
     tokenId: string;

package/dist/checkout-engine/vgs-live-instrument.js

@@ -1,3 +1,4 @@
+import { traceHandleFields } from './trace-handles.js';
 /**
  * Our fail-closed freshness bound, matching the runner's 15-minute checkout
  * review window — NOT a claim about VGS's actual assurance TTL (unpublished).
@@ -162,13 +163,14 @@ export function validateCredential(value, now = new Date()) {
         (value.expYear === now.getFullYear() && value.expMonth < now.getMonth() + 1)) {
         throw new Error('VGS credential is expired');
     }
-    if (value.cryptogramExpiresAt !== undefined) {
-        const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
-        if (!Number.isFinite(expiresAtMs))
-            throw new Error('VGS credential expiry is invalid');
-        if (expiresAtMs - now.getTime() < 60_000) {
-            throw new Error('VGS credential has less than 60 seconds of validity remaining');
-        }
+    if (value.cryptogramExpiresAt === undefined) {
+        throw new Error('VGS credential expiry is missing');
+    }
+    const expiresAtMs = Date.parse(value.cryptogramExpiresAt);
+    if (!Number.isFinite(expiresAtMs))
+        throw new Error('VGS credential expiry is invalid');
+    if (expiresAtMs - now.getTime() < 60_000) {
+        throw new Error('VGS credential has less than 60 seconds of validity remaining');
     }
 }
 /**
@@ -225,6 +227,7 @@ export class VgsLiveInstrument {
             cvc: value.cryptogramValue,
             cardholderName: this.cardholderName.trim(),
             ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
+            ...traceHandleFields(value),
         };
     }
 }
@@ -284,6 +287,7 @@ export class VgsAssuranceInstrument {
             cvc: value.cryptogramValue,
             cardholderName: this.cardholderName.trim(),
             ...(value.cryptogramExpiresAt ? { credentialExpiresAt: value.cryptogramExpiresAt } : {}),
+            ...traceHandleFields(value),
         };
     }
 }