@agent-cards/checkout 0.18.0 → 0.19.0

package/dist/client.js

@@ -1,6 +1,9 @@
-import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
+import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, recognizerRequiresPreparation, } from './registry.js';
+import { armServedProfiles, classifyProfileRequest, declareSandboxMerchant, merchantProfileEnvironment, merchantProfileFor, merchantProfileUrlPatterns, } from './merchant-hosted.js';
+import { merchantAmountExchanges, merchantAmountFromResponses, merchantProfilePricedBySource, merchantTotalWire, MerchantTotalWait, } from './merchant-total.js';
 import { isMercadoTokenRequest, parseMercadoCheckoutContext, validateMercadoProcessorContext } from './mercado-checkout.generated.js';
-import { matchesPreparedRequest, preparationMode, validPreparationEnvironment } from './prepared-processor.js';
+import { matchesPreparation, preparationMode, validPreparationEnvironment } from './prepared-processor.js';
+import { fiservKeyPinById, isFiservSubstitution, requiresFiservPreparation } from './fiserv.js';
 import { hasOwnedShopMarker, parseOwnedShopOrder, parseOwnedShopReceipt } from './owned-shop.generated.js';
 import { requestWithoutCard } from './card-fields.generated.js';
 import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
@@ -20,6 +23,17 @@ export const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
  * confirm, which hosted Checkout sends after an approval.
  */
 export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
+/**
+ * Dark-launch capabilities this build can finish. Sent on syncRegistry as
+ * ?capabilities= so the API also serves the recognizers gated behind one of
+ * these. `fiserv_card_capture`: Fiserv Commerce Hub's Secure Data Capture card
+ * capture, which this build pauses and pays only through a prepared checkout
+ * (pre-claim.ts, fiserv.ts). The API serves Fiserv's recognizer only to a build
+ * that lists it and only for a company Agentcard turned Fiserv on for, so an older
+ * SDK never pauses a capture it cannot finish and no SDK pauses one for a company
+ * Fiserv is off for; the API also refuses a Fiserv payment for every such company.
+ */
+export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture'];
 /** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
 export function validAmountInput(amount) {
     if (typeof amount === 'number')
@@ -59,6 +73,22 @@ export class UnsupportedModeError extends Error {
         this.name = 'UnsupportedModeError';
     }
 }
+/**
+ * The recognizer says this processor is preparation-required, and no preparation
+ * was passed. Its card may be sent only after the cardholder approved a
+ * prepare(): call prepareCheckout() (or the adapters' preparation gate) before
+ * this request is intercepted. Thrown locally before any create or prompt, and
+ * terminal (retrying the same paused request without preparing fails the same
+ * way). The API answers 409 preparation_required for the same case.
+ */
+export class PreparationRequiredError extends Error {
+    psp;
+    constructor(psp) {
+        super(`${psp} requires a prepared checkout: run prepareCheckout() and have the cardholder approve it before this request is taken over. Nothing was charged.`);
+        this.psp = psp;
+        this.name = 'PreparationRequiredError';
+    }
+}
 export class ApprovalTimeoutError extends Error {
     constructor(ms) { super(`user did not approve within ${ms}ms`); this.name = 'ApprovalTimeoutError'; }
 }
@@ -96,6 +126,13 @@ export class ApprovalDeclinedError extends Error {
  * and quiet the page's retry exactly as for a person's "no"), so it extends
  * ApprovalDeclinedError: code that already handles declines keeps working,
  * and code that wants the numbers reads them here or branches on `code`.
+ *
+ * A merchant-hosted checkout (an Adyen merchant whose own server charges the card)
+ * has no processor read-back: its agent amount is held to the merchant's own
+ * checkout total, as the agent's browser read it, at stage 'create'. The SDK refuses
+ * that before any create, and the API refuses the same with 409 `amount_mismatch`, so a
+ * caller catches this one class either way; `amountSource` says whose number
+ * `actualCents` is, and the message names it.
  */
 export class AmountMismatchError extends ApprovalDeclinedError {
     authorizationId;
@@ -104,20 +141,27 @@ export class AmountMismatchError extends ApprovalDeclinedError {
     currency;
     actualCurrency;
     stage;
+    amountSource;
     code = 'amount_mismatch';
     constructor(
     /** The declined authorization, or null for a create-time refusal (no row exists). */
     authorizationId, 
     /** What the user was asked to approve, smallest currency unit. */
     expectedCents, 
-    /** What the processor reported at the last check. */
+    /** What the processor (or the merchant, see `amountSource`) reported at the last check. */
     actualCents, 
     /** ISO 4217 of the approved amount. */
     currency, 
     /** ISO 4217 the processor reported (differs only on a currency change). */
     actualCurrency = currency, 
     /** Which check refused it. */
-    stage = 'pre_replay') {
+    stage = 'pre_replay', 
+    /**
+     * Whose number `actualCents` is: the processor's ('processor'), a merchant-hosted
+     * merchant's own checkout total ('merchant_total'), or the amount its card request
+     * names ('merchant_request').
+     */
+    amountSource = 'processor') {
         super('amount_mismatch');
         this.authorizationId = authorizationId;
         this.expectedCents = expectedCents;
@@ -125,9 +169,12 @@ export class AmountMismatchError extends ApprovalDeclinedError {
         this.currency = currency;
         this.actualCurrency = actualCurrency;
         this.stage = stage;
+        this.amountSource = amountSource;
         this.name = 'AmountMismatchError';
+        const reported = amountSource === 'merchant_total' ? 'the merchant\'s own checkout total is'
+            : amountSource === 'merchant_request' ? 'the merchant\'s card request names' : 'the processor reports';
         this.message = `amount mismatch${authorizationId ? ` on ${authorizationId}` : ' at create'}: `
-            + `the user was asked to approve ${expectedCents} ${currency}, the processor reports ${actualCents} ${actualCurrency}. Nothing was charged.`;
+            + `the user was asked to approve ${expectedCents} ${currency}, ${reported} ${actualCents} ${actualCurrency}. Nothing was charged.`;
     }
 }
 /**
@@ -195,6 +242,69 @@ export class ProcessorRefusedError extends ApprovalDeclinedError {
         this.message = `the processor rejected the payment request on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Check the merchant payment status before retrying.`;
     }
 }
+const ADYEN_TEST_PLATFORM_REFUSALS = ['adyen_test_environment_refused', 'adyen_test_platform_requires_documented_test_card'];
+/**
+ * Agentcard refused a payment on Adyen's TEST platform, where a test account can
+ * read whatever is encrypted under its key. Nothing was encrypted and nothing was
+ * charged. `code` says which rule:
+ *   - 'adyen_test_environment_refused': a live checkout names Adyen's test host or
+ *     a `test_` client key. Stage 'create': the API refused it before anyone was
+ *     asked (`authorizationId` is null) and the page's next request is refused the
+ *     same way, so the adapters stop intercepting. Stage 'pre_replay': the
+ *     authorization was declined right before the card would have been encrypted.
+ *   - 'adyen_test_platform_requires_documented_test_card': a test-mode checkout on
+ *     Adyen's test platform, where the approval page encrypts only Adyen's
+ *     documented test cards and the cardholder's card is not one.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export class AdyenTestPlatformRefusedError extends ApprovalDeclinedError {
+    authorizationId;
+    code;
+    stage;
+    constructor(authorizationId, code, stage) {
+        super(code);
+        this.authorizationId = authorizationId;
+        this.code = code;
+        this.stage = stage;
+        this.name = 'AdyenTestPlatformRefusedError';
+        this.message = code === 'adyen_test_environment_refused'
+            ? `Adyen's test platform cannot take this live payment${authorizationId ? ` (${authorizationId} was declined)` : '; no authorization was created'}: the checkout names Adyen's test host or a test_ client key. Nothing was encrypted or charged.`
+            : `this checkout is on Adyen's test platform, which takes only Adyen's documented test cards${authorizationId ? ` (${authorizationId} was declined)` : ''}. Nothing was encrypted or charged.`;
+    }
+}
+/**
+ * A reviewed merchant's own checkout total could not stand behind this payment, so the
+ * card request was held and nothing was charged. The merchant's server picks what it
+ * charges, so a merchant-hosted payment is priced by the total the merchant's own
+ * checkout responses named in this browser (the profile's amount source), never by the
+ * agent's number alone. `code`:
+ *   - 'merchant_total_required': no total was sent (stage 'sdk': this runtime recorded no
+ *     merchant responses; stage 'create': the API got none);
+ *   - 'merchant_total_refused': the responses do not confirm one total for this order
+ *     (`reasonCode`: no_source when none was seen, stale, refused, unreadable,
+ *     mismatch, unbound, invalid); stage 'sdk' before any create, 'create' by the API;
+ *   - 'merchant_total_changed': stage 'release': between the approval and the moment the
+ *     card would have gone out, the merchant's total moved, or a request that could move
+ *     it had not answered. The approval is retired; the card never left this browser;
+ *   - 'merchant_total_stale': stage 'runtime': the approval came after the total was too
+ *     old for its profile, so the API withheld the card.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export class MerchantTotalError extends ApprovalDeclinedError {
+    authorizationId;
+    code;
+    stage;
+    reasonCode;
+    constructor(authorizationId, code, stage, reasonCode, reason) {
+        super(code);
+        this.authorizationId = authorizationId;
+        this.code = code;
+        this.stage = stage;
+        this.reasonCode = reasonCode;
+        this.name = 'MerchantTotalError';
+        this.message = `${reason}${authorizationId ? ` (${authorizationId})` : ''}. Nothing was charged.`;
+    }
+}
 /**
  * A non-2xx from the Agentcard API, carrying the status so callers can tell a
  * misconfiguration from a blip. The adapters use this to decide whether
@@ -364,6 +474,35 @@ export function redactUrl(raw) {
         return raw.split(/[?#]/)[0];
     }
 }
+/**
+ * Refusals a preparation create answers before any preparation exists, surfaced
+ * as CheckoutPreparationError reasons: Adyen's test platform on a live client, and
+ * a merchant profile Agentcard has not turned on, does not offer this account, or
+ * whose key or checkout page is not the one it reviewed.
+ */
+const PREPARATION_REFUSALS = [
+    'adyen_test_environment_refused', 'unsupported_checkout', 'merchant_profile_unavailable',
+    'merchant_profile_key_changed', 'unknown_merchant_profile', 'unsupported_payment_endpoint',
+    // A sandbox declaration from a live client or an org without declarations turned on,
+    // or one the API cannot pay (sandboxMerchants).
+    'sandbox_declaration_refused', 'sandbox_declaration_invalid',
+];
+/**
+ * Refusals a Fiserv preparation create answers (4xx) before any preparation exists, surfaced as
+ * the CheckoutPreparationError reason so the caller can tell them apart: the processor is
+ * not turned on for this company (`processor_unavailable`), Agentcard has not turned on
+ * payments to the merchant the key belongs to (`unsupported_checkout`), the merchant's
+ * published key is no longer the one Agentcard reviewed (`merchant_profile_key_changed`),
+ * or the key or environment named does not fit the request or the client's test or live
+ * mode. A 502 `cse_key_unavailable` (the merchant's published key could not be read just
+ * now; a new prepare() may pass) is surfaced the same way. Only for a Fiserv checkout;
+ * any other failure, and every other processor's refusal that PREPARATION_REFUSALS does
+ * not name, stays `preparation_unconfirmed`.
+ */
+const FISERV_PREPARATION_REFUSALS = [
+    'processor_unavailable', 'unsupported_checkout', 'merchant_profile_required', 'unknown_merchant_profile',
+    'merchant_profile_key_changed', 'fiserv_key_refused', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row',
+];
 /** Default backoff for a 502 amount_unverifiable at create: two retries, then give up. */
 const UNVERIFIABLE_RETRY_DELAYS_MS = [500, 1500];
 const PREPARATION_READ_RETRY_DELAYS_MS = [250, 500];
@@ -384,6 +523,13 @@ export class VaultClient {
     pollIntervalMs;
     unverifiableRetryDelaysMs;
     registry;
+    /**
+     * The reviewed merchant profiles this client arms: every one this build reviewed,
+     * in 'observe' until a sync reads that the API enabled it (armServedProfiles).
+     */
+    merchantProfiles = armServedProfiles();
+    /** This client's own sandbox declarations (sandboxMerchants), armed at construction, one per profile. */
+    declaredProfiles;
     preparations = new WeakSet();
     usedPreparations = new WeakSet();
     constructor(opts) {
@@ -393,6 +539,11 @@ export class VaultClient {
         this.registry = opts.registry ?? BUILTIN_REGISTRY;
         this.pollIntervalMs = opts.pollIntervalMs ?? 2000;
         this.unverifiableRetryDelaysMs = opts.unverifiableRetryDelaysMs ?? UNVERIFIABLE_RETRY_DELAYS_MS;
+        const declared = (opts.sandboxMerchants ?? []).map(declareSandboxMerchant);
+        if (new Set(declared.map((profile) => profile.id)).size !== declared.length) {
+            throw new TypeError('sandboxMerchants: declare each profile at most once.');
+        }
+        this.declaredProfiles = Object.freeze(declared);
     }
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     async syncRegistry() {
@@ -405,19 +556,59 @@ export class VaultClient {
         // abort, which would dead-end the checkout). `mode` rides through the
         // spread verbatim.
         let raw;
+        // ?capabilities= is the dark-launch half of the same negotiation: a
+        // processor gated behind a capability is served only when this build lists
+        // it. This build lists fiserv_card_capture, so it arms Fiserv's card capture
+        // for a company Agentcard turned Fiserv on for; an older build, and every
+        // other company's, never sees that recognizer.
+        const capabilities = SUPPORTED_CAPABILITIES.length ? `&capabilities=${SUPPORTED_CAPABILITIES.join(',')}` : '';
+        // merchant_profiles=1 asks for the reviewed Adyen merchant profiles too, each
+        // as a `{ merchant_profile }` entry after the recognizers; an API that
+        // predates them serves none. Every profile this build reviewed stays armed in
+        // 'observe' through a failed sync or an answer without profiles, and turns
+        // 'enabled' only when the API serves it enabled with this build's own rules
+        // (merchant-hosted.ts armServedProfiles).
         try {
-            raw = await this.get(`/v2/checkout/recognizers?modes=${SUPPORTED_MODES.join(',')}&features=${SUPPORTED_REGISTRY_FEATURES.join(',')}`);
+            raw = await this.get(`/v2/checkout/recognizers?modes=${SUPPORTED_MODES.join(',')}&features=${SUPPORTED_REGISTRY_FEATURES.join(',')}${capabilities}&merchant_profiles=1`);
         }
         catch {
             return;
         }
         if (!Array.isArray(raw))
             return;
-        this.registry = raw.map((e) => ({
+        const isProfile = (e) => !!e && typeof e === 'object' && 'merchant_profile' in e;
+        this.registry = raw.filter((e) => !isProfile(e)).map((e) => ({
             ...e,
             match: new RegExp(e.match, 'i'),
             passthroughHeaders: e.passthroughHeaders.map((h) => new RegExp(h, 'i')),
         }));
+        this.merchantProfiles = armServedProfiles(raw.filter(isProfile));
+    }
+    /**
+     * The reviewed Adyen merchant profile whose card endpoint (or a sibling of it,
+     * the same path under another query) this URL is, with its status on this
+     * client; null for any other URL. Every profile this build reviewed is armed,
+     * in 'observe' until a sync reads that the API enabled it. The adapters pause
+     * these requests and judge them with classifyMerchantRequest. A raw runtime
+     * that pauses one must never continue a card body there unless authorize()
+     * paid it.
+     */
+    merchantProfileOf(url) {
+        return merchantProfileFor([...this.declaredProfiles, ...this.merchantProfiles], url);
+    }
+    /** The armed profile with this id, or null. A profile id this client declared (sandboxMerchants) names its declaration, in place of the reviewed profile. */
+    merchantProfile(id) {
+        return this.declaredProfiles.find((profile) => profile.id === id)
+            ?? this.merchantProfiles.find((profile) => profile.id === id) ?? null;
+    }
+    /**
+     * Fetch.enable globs for every armed merchant profile's endpoint and its
+     * siblings, for a raw CDP runtime to arm beside cardUrlPatterns(). Every profile
+     * this build reviewed is armed from the start, so these are the same before and
+     * after syncRegistry; a sync changes only a profile's status.
+     */
+    merchantProfileUrlPatterns() {
+        return merchantProfileUrlPatterns([...this.declaredProfiles, ...this.merchantProfiles]);
     }
     /** True when this request is a card tokenization we can take over. */
     isCardRequest(url, method = 'POST') {
@@ -471,6 +662,35 @@ export class VaultClient {
         const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
         if (!validPreparationEnvironment(input.psp, input.environment))
             throw fail('unsupported_processor');
+        // A merchant-hosted preparation pays one reviewed profile's card request: the
+        // profile must be armed here, enabled, and paid in its own environment.
+        // A Fiserv checkout names the key Agentcard pinned for its merchant, in that key's own
+        // environment. The API then names that key's merchant on the approval, and the capture
+        // this preparation pays must carry an envelope under that key (matchesPreparation).
+        let profile = null;
+        let fiservPin = null;
+        if (input.psp === 'fiserv') {
+            if (input.merchantProfile === undefined)
+                throw fail('merchant_profile_required');
+            fiservPin = fiservKeyPinById(input.merchantProfile);
+            if (!fiservPin)
+                throw fail('unknown_merchant_profile');
+            if (fiservPin.environment !== input.environment)
+                throw fail('unsupported_processor');
+        }
+        else if (input.merchantProfile !== undefined) {
+            profile = typeof input.merchantProfile === 'string' ? this.merchantProfile(input.merchantProfile) : null;
+            if (input.psp !== 'adyen')
+                throw fail('unsupported_processor');
+            if (!profile)
+                throw fail('processor_interception_unavailable');
+            if (profile.status !== 'enabled')
+                throw fail('unsupported_checkout');
+            // A declared test endpoint pays on Adyen's TEST platform: a sandbox preparation.
+            if ((profile.sandboxDeclaration ? 'sandbox' : merchantProfileEnvironment(profile.id)) !== input.environment)
+                throw fail('unsupported_processor');
+        }
+        const declaration = profile?.sandboxDeclaration;
         if (!validAmountInput(input.amount) || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
             throw fail('amount_required');
         const origin = new URL(input.merchantOrigin);
@@ -478,6 +698,11 @@ export class VaultClient {
             throw fail('merchant_origin_invalid');
         if (!input.checkoutKey || !input.user || !input.merchant)
             throw fail('checkout_context_required');
+        // The cardholder approves a payment to the merchant the key pin belongs to, so a Fiserv
+        // checkout names that merchant as well: the approval, the handle this returns and every
+        // authorization it pays then name one merchant, never a label the caller chose.
+        if (fiservPin && input.merchant !== fiservPin.merchant)
+            throw fail('merchant_profile_mismatch');
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
         if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
             throw fail('timeout_invalid');
@@ -493,6 +718,9 @@ export class VaultClient {
                 user: input.user, merchant: input.merchant, amount: input.amount, currency: input.currency.toLowerCase(),
                 ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: preparationMode(input.psp),
                 environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
+                ...(profile ? { merchant_profile: profile.id } : {}),
+                ...(fiservPin ? { merchant_profile: fiservPin.id } : {}),
+                ...(declaration ? { sandbox_declaration: { endpoint: declaration.endpoint, client_key: declaration.clientKey, environment: 'test' } } : {}),
             }, AbortSignal.timeout(30_000), signal);
             if (!created || typeof created.id !== 'string' || !/^cprep_[A-Za-z0-9_-]{1,128}$/.test(created.id))
                 throw fail('create_unconfirmed');
@@ -520,7 +748,12 @@ export class VaultClient {
                     const expiry = Date.parse(state.ready_expires_at);
                     if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
                         || state.payment_status !== 'not_started' || state.amount_authority !== 'agent'
-                        || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
+                        // A merchant-hosted preparation names the merchant its reviewed profile names, and
+                        // a declared test endpoint names its host (declareSandboxMerchant), never the caller's label.
+                        // A Fiserv preparation names the merchant its key pin belongs to (input.merchant, checked above), and that pin.
+                        || state.user !== input.user || state.merchant !== (profile ? profile.merchant : input.merchant) || state.merchant_origin !== input.merchantOrigin
+                        || state.merchant_profile !== (profile ? profile.id : fiservPin ? fiservPin.id : undefined)
+                        || !servesDeclaration(state.sandbox_declaration, declaration)
                         || !Number.isSafeInteger(state.amount) || (typeof input.amount === 'number' && state.amount !== input.amount) || state.currency !== input.currency.toLowerCase()
                         || state.psp !== input.psp || state.mode !== preparationMode(input.psp) || state.environment !== input.environment
                         || state.checkout_key !== input.checkoutKey)
@@ -531,6 +764,9 @@ export class VaultClient {
                         amountDisplay: typeof state.amount_display === 'string' ? state.amount_display : null,
                         currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
                         paymentStatus: 'not_started', amountAuthority: 'agent',
+                        ...(profile ? { merchantProfile: profile.id } : {}),
+                        ...(fiservPin ? { merchantProfile: fiservPin.id } : {}),
+                        ...(declaration ? { sandboxDeclaration: declaration } : {}),
                     });
                     this.preparations.add(prepared);
                     ready = true;
@@ -545,6 +781,15 @@ export class VaultClient {
         catch (error) {
             if (error instanceof CheckoutPreparationError)
                 throw error;
+            // A refusal the API answered before any preparation existed names its rule: one
+            // PREPARATION_REFUSALS names for any checkout, and, for a Fiserv checkout only, one
+            // FISERV_PREPARATION_REFUSALS names or a 502 cse_key_unavailable. Every other
+            // processor's other refusals stay preparation_unconfirmed, as before.
+            if (!id && !signal.aborted && error instanceof CheckoutApiError && error.code
+                && ((error.status >= 400 && error.status < 500 && (PREPARATION_REFUSALS.includes(error.code)
+                    || (input.psp === 'fiserv' && FISERV_PREPARATION_REFUSALS.includes(error.code))))
+                    || (input.psp === 'fiserv' && error.status === 502 && error.code === 'cse_key_unavailable')))
+                throw fail(error.code);
             throw fail(signal.aborted ? 'cancelled' : 'preparation_unconfirmed', id);
         }
         finally {
@@ -637,14 +882,33 @@ export class VaultClient {
                 throw new CheckoutPreparationError(preparation.id, 'expired');
             if (input.user !== preparation.user || input.merchant !== preparation.merchant || (typeof input.amount === 'number' && input.amount !== preparation.amount) || (typeof input.amount === 'string' && !validAmountInput(input.amount))
                 || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
-                || !matchesPreparedRequest(preparation.psp, preparation.environment, input.request.url, input.request.method ?? 'POST', input.request.body, input.request.headers))
+                || !matchesPreparation(preparation, input.request.url, input.request.method ?? 'POST', input.request.body, input.request.headers))
                 throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
         }
         if (input.signal?.aborted)
             throw new CheckoutCancelledError();
         if (input.merchantSignal?.aborted)
             throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-        const rec = nativeCheckout ? this.registry.find(entry => entry.psp === 'stripe' && (entry.mode ?? 'token') === 'token')
+        // An armed merchant profile's endpoint (merchant-hosted.ts): the reviewed
+        // merchant's own server, never a processor host, so no recognizer matches it.
+        const merchantProfile = nativeCheckout || ownedShop || mercadoContext ? null : this.merchantProfileOf(input.request.url);
+        // A preparation pays the profile it was made for and nothing else: a
+        // merchant-hosted one never a processor's request or another profile's (two
+        // profiles could share an endpoint), and a processor-hosted one never a
+        // merchant's own endpoint. Checked here, not left to the matcher above, so the
+        // create below can only ever name the profile the cardholder prepared. A Fiserv
+        // preparation names a key pin, not a reviewed profile (matchesPreparation binds it).
+        if (preparation && (((preparation.psp === 'fiserv' ? null : preparation.merchantProfile) ?? null) !== (merchantProfile?.id ?? null)
+            || (preparation.sandboxDeclaration?.endpoint ?? null) !== (merchantProfile?.sandboxDeclaration?.endpoint ?? null))) {
+            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        }
+        // A profile a later sync holds in 'observe' no longer pays the preparation made for it.
+        if (preparation && merchantProfile && merchantProfile.status !== 'enabled') {
+            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        }
+        if (merchantProfile)
+            assertMerchantHostedRequest(input, merchantProfile);
+        const rec = merchantProfile ? MERCHANT_HOSTED_RECOGNIZER : nativeCheckout ? this.registry.find(entry => entry.psp === 'stripe' && (entry.mode ?? 'token') === 'token')
             : findRecognizer(input.request.url, this.registry);
         if (!rec)
             throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
@@ -655,6 +919,22 @@ export class VaultClient {
         const mode = rec.mode ?? 'token';
         if (preparation && (rec.psp !== preparation.psp || mode !== preparationMode(preparation.psp)))
             throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        // A preparation-required processor may not be taken over on an ordinary
+        // authorization: the cardholder must have approved a prepare() first. Refuse
+        // locally, before any create or prompt, when none is active, through the
+        // same strict rule the API applies (recognizerRequiresPreparation). Fiserv
+        // sets it; the API serves Fiserv only on a sync that declares its capability,
+        // and only to a company Agentcard turned Fiserv on for. This build carries
+        // Fiserv's own rules, so it also requires the preparation for a Fiserv
+        // request whatever the served entry says (requiresFiservPreparation): a
+        // registry that dropped the flag never opens an ordinary Fiserv authorization.
+        if ((recognizerRequiresPreparation(rec) || requiresFiservPreparation(rec.psp, input.request.url)) && !preparation)
+            throw new PreparationRequiredError(rec.psp);
+        // The merchant's server picks what it charges Adyen, so the agent's amount is
+        // what the API holds the body's own amount to: a merchant-hosted payment names one.
+        if (merchantProfile && input.amount == null) {
+            throw new Error(`A payment to ${merchantProfile.merchant} names its amount: pass amount and currency, the amount the cardholder approves.`);
+        }
         if (rec.clientSideEncrypted && mode !== 'cse')
             throw new CardEncryptedError(rec.psp);
         if (!SUPPORTED_MODES.includes(mode))
@@ -686,6 +966,10 @@ export class VaultClient {
         const deadline = Date.now() + timeoutMs;
         const timeoutSignal = AbortSignal.timeout(timeoutMs);
         const operationSignal = input.signal ? AbortSignal.any([input.signal, timeoutSignal]) : timeoutSignal;
+        // A reviewed profile priced by the merchant's own total: read it from what this browser
+        // recorded, and refuse before any create when it cannot stand behind this payment.
+        const priced = merchantProfile && merchantProfilePricedBySource(merchantProfile.id)
+            ? await this.readMerchantTotal(input, merchantProfile, preparation, operationSignal) : null;
         let created;
         const payload = {
             user: input.user,
@@ -704,6 +988,12 @@ export class VaultClient {
             ...(input.executionMode ? { execution_mode: input.executionMode } : {}),
             ...(input.grantId ? { grant_id: input.grantId } : {}),
             ...(input.merchantOrigin && !preparation ? { merchant_origin: input.merchantOrigin } : {}),
+            // Only the profile's id: the API takes the key, its environment and where
+            // the card goes from the profile Agentcard reviewed, never from the caller.
+            ...(merchantProfile ? { merchant_hosted: { profile: merchantProfile.id, ...(merchantProfile.sandboxDeclaration ? { sandbox_declaration: {
+                            endpoint: merchantProfile.sandboxDeclaration.endpoint, client_key: merchantProfile.sandboxDeclaration.clientKey, environment: 'test'
+                        } } : {}),
+                    ...(priced ? { merchant_total: priced.wire } : {}) } } : {}),
             // A prepared checkout already carries the page origin as merchant_origin.
             ...(preparation
                 ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin, form_guidance: 'filled' }
@@ -831,6 +1121,13 @@ export class VaultClient {
                 const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
                     ? { amountAuthority: s.amount_authority }
                     : {};
+                // A merchant-hosted create finishes only as a cse approval: the API's
+                // database forces these rows to cse. A finished read in any other mode
+                // (token, a missing mode, a hosted form) is not one to act on, and never
+                // reaches the code that would answer the merchant's paused request with it.
+                if (merchantProfile && (s.status === 'approved' || s.status === 'submitted_on_device') && s.mode !== 'cse') {
+                    throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_hosted_mode_invalid');
+                }
                 if (s.status === 'submitted_on_device') {
                     // The device attested that the processor's form left it; the stamp
                     // is the whole fact and it is NOT an approval (see HostedFormReplay).
@@ -858,12 +1155,27 @@ export class VaultClient {
                     if (approvedMode === 'cse') {
                         if (execution.executionMode === 'autopilot')
                             throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
+                        // A merchant-hosted create reads back only a merchant-hosted approval,
+                        // and a processor-hosted one never does.
+                        if (merchantProfile || (s.substitutions && typeof s.substitutions === 'object' && 'kind' in s.substitutions)) {
+                            return { ...merchantHostedApproval(s, authorizationId, merchantProfile), ...(priced ? { merchantTotal: priced.approved } : {}),
+                                ...amountAuthority, ...execution };
+                        }
+                        // The API serves a Fiserv envelope only briefly after the approval (it carries
+                        // no timestamp, so whoever holds it could resubmit it). A read after that
+                        // window says so instead of serving it; the capture was never continued here.
+                        if (s.substitutions_expired === true)
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_expired');
                         const sub = s.substitutions;
                         const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
                             && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
                             && Object.values(sub.fields).every((v) => typeof v === 'string' && v.length > 0);
                         if (!fieldsOk)
                             throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
+                        // A Fiserv approval carries exactly its envelope's four members at
+                        // source.encryptionData and removes nothing (fiserv.ts); any other shape is not one to act on.
+                        if (rec.psp === 'fiserv' && !isFiservSubstitution(sub))
+                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
                         // `remove`: sibling keys the API says to drop with the swap (Adyen's
                         // `brand`, stamped by adyen-web from the agent's dummy digits). Absent
                         // on an older API; anything but a list of names is refused, since a
@@ -950,6 +1262,9 @@ export class VaultClient {
                     }
                     if (s.reason === 'intent_not_confirmable')
                         throw new IntentNotConfirmableError(String(created.id));
+                    if (typeof s.reason === 'string' && ADYEN_TEST_PLATFORM_REFUSALS.includes(s.reason)) {
+                        throw new AdyenTestPlatformRefusedError(String(created.id), s.reason, 'pre_replay');
+                    }
                     if (typeof s.reason === 'string' && PRESET_REFUSAL_REASONS.has(s.reason)) {
                         throw new PresetRefusedError(String(created.id), s.reason, typeof s.message === 'string' ? s.message : null, presetOf(s.preset), typeof s.rule === 'string' ? s.rule : null, 'pre_replay', attachmentOf(s.attachment), refusalsOf(s.refusals));
                     }
@@ -1071,6 +1386,67 @@ export class VaultClient {
         }
         return { paymentIntentId: pi.id, amount: pi.amount, currency: pi.currency };
     }
+    /**
+     * After a merchant-hosted payment priced by the merchant's own total: what the merchant's
+     * confirmation says it charged (merchant-total.ts merchantChargeReport builds `report`
+     * from the responses this browser recorded after the card request). The API compares it
+     * with the approved amount and alerts Agentcard once when the merchant charged more, or
+     * in another currency. The adapters send it on their own; the verdict is 'equal',
+     * 'lower', 'higher', 'currency_mismatch', or 'unread' when no response read.
+     */
+    async reportMerchantCharge(authorizationId, report) {
+        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
+            throw new Error('Invalid authorization ID.');
+        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/merchant_charge`, report, AbortSignal.timeout(10_000));
+        const verdict = result?.verdict;
+        if (result?.authorization_id !== authorizationId || !['equal', 'lower', 'higher', 'currency_mismatch', 'unread'].includes(verdict)) {
+            throw new Error('The merchant charge report was not acknowledged.');
+        }
+        return { verdict, alerted: result.alerted === true };
+    }
+    /**
+     * The merchant's own total for a paused card request whose reviewed profile is priced by
+     * one: the exchanges the adapter recorded (once every request that can move the total has
+     * answered), cut to what the profile's rules read, and the same reading the API makes.
+     * Refused with a MerchantTotalError before any create when nothing recorded them, one is
+     * still unanswered, or they do not confirm one total for this order.
+     */
+    async readMerchantTotal(input, profile, preparation, signal) {
+        const refuse = (code, reasonCode, reason) => new MerchantTotalError(null, code, 'sdk', reasonCode, reason);
+        const capture = input.merchantTotal;
+        if (!capture || typeof capture.exchanges !== 'function' || typeof capture.pausedAt !== 'number' || !Number.isFinite(capture.pausedAt)) {
+            throw refuse('merchant_total_required', null, `${profile.merchant}'s own total is read from its checkout's responses, and this runtime recorded none`);
+        }
+        const checkoutOrigin = preparation?.merchantOrigin ?? input.pageOrigin;
+        const card = {
+            url: input.request.url, method: (input.request.method ?? 'POST').toUpperCase(), body: input.request.body, pausedAt: capture.pausedAt,
+            ...(checkoutOrigin ? { checkoutOrigin } : {}), ...(capture.page ? { page: capture.page } : {}),
+            ...(profile.sandboxDeclaration ? { declaredEndpoint: profile.sandboxDeclaration.endpoint } : {}),
+        };
+        let seen;
+        try {
+            seen = await capture.exchanges(profile.id, 'source', card, signal);
+        }
+        catch (error) {
+            if (error instanceof MerchantTotalWait)
+                throw refuse('merchant_total_refused', 'stale', `${profile.merchant}'s total is not known: ${error.message}`);
+            throw error;
+        }
+        const sent = merchantAmountExchanges(profile.id, 'source', { card, responses: seen });
+        if (!sent.ok)
+            throw refuse('merchant_total_refused', sent.code, `Refusing to pay ${profile.merchant}: ${sent.reason}`);
+        const read = merchantAmountFromResponses(profile.id, { card, responses: sent.responses });
+        if (!read.ok)
+            throw refuse('merchant_total_refused', read.code, `Refusing to pay ${profile.merchant}: ${read.reason}`);
+        // The agent's number is held to the merchant's before anyone is asked. An integer amount is
+        // compared here; a decimal string is left to the API, which reads it in the currency's units.
+        if (typeof input.amount === 'number' && typeof input.currency === 'string'
+            && (input.amount !== read.amount.amount || input.currency.toLowerCase() !== read.amount.currency.toLowerCase())) {
+            // The same typed refusal the API's 409 amount_mismatch becomes, naming the merchant's total.
+            throw new AmountMismatchError(null, input.amount, read.amount.amount, input.currency.toLowerCase(), read.amount.currency, 'create', 'merchant_total');
+        }
+        return { wire: merchantTotalWire(capture.pausedAt, capture.page, sent.responses), approved: { card, amount: read.amount } };
+    }
     /**
      * POST the create, with two typed twists: a 502 `amount_unverifiable`
      * (Stripe did not answer the read-back) is retried on a short backoff
@@ -1091,9 +1467,21 @@ export class VaultClient {
                     const d = err.details;
                     throw new PresetRefusedError(null, err.code, typeof d.message === 'string' ? d.message : null, presetOf(d.preset), typeof d.rule === 'string' ? d.rule : null, 'create', attachmentOf(d.attachment), refusalsOf(d.refusals));
                 }
+                if (err instanceof CheckoutApiError && err.status === 400 && err.code === 'adyen_test_environment_refused') {
+                    // A live checkout named Adyen's test host or a test_ key: refused before anyone was asked.
+                    throw new AdyenTestPlatformRefusedError(null, 'adyen_test_environment_refused', 'create');
+                }
                 if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
                     const d = err.details;
-                    throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create');
+                    throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create', 
+                    // A merchant-hosted refusal names the merchant amount it held the agent's to:
+                    // its card request's own ('body') or its checkout total (an amount source's id).
+                    typeof d.amount_source === 'string' ? (d.amount_source === 'body' ? 'merchant_request' : 'merchant_total') : 'processor');
+                }
+                if (err instanceof CheckoutApiError && err.status === 409 && (err.code === 'merchant_total_required' || err.code === 'merchant_total_refused')) {
+                    // The API could not confirm the merchant's own total for this order: no row exists.
+                    const d = err.details;
+                    throw new MerchantTotalError(null, err.code, 'create', typeof d.reason_code === 'string' ? d.reason_code : null, typeof d.reason === 'string' ? `Agentcard could not confirm the merchant's own total: ${d.reason}` : err.message);
                 }
                 // Two 502s the API asks to be retried: Stripe did not answer the
                 // amount read-back, or Adyen did not answer the public-key fetch.
@@ -1212,6 +1600,121 @@ function executionMetadata(state, authorizationId, previous = {}) {
         throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_grant_changed');
     return { executionMode: 'autopilot', grantId: state.grant_id };
 }
+/**
+ * What authorize() creates a merchant-hosted authorization as: an Adyen cse
+ * payment that only a prepared checkout may make (so an unprepared request is
+ * refused locally with PreparationRequiredError, before any create), forwarding
+ * no header but content-type. Never matched against a URL: authorize() uses it
+ * only for an armed profile's endpoint.
+ */
+const MERCHANT_HOSTED_RECOGNIZER = Object.freeze({
+    psp: 'adyen', match: /(?!)/, encoding: 'json', passthroughHeaders: [],
+    clientSideEncrypted: true, mode: 'cse', preparationRequired: true,
+});
+/**
+ * Refuse, before any create or prompt, a merchant-hosted request this client
+ * cannot pay: a profile Agentcard has not turned on (observe), Autopilot (the
+ * cardholder approves every one), or a request the profile's rules do not pause
+ * (anything but its reviewed card request).
+ */
+function assertMerchantHostedRequest(input, profile) {
+    if (profile.status !== 'enabled') {
+        throw new Error(`Agentcard has not turned on payments to ${profile.merchant} yet. Nothing was charged.`);
+    }
+    if (input.executionMode === 'autopilot' || input.grantId !== undefined) {
+        throw new Error(`A payment to ${profile.merchant} needs the cardholder's approval every time; Autopilot cannot pay it.`);
+    }
+    const verdict = classifyProfileRequest(profile, input.request.url, input.request.method ?? 'POST', input.request.body);
+    if (verdict.verdict === 'abort')
+        throw new Error(`Refusing to pay ${profile.merchant}: ${verdict.reason}. Nothing was charged.`);
+    if (verdict.verdict === 'pass')
+        throw new Error(`not a card request Agentcard reviewed for ${profile.merchant}.`);
+}
+const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const FORBIDDEN_STEPS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * Whether a served preparation names the sandbox declaration this client sent:
+ * its endpoint, client key and the test environment, with the public key's
+ * SHA-256 the API read. Neither side naming one also matches.
+ */
+function servesDeclaration(served, declaration) {
+    if (!declaration)
+        return served === undefined;
+    return isRecord(served) && served.endpoint === declaration.endpoint && served.client_key === declaration.clientKey
+        && served.environment === 'test' && typeof served.public_key_sha256 === 'string' && /^[0-9a-f]{64}$/.test(served.public_key_sha256);
+}
+/** A served JSON path: object keys and array indices, `[]` for the body root; null for anything else. */
+function jsonPathOf(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        return null;
+    const ok = value.every((step) => (typeof step === 'string' && step.length > 0 && !FORBIDDEN_STEPS.has(step))
+        || (typeof step === 'number' && Number.isSafeInteger(step) && step >= 0));
+    return ok ? [...value] : null;
+}
+/** Served card facts: a list of {path, value}; null when anything in it is not one. */
+function factsOf(value) {
+    if (!Array.isArray(value))
+        return null;
+    const facts = [];
+    for (const fact of value) {
+        if (!isRecord(fact) || Object.keys(fact).some((key) => key !== 'path' && key !== 'value'))
+            return null;
+        const path = jsonPathOf(fact.path);
+        if (!path || typeof fact.value !== 'string')
+            return null;
+        facts.push({ path, value: fact.value });
+    }
+    return facts;
+}
+const MERCHANT_HOSTED_SUBSTITUTION_MEMBERS = new Set(['encoding', 'kind', 'profile', 'path', 'fields', 'remove', 'set']);
+/**
+ * The approved read of a merchant-hosted authorization, as the replay the
+ * adapters continue: the profile's substitution (`kind: 'merchant_hosted'`, a
+ * holder path that may be the root `[]`, the merchant's four field names with
+ * their ciphertext, the keys to drop and any card facts to `set`), and beside it
+ * the profile and the SHA-256 of the body the API checked at create. Anything
+ * else, a create that was not merchant-hosted, another profile, or a set the API
+ * no longer serves (`substitutions_expired`) is an unknown outcome: the device may
+ * already have encrypted the card, and nothing here can pay with it.
+ */
+function merchantHostedApproval(s, authorizationId, profile) {
+    const malformed = () => new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
+    if (!profile)
+        throw malformed();
+    // The API withheld the card because the merchant's total was too old when the cardholder
+    // approved: nothing was encrypted into any request, so this is a refusal, not an unknown.
+    if (s.merchant_total_stale === true) {
+        throw new MerchantTotalError(authorizationId, 'merchant_total_stale', 'runtime', 'stale', `The approval came after ${profile.merchant}'s total was too old for its profile, so Agentcard withheld the card`);
+    }
+    if (s.substitutions_expired === true)
+        throw new PaymentOutcomeUnknownError(authorizationId, 'substitutions_expired');
+    const sub = s.substitutions;
+    const served = s.merchant_hosted;
+    if (!isRecord(sub) || sub.encoding !== 'json' || sub.kind !== 'merchant_hosted' || sub.profile !== profile.id
+        || Object.keys(sub).some((member) => !MERCHANT_HOSTED_SUBSTITUTION_MEMBERS.has(member)))
+        throw malformed();
+    if (!isRecord(served) || served.profile !== profile.id || typeof served.body_sha256 !== 'string'
+        || !/^[0-9a-f]{64}$/.test(served.body_sha256))
+        throw malformed();
+    const path = jsonPathOf(sub.path);
+    const fields = isRecord(sub.fields) && Object.keys(sub.fields).length > 0
+        && Object.values(sub.fields).every((value) => typeof value === 'string' && value.length > 0) ? { ...sub.fields } : null;
+    const remove = sub.remove === undefined ? [] : Array.isArray(sub.remove) && sub.remove.every((key) => typeof key === 'string' && key.length > 0)
+        ? [...sub.remove] : null;
+    const set = sub.set === undefined ? [] : factsOf(sub.set);
+    if (!path || !fields || !remove || !set)
+        throw malformed();
+    return {
+        mode: 'cse',
+        kind: 'merchant_hosted',
+        authorizationId,
+        profile: profile.id,
+        substitutions: { encoding: 'json', kind: 'merchant_hosted', profile: profile.id, path, fields, remove, ...(set.length ? { set } : {}) },
+        bodySha256: served.body_sha256,
+        substitutionsExpiresAt: typeof s.substitutions_expires_at === 'string' ? s.substitutions_expires_at : null,
+        ...(profile.sandboxDeclaration ? { sandboxDeclaration: profile.sandboxDeclaration } : {}),
+    };
+}
 /**
  * Forward only the headers the merchant needs to accept the replay. Everything
  * else (cookies, UA, tracing) is dropped so we transmit as little as possible.