@agent-cards/checkout 0.18.0 → 0.19.0

package/dist/preflight-schemas.json

@@ -463,6 +463,9 @@
                 "dlocal-smart-card-fields",
                 "mercado-pago-secure-fields-frame",
                 "mercado-pago-checkout-pro-card-form",
+                "fiserv-commercehub-payment-fields",
+                "fiserv-commercehub-checkout-script",
+                "fiserv-secure-data-capture-frame",
                 "square-web-sdk-sandbox",
                 "paysafe-js-test",
                 "worldpay-checkout-sdk-try",
@@ -476,7 +479,10 @@
                 "adyen-secured-fields-live-au",
                 "adyen-secured-fields-live-apse",
                 "adyen-secured-fields-live-in",
-                "adyen-secured-fields-live-nea"
+                "adyen-secured-fields-live-nea",
+                "fiserv-commercehub-payment-fields-cert",
+                "fiserv-commercehub-checkout-script-cert",
+                "fiserv-secure-data-capture-frame-cert"
               ]
             },
             "kind": {
@@ -983,6 +989,9 @@
                       "dlocal-smart-card-fields",
                       "mercado-pago-secure-fields-frame",
                       "mercado-pago-checkout-pro-card-form",
+                      "fiserv-commercehub-payment-fields",
+                      "fiserv-commercehub-checkout-script",
+                      "fiserv-secure-data-capture-frame",
                       "square-web-sdk-sandbox",
                       "paysafe-js-test",
                       "worldpay-checkout-sdk-try",
@@ -996,7 +1005,10 @@
                       "adyen-secured-fields-live-au",
                       "adyen-secured-fields-live-apse",
                       "adyen-secured-fields-live-in",
-                      "adyen-secured-fields-live-nea"
+                      "adyen-secured-fields-live-nea",
+                      "fiserv-commercehub-payment-fields-cert",
+                      "fiserv-commercehub-checkout-script-cert",
+                      "fiserv-secure-data-capture-frame-cert"
                     ]
                   },
                   "kind": {

package/dist/preflight.generated.js

@@ -1,5 +1,5 @@
 // Generated from @agent-cards/payment-core. Do not edit.
-// source-sha256: 47959768c673f160be4b35fd7cd406aebce431e666963f46a2c9c95125906456
+// source-sha256: 7c76900599ba4ac29a8d1ca541170591ddae58d35c78560e5d37562e0050534a
 import { CHECKOUT_PREFLIGHT_CAPABILITIES } from './preflight-capabilities.generated.js';
 /** Advisory page discovery. These rules never admit a payment destination. */
 export const CHECKOUT_PREFLIGHT_VERSION = '1';
@@ -49,6 +49,16 @@ RULES.push({ id: 'tranzila-terminal-hosted-page', psp: 'tranzila', kinds: ['docu
     sources: [documented('https://docs.dlocal.com/docs/set-up-smart-fields'), observed('dlocal-smart-fields-6.8.3')] }, { id: 'mercado-pago-secure-fields-frame', psp: 'mercado_pago', kinds: ['frame', 'iframe', 'document'], hostname: /^secure-fields\.mercadopago\.com$/, pathname: /^\/$/, origin: 'https://secure-fields.mercadopago.com', path_pattern: '/',
     sources: [documented('https://sdk.mercadopago.com/js/v2'), observed('mercado-pago-secure-fields-frames')] }, { id: 'mercado-pago-checkout-pro-card-form', psp: 'mercado_pago', kinds: ['document', 'frame', 'iframe'], hostname: /^www\.mercadopago\.com\.ar$/, pathname: /^\/checkout\/v1\/payment\/redirect\/[^/]+\/card-form\/?$/, origin: 'https://www.mercadopago.com.ar', path_pattern: '/checkout/v1/payment/redirect/:preference/card-form/',
     sources: [documented('https://www.mercadopago.com.ar/developers/es/docs/checkout-pro/landing'), observed('mercado-pago-checkout-pro-guest-card-form')] });
+// Fiserv Commerce Hub, read 2026-09-23 from Home Depot's OrangePay frame and Fiserv's
+// docs: payment-fields.js renders one Secure Data Capture iframe per card field, and
+// the Checkout JS SDK is Commerce Hub's other browser entry. Fiserv ships dark (its
+// definition names a capability), so the bundled catalog declares no support for it:
+// these assets identify fiserv and the result stays unknown.
+const fiservSource = (reference) => ({ kind: 'primary_source', reference, reviewed_on: '2026-09-23' });
+RULES.push({ id: 'fiserv-commercehub-payment-fields', psp: 'fiserv', kinds: ['script'], hostname: /^commercehub-checkout\.fiservapps\.com$/, pathname: /^\/sdk\/[0-9]+\.[0-9]+\.[0-9]+\/payment-fields\.js$/, origin: 'https://commercehub-checkout.fiservapps.com', path_pattern: '/sdk/:version/payment-fields.js',
+    sources: [fiservSource('https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js'), fiservSource('https://orangepay-ecommerce.hdpayments.homedepot.com/env.js')] }, { id: 'fiserv-commercehub-checkout-script', psp: 'fiserv', kinds: ['script'], hostname: /^commercehub-checkout\.fiservapps\.com$/, pathname: /^\/sdk\/[0-9]+\.[0-9]+\.[0-9]+\/checkout\.js$/, origin: 'https://commercehub-checkout.fiservapps.com', path_pattern: '/sdk/:version/checkout.js',
+    sources: [fiservSource('https://developer.fiserv.com/product/CommerceHub/docs/Online-Commerce/Integration-Options/Hosted-Checkout/Hosted-Checkout-Version-Release')] }, { id: 'fiserv-secure-data-capture-frame', psp: 'fiserv', kinds: ['frame', 'iframe', 'document'], hostname: /^commercehub-secure-data-capture\.fiservapps\.com$/, pathname: /^\/sdk-secure\/[0-9]+\.[0-9]+\.[0-9]+\/iframe\.html$/, origin: 'https://commercehub-secure-data-capture.fiservapps.com', path_pattern: '/sdk-secure/:version/iframe.html',
+    sources: [fiservSource('https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js'), fiservSource('https://commercehub-secure-data-capture.fiservapps.com/sdk-secure/3.8.14/iframe.html')] });
 // Keep sandbox evidence truthful instead of labelling it with a production origin.
 for (const [baseId, suffix, hostname, origin] of [
     ['square-web-sdk', 'sandbox', /^sandbox\.web\.squarecdn\.com$/, 'https://sandbox.web.squarecdn.com'],
@@ -66,6 +76,10 @@ for (const [baseId, suffix, hostname, origin] of [
     ['adyen-secured-fields-live', 'apse', /^checkoutshopper-live-apse\.adyen\.com$/, 'https://checkoutshopper-live-apse.adyen.com'],
     ['adyen-secured-fields-live', 'in', /^checkoutshopper-live-in\.adyen\.com$/, 'https://checkoutshopper-live-in.adyen.com'],
     ['adyen-secured-fields-live', 'nea', /^checkoutshopper-live-nea\.adyen\.com$/, 'https://checkoutshopper-live-nea.adyen.com'],
+    // Commerce Hub's "Sandbox and Cert" environment (payment-fields.js 3.8.14 environment table).
+    ['fiserv-commercehub-payment-fields', 'cert', /^commercehub-checkout-cert\.fiservapps\.com$/, 'https://commercehub-checkout-cert.fiservapps.com'],
+    ['fiserv-commercehub-checkout-script', 'cert', /^commercehub-checkout-cert\.fiservapps\.com$/, 'https://commercehub-checkout-cert.fiservapps.com'],
+    ['fiserv-secure-data-capture-frame', 'cert', /^commercehub-secure-data-capture-cert\.fiservapps\.com$/, 'https://commercehub-secure-data-capture-cert.fiservapps.com'],
 ]) {
     RULES.push({ ...RULES.find(rule => rule.id === baseId), id: `${baseId}-${suffix}`, hostname, origin });
 }

package/dist/preparation.d.ts

@@ -19,6 +19,13 @@ export declare class PreparationGate {
     assertDocument(): Promise<void>;
     private readDocument;
     isEngaged(): boolean;
+    /**
+     * A card request that only a prepared checkout may pay (an Adyen merchant
+     * profile's, or a Fiserv card capture, pre-claim.ts) arrived with no
+     * preparation and was refused. Like claim() on an unused gate, a later
+     * prepare() is then refused too.
+     */
+    observeUnprepared(): void;
     retireUnboundClaim(): void;
     /** A bound native request has its own cancellation/unknown-outcome machinery. */
     invalidate(reason: string): void;

package/dist/preparation.js

@@ -1,6 +1,6 @@
 import { CheckoutPreparationError } from './client.js';
 import { validAmountInput } from './client.js';
-import { matchesPreparedRequest, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
+import { matchesPreparation, validPreparationEnvironment, preparationEndpoint } from './prepared-processor.js';
 /** A local, one-use rendezvous. It never starts or retries a merchant request. */
 export class PreparationGate {
     opts;
@@ -39,9 +39,25 @@ export class PreparationGate {
         try {
             if (!options || !validPreparationEnvironment(options.psp, options.environment))
                 throw new CheckoutPreparationError(null, 'unsupported_processor');
-            const tokenizer = preparationEndpoint(options.psp, options.environment);
-            if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
-                throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
+            // A Fiserv checkout's merchantProfile names a key pin, which prepareCheckout checks: its
+            // capture endpoint is checked below like any processor-hosted checkout's.
+            if (options.merchantProfile !== undefined && options.psp !== 'fiserv') {
+                // An Adyen merchant's own endpoint: a profile this build reviewed, which
+                // this attachment pauses, and one Agentcard turned on for this client.
+                const profile = typeof this.opts.vault.merchantProfile === 'function' && typeof options.merchantProfile === 'string'
+                    ? this.opts.vault.merchantProfile(options.merchantProfile) : null;
+                if (options.psp !== 'adyen')
+                    throw new CheckoutPreparationError(null, 'unsupported_processor');
+                if (!profile)
+                    throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
+                if (profile.status !== 'enabled')
+                    throw new CheckoutPreparationError(null, 'unsupported_checkout');
+            }
+            else {
+                const tokenizer = preparationEndpoint(options.psp, options.environment);
+                if (!this.opts.vault.isCardRequest(tokenizer, 'POST'))
+                    throw new CheckoutPreparationError(null, 'processor_interception_unavailable');
+            }
             if (!validAmountInput(this.opts.amount) || this.opts.amount === 0 || !/^[a-z]{3}$/i.test(this.opts.currency ?? ''))
                 throw new CheckoutPreparationError(null, 'amount_required');
             if (signal.aborted)
@@ -66,7 +82,9 @@ export class PreparationGate {
                 },
             });
             this.prepared = prepared;
-            if (prepared.psp !== options.psp || prepared.environment !== options.environment)
+            // A Fiserv preparation also names the key pin the cardholder approves (merchantProfile).
+            if (prepared.psp !== options.psp || prepared.environment !== options.environment
+                || prepared.merchantProfile !== options.merchantProfile)
                 throw new CheckoutPreparationError(prepared.id, 'checkout_changed');
             if (signal.aborted || this.state !== 'preparing') {
                 void this.cancelThenObserve(prepared.id, 'cancelled');
@@ -101,7 +119,9 @@ export class PreparationGate {
             throw new CheckoutPreparationError(this.prepared?.id ?? null, 'already_used_or_unavailable');
         }
         const prepared = this.prepared;
-        if (Date.parse(prepared.expiresAt) <= Date.now() || !matchesPreparedRequest(prepared.psp, prepared.environment, requestUrl, 'POST', requestBody, requestHeaders)) {
+        // A merchant-hosted preparation claims only its profile's reviewed card request.
+        // A Fiserv preparation claims only a capture under the key pin it names.
+        if (Date.parse(prepared.expiresAt) <= Date.now() || !matchesPreparation(prepared, requestUrl, 'POST', requestBody, requestHeaders)) {
             const reason = Date.parse(prepared.expiresAt) <= Date.now() ? 'expired' : 'checkout_changed';
             this.invalidate(reason);
             throw new CheckoutPreparationError(prepared.id, reason);
@@ -132,6 +152,13 @@ export class PreparationGate {
         }
     }
     isEngaged() { return this.state !== 'unused'; }
+    /**
+     * A card request that only a prepared checkout may pay (an Adyen merchant
+     * profile's, or a Fiserv card capture, pre-claim.ts) arrived with no
+     * preparation and was refused. Like claim() on an unused gate, a later
+     * prepare() is then refused too.
+     */
+    observeUnprepared() { this.observedRequest = true; }
     retireUnboundClaim() {
         if (this.state !== 'consumed' || !this.prepared || this.lifecycle.getState().authorizationId)
             return;

package/dist/prepared-processor.d.ts

@@ -1,10 +1,43 @@
-export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'recurly' | 'spreedly' | 'adyen' | 'checkout_com' | 'paysafe';
+export type PreparationProcessor = 'square' | 'braintree' | 'worldpay' | 'bambora' | 'mercado_pago' | 'recurly' | 'spreedly' | 'adyen' | 'checkout_com' | 'paysafe' | 'fiserv';
 export type PreparationEnvironment = 'production' | 'sandbox' | 'shared';
-/** How the approved card reaches the processor: the device's own request (token), or ciphertext the device produces for this browser to send (cse, Adyen). */
+/**
+ * How the approved card reaches the processor: the device's own request (token), or
+ * ciphertext the device produces for this browser to send (cse: Adyen's four encrypted
+ * fields, or Fiserv's Secure Data Capture envelope under a key Agentcard pinned).
+ */
 export type PreparationMode = 'token' | 'cse';
 export declare function preparationMode(psp: string): PreparationMode;
-/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. Adyen can: test and live are separate hosts and key prefixes. */
+/**
+ * Shared endpoint processors cannot attest test/live mode from their URL or key prefix.
+ * Adyen can: test and live are separate hosts and key prefixes. Fiserv's are separate
+ * hosts too: connect (production) and connect-cert (sandbox).
+ */
 export declare function validPreparationEnvironment(psp: string, environment: string): boolean;
 export declare function preparationEndpoint(psp: PreparationProcessor, environment: PreparationEnvironment): string;
 /** Processor identity and environment are part of the device's prior consent. */
 export declare function matchesPreparedRequest(psp: PreparationProcessor, environment: PreparationEnvironment, requestUrl: string, method: string, body?: string | null, headers?: Record<string, string>): boolean;
+/**
+ * The one request a merchant-hosted preparation pays: the reviewed profile's
+ * card request itself (classifyMerchantRequest pauses it), at the profile's exact
+ * endpoint, as its method, with a body the profile reviewed. A sibling endpoint, a
+ * stored card, a store-the-card body or any other shape never consumes consent.
+ */
+export declare function matchesPreparedMerchantRequest(profileId: string, requestUrl: string, method: string, body?: string | null, sandboxDeclaration?: {
+    endpoint: string;
+}): boolean;
+/**
+ * matchesPreparedRequest for a preparation, through its merchant profile (at its declared
+ * endpoint, when it names one) when it names one. A Fiserv preparation also names the key its
+ * cardholder approved a payment under (merchantProfile, a pin id): the capture's own pin,
+ * the one its envelope's key is pinned as for its endpoint and merchant, must be that
+ * pin, as the API's bind requires. Two pins in one environment (a merchant's old and new
+ * keys during a rotation) never spend each other's approval. No other processor names one.
+ */
+export declare function matchesPreparation(preparation: {
+    psp: PreparationProcessor;
+    environment: PreparationEnvironment;
+    merchantProfile?: string;
+    sandboxDeclaration?: {
+        endpoint: string;
+    };
+}, requestUrl: string, method: string, body?: string | null, headers?: Record<string, string>): boolean;

package/dist/prepared-processor.js

@@ -4,20 +4,28 @@ import { braintreeEnvironment, isPreparedBraintreeRequest, readTokenizationJson
 import { isPreparedRecurlyRequest } from './recurly.generated.js';
 import { isPreparedSpreedlyRequest, isSpreedlyTokenRequest, SPREEDLY_TOKEN_ENDPOINT } from './spreedly.generated.js';
 import { checkoutComPreparationUrl, isPreparedCheckoutComRequest } from './checkout-com.generated.js';
+import { classifyDeclaredMerchantRequest, classifyMerchantRequest } from './merchant-hosted.js';
+import { fiservCapturePinId, fiservPreparationUrl, isPreparedFiservRequest } from './fiserv.js';
 export function preparationMode(psp) {
-    return psp === 'adyen' ? 'cse' : 'token';
+    return psp === 'adyen' || psp === 'fiserv' ? 'cse' : 'token';
 }
-/** Shared endpoint processors cannot attest test/live mode from their URL or key prefix. Adyen can: test and live are separate hosts and key prefixes. */
+/**
+ * Shared endpoint processors cannot attest test/live mode from their URL or key prefix.
+ * Adyen can: test and live are separate hosts and key prefixes. Fiserv's are separate
+ * hosts too: connect (production) and connect-cert (sandbox).
+ */
 export function validPreparationEnvironment(psp, environment) {
     if (psp === 'bambora' || psp === 'mercado_pago' || psp === 'recurly' || psp === 'spreedly')
         return environment === 'shared';
-    return ['square', 'braintree', 'worldpay', 'adyen', 'checkout_com', 'paysafe'].includes(psp) && ['production', 'sandbox'].includes(environment);
+    return ['square', 'braintree', 'worldpay', 'adyen', 'checkout_com', 'paysafe', 'fiserv'].includes(psp) && ['production', 'sandbox'].includes(environment);
 }
 export function preparationEndpoint(psp, environment) {
     if (!validPreparationEnvironment(psp, environment))
         throw new Error('unsupported_preparation_processor');
     if (psp === 'paysafe')
         return paysafePreparationUrl(environment);
+    if (psp === 'fiserv')
+        return fiservPreparationUrl(environment);
     if (psp === 'checkout_com')
         return checkoutComPreparationUrl(environment);
     if (psp === 'adyen')
@@ -84,6 +92,11 @@ export function matchesPreparedRequest(psp, environment, requestUrl, method, bod
         return false;
     if (psp === 'paysafe')
         return isPreparedPaysafeRequest(requestUrl, method, body ?? null, environment, headers);
+    // Fiserv: that environment's card-capture endpoint exactly, the capture rules on the whole
+    // request (missing headers refuse), and an envelope under a key pinned for that environment
+    // and for the merchant the body names (payment-core isPreparedFiservRequest).
+    if (psp === 'fiserv')
+        return isPreparedFiservRequest(requestUrl, method.toUpperCase(), body ?? null, environment, headers);
     if (psp === 'checkout_com')
         return isPreparedCheckoutComRequest(requestUrl, method, body ?? null, environment, headers);
     if (psp === 'adyen')
@@ -120,3 +133,40 @@ export function matchesPreparedRequest(psp, environment, requestUrl, method, bod
         return false;
     }
 }
+/**
+ * The one request a merchant-hosted preparation pays: the reviewed profile's
+ * card request itself (classifyMerchantRequest pauses it), at the profile's exact
+ * endpoint, as its method, with a body the profile reviewed. A sibling endpoint, a
+ * stored card, a store-the-card body or any other shape never consumes consent.
+ */
+export function matchesPreparedMerchantRequest(profileId, requestUrl, method, body, sandboxDeclaration) {
+    try {
+        const verdict = sandboxDeclaration
+            ? classifyDeclaredMerchantRequest(profileId, sandboxDeclaration.endpoint, requestUrl, method, body ?? '')
+            : classifyMerchantRequest(profileId, requestUrl, method, body ?? '');
+        return verdict.verdict === 'pause';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * matchesPreparedRequest for a preparation, through its merchant profile (at its declared
+ * endpoint, when it names one) when it names one. A Fiserv preparation also names the key its
+ * cardholder approved a payment under (merchantProfile, a pin id): the capture's own pin,
+ * the one its envelope's key is pinned as for its endpoint and merchant, must be that
+ * pin, as the API's bind requires. Two pins in one environment (a merchant's old and new
+ * keys during a rotation) never spend each other's approval. No other processor names one.
+ */
+export function matchesPreparation(preparation, requestUrl, method, body, headers) {
+    if (preparation.psp === 'fiserv') {
+        if (!matchesPreparedRequest(preparation.psp, preparation.environment, requestUrl, method, body, headers))
+            return false;
+        return typeof preparation.merchantProfile === 'string' && fiservCapturePinId(requestUrl, body ?? null) === preparation.merchantProfile;
+    }
+    if (preparation.merchantProfile !== undefined) {
+        return preparation.psp === 'adyen'
+            && matchesPreparedMerchantRequest(preparation.merchantProfile, requestUrl, method, body, preparation.sandboxDeclaration);
+    }
+    return matchesPreparedRequest(preparation.psp, preparation.environment, requestUrl, method, body, headers);
+}

package/dist/registry.d.ts

@@ -64,10 +64,55 @@ export interface Recognizer {
     clientSideEncrypted?: boolean;
     /** How the card reaches the processor; absent means 'token'. Carried verbatim by syncRegistry. */
     mode?: CheckoutMode;
+    /**
+     * Dark launch: a capability name the API attaches to an entry it serves only
+     * to a client that declared it (?capabilities=). Absent on every entry in
+     * BUILTIN_REGISTRY, because a gated entry is left out of the built-in
+     * fallback. Carried verbatim by syncRegistry for a client that does declare
+     * it, so the SDK never has to act on it.
+     */
+    capability?: string;
+    /**
+     * True when this processor cannot be taken over on an ordinary authorization:
+     * the cardholder must have approved a prepare() first. authorize() refuses
+     * such a request locally, before it prompts, when no preparation is active
+     * (PreparationRequiredError), and the API answers 409 preparation_required.
+     * Absent on every BUILTIN_REGISTRY entry today and carried verbatim by
+     * syncRegistry for a build that reaches a processor which sets it.
+     */
+    preparationRequired?: boolean;
+    /**
+     * Anchored regex SOURCES (a subset of `hosts`) marking the vendor's
+     * SANDBOX/TEST hostnames, so the backend and the device can tell a test host
+     * from a live one. Carried verbatim by syncRegistry; the SDK never matches
+     * with them (recognition still uses `hosts`), so it acts on neither this nor
+     * the pin below. Present in BUILTIN_REGISTRY for the host-separated processors.
+     */
+    sandboxHosts?: string[];
+    /**
+     * True when a processor's host environment is enforced: the API refuses a
+     * create whose host environment disagrees with the row's test/live nature, and
+     * the device sends only documented test cards to a sandbox host. Absent on
+     * every entry today; carried verbatim by syncRegistry, and the SDK never acts
+     * on it.
+     */
+    hostEnvironmentPinned?: boolean;
 }
 import { BUILTIN_REGISTRY } from './builtin-registry.generated.js';
 export { BUILTIN_REGISTRY };
 export declare function findRecognizer(url: string, registry?: Recognizer[]): Recognizer | null;
+/**
+ * True when this processor cannot be taken over on an ordinary authorization:
+ * the cardholder must have approved a prepare() first (the `preparationRequired`
+ * field above). authorize() applies this before it prompts and refuses with
+ * PreparationRequiredError when no preparation is active; the API answers 409
+ * preparation_required for the same case. This is the SAME rule payment-core's
+ * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
+ * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
+ * this is false for all 24 today.
+ */
+export declare function recognizerRequiresPreparation(rec: Pick<Recognizer, 'preparationRequired'>): boolean;
 /**
  * Glob url patterns covering every host in `registry` — what to hand
  * `Fetch.enable` so a card request is ever paused. Deliberately a superset of

package/dist/registry.js

@@ -46,6 +46,20 @@ export function findRecognizer(url, registry = BUILTIN_REGISTRY) {
         return new RegExp(`^(?:${r.match.source})$`, 'i').test(hostPath);
     }) ?? null);
 }
+/**
+ * True when this processor cannot be taken over on an ordinary authorization:
+ * the cardholder must have approved a prepare() first (the `preparationRequired`
+ * field above). authorize() applies this before it prompts and refuses with
+ * PreparationRequiredError when no preparation is active; the API answers 409
+ * preparation_required for the same case. This is the SAME rule payment-core's
+ * recognizerRequiresPreparation applies on the server, a strict `=== true`, so a
+ * value that rode in over the wire (syncRegistry spreads the served JSON) cannot
+ * turn a truthy string into a gate. Absent on every BUILTIN_REGISTRY entry, so
+ * this is false for all 24 today.
+ */
+export function recognizerRequiresPreparation(rec) {
+    return rec.preparationRequired === true;
+}
 // ---------------------------------------------------------------------------
 // Registry -> CDP url patterns
 //

package/dist/stripe-checkout.generated.js

@@ -1,7 +1,7 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: 128bbf2359c38eda0d29a58c9b6f83123cf2d27d94365a5665e1569d605e9d2c
-// src/definitions.js
+// artifact-sha256: 9edf78da59b3bdfe310b4422e06d333cd164497cdb4070db59ffed348492198a
+// src/deep-freeze.js
 function deepFreeze(value) {
     if (value && typeof value === "object" && !Object.isFrozen(value)) {
         for (const child of Object.values(value))
@@ -10,6 +10,7 @@ function deepFreeze(value) {
     }
     return value;
 }
+// src/definitions.js
 var PROCESSOR_DEFINITIONS = deepFreeze([
     {
         psp: "spreedly",
@@ -69,6 +70,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         psp: "braintree",
         match: "payments(\\.sandbox)?\\.braintree-api\\.com/graphql",
         hosts: ["^payments\\.braintree-api\\.com$", "^payments\\.sandbox\\.braintree-api\\.com$"],
+        sandboxHosts: ["^payments\\.sandbox\\.braintree-api\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^authorization$", "^braintree-version$"]
     },
@@ -86,6 +88,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
             "^card-acquisition-gateway\\.checkout\\.com$",
             "^card-acquisition-gateway\\.sandbox\\.checkout\\.com$"
         ],
+        sandboxHosts: ["^api\\.sandbox\\.checkout\\.com$", "^card-acquisition-gateway\\.sandbox\\.checkout\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^authorization$"]
     },
@@ -114,6 +117,15 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // merchants on them were silently never paused.
         match: "(checkoutshopper-(test|live(-[a-z]+)?)\\.adyen\\.com|([a-z0-9-]+\\.)*adyenpayments\\.com)/checkoutshopper/v1/sessions/[A-Za-z0-9_-]+/payments",
         hosts: ["^checkoutshopper-(test|live(-[a-z]+)?)\\.adyen\\.com$", "^([a-z0-9-]+\\.)*adyenpayments\\.com$"],
+        // The sandbox marker matches ONLY the TEST hostname, a subset of the first
+        // host source (which matches checkoutshopper-test and every checkoutshopper-live
+        // regional host). checkoutshopper-live* and *.adyenpayments.com are live.
+        // Load-bearing for Adyen although Adyen does not pin its environment: the
+        // Adyen TEST platform rule (backend.js adyenLivePlatform) reads this marker
+        // on the server's authorization create and cardholder legs
+        // (services/checkout-cse-adyen.ts in the backend), on the device and in the
+        // enclave. Dropping or widening it moves which payments count as Adyen TEST.
+        sandboxHosts: ["^checkoutshopper-test\\.adyen\\.com$"],
         encoding: "json",
         passthroughHeaders: [],
         clientSideEncrypted: true,
@@ -183,6 +195,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // PAN@ card_data.number. POST /v2/card-nonce (URL always carries ?_=&version=).
         match: "pci-connect\\.squareup(?:sandbox)?\\.com/v2/card-nonce",
         hosts: ["^pci-connect\\.squareup\\.com$", "^pci-connect\\.squareupsandbox\\.com$"],
+        sandboxHosts: ["^pci-connect\\.squareupsandbox\\.com$"],
         encoding: "json",
         passthroughHeaders: []
         // auth = client_id in body; no auth header
@@ -203,6 +216,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // request types on the same URL — the body, not the URL, is what distinguishes them.
         match: "(api2|apitest)\\.authorize\\.net/xml/v1/request\\.api",
         hosts: ["^api2\\.authorize\\.net$", "^apitest\\.authorize\\.net$"],
+        sandboxHosts: ["^apitest\\.authorize\\.net$"],
         encoding: "json",
         // JSON body; Content-Type is sometimes text/plain (preflight dodge), replayed as-is
         passthroughHeaders: []
@@ -213,6 +227,8 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // the two paths need DIFFERENT vendor media types; `application/json` → HTTP 406.
         match: "(try\\.)?access\\.worldpay\\.com/(sessions/card|verifiedTokens/sessions)",
         hosts: ["^access\\.worldpay\\.com$", "^try\\.access\\.worldpay\\.com$"],
+        sandboxHosts: ["^try\\.access\\.worldpay\\.com$"],
+        // try.* is Worldpay's try/test host
         encoding: "json",
         passthroughHeaders: ["^accept$"]
     },
@@ -229,6 +245,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // with no branch back to the covered path.
         match: "(secure|ppp-test)\\.safecharge\\.com/ppp/api/v1/(?:cardTokenization|clientPayment|websdk/initPaymentWithCardTokenization)\\.do",
         hosts: ["^secure\\.safecharge\\.com$", "^ppp-test\\.safecharge\\.com$"],
+        sandboxHosts: ["^ppp-test\\.safecharge\\.com$"],
         encoding: "json",
         passthroughHeaders: []
     },
@@ -263,6 +280,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
             "^pci-api\\.airwallex\\.com$",
             "^pci-api\\.sandbox\\.airwallex\\.com$"
         ],
+        sandboxHosts: ["^checkout\\.sandbox\\.airwallex\\.com$", "^pci-api\\.sandbox\\.airwallex\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^client-secret$", "^authorization$", "^x-auth-token$", "^x-on-behalf-of$", "^x-api-version$"]
     },
@@ -276,6 +294,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // Checkout Page (signature-authed, server-to-server, no card) — the POST gate is what splits them.
         match: "(api|sandboxapi)\\.rapyd\\.net/v1/(?:hosted/collect/card/[^/?#]+/payment_method|checkout/checkout_[A-Za-z0-9]+)(?:[?#]|$)",
         hosts: ["^api\\.rapyd\\.net$", "^sandboxapi\\.rapyd\\.net$"],
+        sandboxHosts: ["^sandboxapi\\.rapyd\\.net$"],
         encoding: "json",
         passthroughHeaders: []
         // auth rides the opaque hosted-page / checkout token in the URL
@@ -287,6 +306,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // multi-tenant surface: `ppmcc` is dlocal-operated, not merchant-registrable.
         match: "ppmcc(-sandbox)?\\.dlocal\\.com/cvault/credit-card/temporal",
         hosts: ["^ppmcc\\.dlocal\\.com$", "^ppmcc-sandbox\\.dlocal\\.com$"],
+        sandboxHosts: ["^ppmcc-sandbox\\.dlocal\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^x-fields-api-key$", "^x-uow$", "^x-dlocal-infrav2$"]
     },
@@ -318,6 +338,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
             "^api\\.ebanxpay\\.com$",
             "^sandbox\\.ebanxpay\\.com$"
         ],
+        sandboxHosts: ["^sandbox\\.ebanx\\.com$", "^sandbox-local-latam\\.ebanx\\.com$", "^sandbox\\.ebanxpay\\.com$"],
         encoding: "json",
         passthroughHeaders: []
     },
@@ -342,6 +363,8 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // GPO Secure Forms. PAN@ card.number.
         match: "(secure\\.payu\\.com|(merch-prod|secure)\\.snd\\.payu\\.com)/api/front/tokens",
         hosts: ["^secure\\.payu\\.com$", "^(merch-prod|secure)\\.snd\\.payu\\.com$"],
+        sandboxHosts: ["^(merch-prod|secure)\\.snd\\.payu\\.com$"],
+        // .snd. is PayU's sandbox
         encoding: "json",
         // Native checkout attaches a bearer to tokenization; preserve it on replay.
         passthroughHeaders: ["^authorization$"]
@@ -403,6 +426,7 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
         // card/tokenize uses a saved paymentToken, and 3DS-specific paths are unverified.
         match: "(?:api(\\.test)?\\.paysafe\\.com/(?:paymenthub/v1/singleusepaymenthandles|js/api/v1/tokenize)|hosted(\\.test)?\\.paysafe\\.com/checkout/api/v1/tokenize)(?![\\w/-])",
         hosts: ["^api\\.paysafe\\.com$", "^api\\.test\\.paysafe\\.com$", "^hosted\\.paysafe\\.com$", "^hosted\\.test\\.paysafe\\.com$"],
+        sandboxHosts: ["^api\\.test\\.paysafe\\.com$", "^hosted\\.test\\.paysafe\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^authorization$", "^x-paysafe-credentials$", "^correlationid$"]
     },
@@ -446,6 +470,8 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
             "^gatewayt\\.moneris\\.com$",
             "^gatewaydev\\.moneris\\.com$"
         ],
+        // Live: www3, gateway. Test/QA/dev: esqa, gatewayqa, gatewayt, gatewaydev.
+        sandboxHosts: ["^esqa\\.moneris\\.com$", "^gatewayqa\\.moneris\\.com$", "^gatewayt\\.moneris\\.com$", "^gatewaydev\\.moneris\\.com$"],
         encoding: "form",
         passthroughHeaders: []
     },
@@ -486,8 +512,66 @@ var PROCESSOR_DEFINITIONS = deepFreeze([
             "^apis\\.eu\\.globalpay\\.com$",
             "^apis\\.sandbox\\.eu\\.globalpay\\.com$"
         ],
+        // Heartland/Portico cert.* is the certification (sandbox) host; GP-API sandbox is apis.sandbox[.eu].
+        sandboxHosts: ["^cert\\.api2\\.heartlandportico\\.com$", "^apis\\.sandbox\\.globalpay\\.com$", "^apis\\.sandbox\\.eu\\.globalpay\\.com$"],
         encoding: "json",
         passthroughHeaders: ["^authorization$", "^x-gp-version$"]
+    },
+    // ── Encrypted on the device under a pinned key ────────────────────────────
+    {
+        psp: "fiserv",
+        // Fiserv Commerce Hub card capture from the Secure Data Capture (SDC) frame,
+        // the request Home Depot's OrangePay checkout sends (payment-fields.js and
+        // sdk-secure 3.8.14). The frame always encrypts: it seals the card with
+        // AES-256-GCM under a fresh key, wraps that key with RSA-OAEP-SHA256 under the
+        // public key the page passed it, and posts the envelope as
+        // source.encryptionData. It picks its endpoint by the page's auth type
+        // (iframe.js @85480): an AccessToken (Security Credentials) posts here, to
+        // card-capture; a Checkout Sessions JWT posts to /ch/checkouts/v1/payment-link
+        // instead. payment-link also carries the card, and it is left out on purpose:
+        // `match` names card-capture only, so a Sessions merchant's capture is never
+        // paused and fails as it does today. Fastlane (PaymentToken), ACH
+        // (PaymentCheck), gift and EBT captures share this URL, carry no Vault card,
+        // and the SDK continues them unpaused (fiserv.js isFiservPausableBody).
+        // The Wave 0 sandbox gate (2026-09-24, connect-cert, Fiserv simulator cards)
+        // settled the mode: card-capture refuses a plaintext source.card (400
+        // GATEWAY 302 "Missing or Invalid Encryption Data") and captures the frame's
+        // own envelope with no Origin, so the device builds that envelope under a
+        // key Agentcard pinned (fiserv-keys.js), the runtime writes its four members
+        // over the paused ones, and the capture continues from the agent's browser.
+        // The AccessToken the agent can read was refused on charges and tokens at
+        // Fiserv's edge in that sandbox. Every other Commerce Hub path is refused
+        // here: charges, tokens, security/keys, payment-link, and the non-production
+        // hosts (connect-dev, -qa, -uat, -test); resolveRecognizerForUrl also takes
+        // only the two endpoints written exactly (fiserv-environment.js). The
+        // envelope carries no timestamp or session binding, so it is approved by the
+        // cardholder every time: dark until an org is allowlisted, and autopilot
+        // refuses fiserv at all three gates.
+        capability: "fiserv_card_capture",
+        // A Fiserv card is sealed only for a capture the cardholder already approved
+        // through a prepare(): the backend refuses an unprepared create (409
+        // preparation_required), the internal buy loop never mints a Fiserv round,
+        // and the SDK refuses locally before it prompts.
+        preparationRequired: true,
+        match: "connect(?:-cert)?\\.fiservapis\\.com/ch/payments-vas/v1/card-capture(?![\\w/.-])",
+        hosts: ["^connect\\.fiservapis\\.com$", "^connect-cert\\.fiservapis\\.com$"],
+        sandboxHosts: ["^connect-cert\\.fiservapis\\.com$"],
+        // A live row reaches connect only and a test row connect-cert only, and
+        // connect-cert receives only documented test cards (device-replay.js).
+        hostEnvironmentPinned: true,
+        encoding: "json",
+        // The browser continues the capture with its own headers, so only the ones
+        // the backend checks against the body and the merchant are kept:
+        // Auth-Token-Type, the merchant and terminal ids, and the embedding frame's
+        // origin the SDC names (x-integration-origin, self-asserted). The
+        // AccessToken, the API key, Client-Request-Id and Timestamp are never stored.
+        passthroughHeaders: ["^auth-token-type$", "^x-integration-merchant-id$", "^x-integration-terminal-id$", "^x-integration-origin$"],
+        clientSideEncrypted: true,
+        mode: "cse",
+        cse: {
+            at: "source.encryptionData",
+            fields: ["keyId", "encryptedKey", "encryptionBlock", "aesIv"]
+        }
     }
 ]);
 var PSP_RECOGNIZERS = deepFreeze(PROCESSOR_DEFINITIONS.map(({ compose, encryptedCardFields, ...definition }) => definition));
@@ -497,17 +581,22 @@ var PSP_CLIENT_TABLE = deepFreeze(PROCESSOR_DEFINITIONS.map((definition) => ({
     hosts: definition.hosts.map((source) => new RegExp(source, "i")),
     encoding: definition.encoding,
     headers: definition.passthroughHeaders.map((source) => new RegExp(source, "i")),
+    ...definition.sandboxHosts ? { sandboxHosts: definition.sandboxHosts.map((source) => new RegExp(source, "i")) } : {},
+    ...definition.hostEnvironmentPinned ? { hostEnvironmentPinned: true } : {},
     ...definition.mode ? { mode: definition.mode } : {},
     ...definition.clientSideEncrypted ? { clientSideEncrypted: true } : {},
     ...definition.compose ? { compose: definition.compose } : {},
     ...definition.encryptedCardFields ? { cse: { fields: definition.encryptedCardFields } } : {},
     ...definition.hostedForm ? { form: definition.hostedForm.card } : {}
 })));
-var BUILTIN_REGISTRY = deepFreeze(PSP_RECOGNIZERS.map(({ cse, hostedForm, ...definition }) => ({
-    ...definition,
-    match: new RegExp(definition.match, "i"),
-    passthroughHeaders: definition.passthroughHeaders.map((source) => new RegExp(source, "i"))
-})));
+function buildBuiltinRegistry(recognizers) {
+    return recognizers.filter((definition) => !definition.capability).map(({ cse, hostedForm, ...definition }) => ({
+        ...definition,
+        match: new RegExp(definition.match, "i"),
+        passthroughHeaders: definition.passthroughHeaders.map((source) => new RegExp(source, "i"))
+    }));
+}
+var BUILTIN_REGISTRY = deepFreeze(buildBuiltinRegistry(PSP_RECOGNIZERS));
 var CHECKOUT_MODES = deepFreeze(["token", "cse", "hosted_form"]);
 function recognizerByPsp(psp) {
     return typeof psp === "string" ? PSP_CLIENT_TABLE.find((entry) => entry.psp === psp) ?? null : null;

package/dist/substitutions.generated.d.ts

@@ -7,4 +7,5 @@ declare var SubstitutionError: {
     };
 };
 declare function substituteEncryptedFields(body: any, sub: any): string;
-export { SubstitutionError, substituteEncryptedFields };
+declare function substituteMerchantHosted(body: any, sub: any, opts: any): string;
+export { SubstitutionError, substituteEncryptedFields, substituteMerchantHosted };