@agent-cards/checkout 0.17.0 → 0.19.0

package/dist/preflight-catalog.json

@@ -2097,6 +2097,72 @@
       "hostname_pattern": "^www\\.mercadopago\\.com\\.ar$",
       "pathname_pattern": "^\\/checkout\\/v1\\/payment\\/redirect\\/[^/]+\\/card-form\\/?$"
     },
+    {
+      "id": "fiserv-commercehub-payment-fields",
+      "psp": "fiserv",
+      "kinds": [
+        "script"
+      ],
+      "origin": "https://commercehub-checkout.fiservapps.com",
+      "path_pattern": "/sdk/:version/payment-fields.js",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js",
+          "reviewed_on": "2026-09-23"
+        },
+        {
+          "kind": "primary_source",
+          "reference": "https://orangepay-ecommerce.hdpayments.homedepot.com/env.js",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-checkout\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/payment-fields\\.js$"
+    },
+    {
+      "id": "fiserv-commercehub-checkout-script",
+      "psp": "fiserv",
+      "kinds": [
+        "script"
+      ],
+      "origin": "https://commercehub-checkout.fiservapps.com",
+      "path_pattern": "/sdk/:version/checkout.js",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://developer.fiserv.com/product/CommerceHub/docs/Online-Commerce/Integration-Options/Hosted-Checkout/Hosted-Checkout-Version-Release",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-checkout\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/checkout\\.js$"
+    },
+    {
+      "id": "fiserv-secure-data-capture-frame",
+      "psp": "fiserv",
+      "kinds": [
+        "frame",
+        "iframe",
+        "document"
+      ],
+      "origin": "https://commercehub-secure-data-capture.fiservapps.com",
+      "path_pattern": "/sdk-secure/:version/iframe.html",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js",
+          "reviewed_on": "2026-09-23"
+        },
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-secure-data-capture.fiservapps.com/sdk-secure/3.8.14/iframe.html",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-secure-data-capture\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk-secure\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/iframe\\.html$"
+    },
     {
       "id": "square-web-sdk-sandbox",
       "psp": "square",
@@ -2454,6 +2520,72 @@
       ],
       "hostname_pattern": "^checkoutshopper-live-nea\\.adyen\\.com$",
       "pathname_pattern": "^\\/checkoutshopper\\/securedfields\\/[^/]+\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/securedFields\\.html$"
+    },
+    {
+      "id": "fiserv-commercehub-payment-fields-cert",
+      "psp": "fiserv",
+      "kinds": [
+        "script"
+      ],
+      "origin": "https://commercehub-checkout-cert.fiservapps.com",
+      "path_pattern": "/sdk/:version/payment-fields.js",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js",
+          "reviewed_on": "2026-09-23"
+        },
+        {
+          "kind": "primary_source",
+          "reference": "https://orangepay-ecommerce.hdpayments.homedepot.com/env.js",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-checkout-cert\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/payment-fields\\.js$"
+    },
+    {
+      "id": "fiserv-commercehub-checkout-script-cert",
+      "psp": "fiserv",
+      "kinds": [
+        "script"
+      ],
+      "origin": "https://commercehub-checkout-cert.fiservapps.com",
+      "path_pattern": "/sdk/:version/checkout.js",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://developer.fiserv.com/product/CommerceHub/docs/Online-Commerce/Integration-Options/Hosted-Checkout/Hosted-Checkout-Version-Release",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-checkout-cert\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/checkout\\.js$"
+    },
+    {
+      "id": "fiserv-secure-data-capture-frame-cert",
+      "psp": "fiserv",
+      "kinds": [
+        "frame",
+        "iframe",
+        "document"
+      ],
+      "origin": "https://commercehub-secure-data-capture-cert.fiservapps.com",
+      "path_pattern": "/sdk-secure/:version/iframe.html",
+      "sources": [
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-checkout.fiservapps.com/sdk/3.8.14/payment-fields.js",
+          "reviewed_on": "2026-09-23"
+        },
+        {
+          "kind": "primary_source",
+          "reference": "https://commercehub-secure-data-capture.fiservapps.com/sdk-secure/3.8.14/iframe.html",
+          "reviewed_on": "2026-09-23"
+        }
+      ],
+      "hostname_pattern": "^commercehub-secure-data-capture-cert\\.fiservapps\\.com$",
+      "pathname_pattern": "^\\/sdk-secure\\/[0-9]+\\.[0-9]+\\.[0-9]+\\/iframe\\.html$"
     }
   ],
   "processors": [
@@ -2640,7 +2772,7 @@
         },
         {
           "id": "stripe.tokenization",
-          "path_pattern": "^/v1/(?:payment_methods|tokens)$",
+          "path_pattern": "^/v1/(?:payment_methods|tokens|sources|confirmation_tokens)$",
           "effect": "token_or_method_creation",
           "amount_binding": "none",
           "psp": "stripe",

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.d.ts

@@ -271,7 +271,7 @@ export declare function getCheckoutPreflightCatalog(): {
             readonly requires: "reviewed_final_payment_and_continuation_evidence";
         }, {
             readonly id: "stripe.tokenization";
-            readonly path_pattern: "^/v1/(?:payment_methods|tokens)$";
+            readonly path_pattern: "^/v1/(?:payment_methods|tokens|sources|confirmation_tokens)$";
             readonly effect: "token_or_method_creation";
             readonly amount_binding: "none";
             readonly psp: "stripe";

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,7 +19,20 @@ 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;
+    /**
+     * Retire the server handle first, then report the form outcome. Neither
+     * call waits on the other: a stalled report cannot delay the cancel, and a
+     * stalled cancel cannot lose the report.
+     */
+    private cancelThenObserve;
 }

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,10 +82,12 @@ 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.opts.vault.cancelPreparation(prepared.id).catch(() => { });
+                void this.cancelThenObserve(prepared.id, 'cancelled');
                 throw new CheckoutPreparationError(prepared.id, 'cancelled');
             }
             await this.assertDocument();
@@ -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,10 +152,17 @@ 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;
-        void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+        void this.cancelThenObserve(this.prepared.id, 'request_not_bound');
         // No bound ID means the adapter must not leave a spent handle appearing ready.
         if (this.lifecycle.getState().status === 'ready_to_submit')
             this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared.id, 'request_not_bound'));
@@ -148,7 +175,17 @@ export class PreparationGate {
         clearTimeout(this.expiryTimer);
         this.stop.abort();
         if (this.prepared)
-            void this.opts.vault.cancelPreparation(this.prepared.id).catch(() => { });
+            void this.cancelThenObserve(this.prepared.id, reason);
         this.lifecycle.preparationFailed(new CheckoutPreparationError(this.prepared?.id ?? null, reason));
     }
+    /**
+     * Retire the server handle first, then report the form outcome. Neither
+     * call waits on the other: a stalled report cannot delay the cancel, and a
+     * stalled cancel cannot lose the report.
+     */
+    async cancelThenObserve(id, reason) {
+        const cancellation = this.opts.vault.cancelPreparation(id).catch(() => { });
+        const observation = this.opts.vault.observePreparation?.(id, this.observedRequest ? 'presented_not_filled' : 'not_presented', reason);
+        await Promise.all([cancellation, observation?.catch(() => { })]);
+    }
 }

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

@@ -40,6 +40,21 @@ export interface Recognizer {
      * the call (signatures, client tokens). Matched case-insensitively.
      */
     passthroughHeaders: RegExp[];
+    /**
+     * Form keys that carry the card number. When present, a request on this
+     * recognizer's endpoints is a card request only if its body carries one of
+     * them: a Stripe confirmation that pays with a method the page already
+     * created (`payment_method=pm_...`) carries none, so there is nothing for
+     * the cardholder to approve. Served by the API and carried through
+     * syncRegistry() verbatim.
+     */
+    cardFields?: string[];
+    /**
+     * With cardFields: the endpoints (regex source over hostname + pathname,
+     * anchored) where a request without a card is routine and never ours, so
+     * it continues untouched; a request without a card anywhere else is refused.
+     */
+    passWithoutCard?: string;
     /**
      * True when the card is encrypted inside the page before the request leaves.
      * A digit swap is useless here; the vault must re-run the PSP's client-side
@@ -49,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
 //