@agent-cards/sdk 0.22.0 → 0.23.1

package/dist/client.d.ts

@@ -9,8 +9,9 @@ import { VoiceModule, type VoiceOptions } from './voice.js';
 import { BuyModule } from './buy.js';
 import { RequestRegistry } from './requests.js';
 import type { ApiTransport } from './api-module.js';
-import { type MicroformSidecar } from './cybersource-flex.js';
+import { type MicroformField, type MicroformSidecar } from './cybersource-flex.js';
 import { type CardEndpointSession } from './card-endpoint.js';
+import type { CardEndpointFactsRecord } from './card-endpoint-facts.js';
 import { type PayrailsSidecar } from './payrails.js';
 export interface PausedRequest {
     url: string;
@@ -29,12 +30,15 @@ export interface PausedRequest {
     microform?: MicroformSidecar;
     /**
      * A reviewed merchant's own card endpoint (see card-endpoint.ts): the profile and the
-     * paused request's session, which the adapters capture. Cardholder data: it travels
-     * only in the create's `merchant_card_endpoint` member, never in `request`.
+     * paused request's session, which the adapters capture, and, for a merchant that keeps
+     * its own record of the order, that record as the adapters read it from the page, cut
+     * to the values payment-core's reader reads (card-endpoint-facts.ts). Cardholder data:
+     * it travels only in the create's `merchant_card_endpoint` member, never in `request`.
      */
     merchant_card_endpoint?: {
         profile: string;
         session: CardEndpointSession;
+        facts?: CardEndpointFactsRecord;
     };
     /**
      * A Payrails card save (mode device_encrypt) only: the session key the page's
@@ -169,6 +173,9 @@ export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
  * verifone.js blob sent to the merchant's server), which this build pauses and pays
  * only through a prepared checkout (verifone.ts); the API serves the Verifone
  * profiles only to a build that lists it, for a company Agentcard turned Verifone on for.
+ * `ekashu_hosted_payment_page`: NMI's hosted payment page, whose card-free entry this
+ * build pauses for the cardholder's device and whose card page this build never lets
+ * the agent's browser post to (pre-claim.ts, ekashu.ts); served on the same terms.
  */
 export declare const SUPPORTED_CAPABILITIES: readonly string[];
 /**
@@ -364,11 +371,12 @@ export interface HostedFormReplay extends ExecutionMetadata {
  * `setCookies` written into the agent's browser on the endpoint host, or on the parent
  * domain of a cookie the browser already holds there, which the write replaces.
  *
- * `withheld` is set when the device found the card in the answer, or a compressed
- * stream it cannot read: nothing of the answer travels, the adapters answer the paused
- * request with a fixed error, and the outcome is unknown until the merchant order is
- * checked. The card request was sent either way. Amounts are not reconciled on this
- * mode: the agent's amount is the only authority.
+ * `withheld` is set when the device found the card in the answer, a compressed
+ * stream it cannot read, or a step the review refuses (FastSpring's EBANX step): nothing
+ * of the answer travels, the adapters answer the paused request with a fixed error, and
+ * the outcome is unknown until the merchant order is checked. The card request was sent
+ * either way. Amounts are not reconciled on this mode: the agent's amount is the only
+ * authority, held before the create to the merchant's own total where its page keeps one.
  */
 export interface CardEndpointReplay extends ExecutionMetadata {
     mode: 'card_endpoint';
@@ -380,7 +388,7 @@ export interface CardEndpointReplay extends ExecutionMetadata {
     headers: Record<string, string>;
     setCookies: string[];
     body: string;
-    withheld: 'card_in_response' | 'unreadable_in_response' | null;
+    withheld: 'card_in_response' | 'unreadable_in_response' | 'refused_step_in_response' | null;
     amountAuthority?: AmountAuthority;
 }
 /**
@@ -448,8 +456,25 @@ export interface PrepareCheckoutOptions {
      * processor.
      */
     paypageId?: string;
+    /**
+     * CyberSource Flex only: the cardholder's device tokenizes the card when it approves, before
+     * Pay, under the capture context of the card fields the page already loaded, so the page's
+     * createToken is answered at once. For a page that gives createToken only seconds (Alaska
+     * Airlines' flight checkout gives it three). Call prepare() once the card fields show; the
+     * attachment reads their capture context and fields and refuses with `microform_not_loaded`,
+     * `microform_ambiguous` or `microform_unsupported` when it cannot.
+     */
+    tokenizeBeforePay?: boolean;
     signal?: AbortSignal;
 }
+/** A CyberSource Flex preparation that tokenizes before Pay: the loaded card field's capture context and fields. */
+export interface PreparedCybersourceFlex {
+    captureContext: string;
+    microform: {
+        version: string;
+        fields: MicroformField[];
+    };
+}
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
     user: string;
     merchant: string;
@@ -462,6 +487,12 @@ export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
     timeoutMs?: number;
     onPreparationCreated?: (id: string) => void;
     onApprovalUrl?: (url: string) => void;
+    /**
+     * CyberSource Flex, tokenized before Pay: the capture context and fields of the card Microform
+     * the page loaded (the attachments read them for prepare({ tokenizeBeforePay: true })). Verified
+     * here and by the API before any preparation exists.
+     */
+    cybersourceFlex?: PreparedCybersourceFlex;
 }
 /** Real user consent and an unlocked device; no processor request or payment yet. */
 export interface PreparedCheckout {
@@ -494,6 +525,18 @@ export interface PreparedCheckout {
     readonly paymentPageUrl?: string;
     /** Worldpay eProtect only: the paypageId the API confirmed, the one merchant whose registration may spend this approval. */
     readonly paypageId?: string;
+    /**
+     * CyberSource Flex, tokenized before Pay: the capture context and fields the cardholder's device
+     * tokenized the card under. Only a field request loaded under this context, with these fields,
+     * binds this preparation.
+     */
+    readonly cybersourceFlex?: Readonly<{
+        captureContext: string;
+        microform: Readonly<{
+            version: string;
+            fields: readonly MicroformField[];
+        }>;
+    }>;
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
@@ -703,6 +746,15 @@ export declare const RUNTIME_CANCEL_REASONS: readonly RuntimeCancelReason[];
 export declare class PaymentOutcomeUnknownError extends Error {
     authorizationId: string | null;
     reason: string;
+    /**
+     * False when the API confirmed it retired this authorization before any processor
+     * request started: authorize() cancels an authorization it could not finish (a card
+     * endpoint, a prepared or a native checkout, or a request the page abandoned), and the
+     * cancel came back with `processor_request_started: false`, so nothing reached the
+     * processor or the merchant. Null when that is not known. The controller still reads
+     * `outcome_unknown`; a card form navigation's page reads this to say nothing was sent.
+     */
+    processorRequestStarted: false | null;
     constructor(authorizationId: string | null, reason: string);
 }
 export declare class ApprovalDeclinedError extends Error {

package/dist/client.js

@@ -21,10 +21,11 @@ import { Languages } from './languages.js';
 import { RequestRegistry } from './requests.js';
 import { AgentcardError } from './voice-types.js';
 import { GMO_CAPABILITY, GMO_PSP, gmoTokenAnswer } from './gmo.js';
-import { isCybersourceFlexTokenShape } from './cybersource-flex.generated.js';
-import { CYBERSOURCE_FLEX_CAPABILITY, CYBERSOURCE_FLEX_PSP, validCybersourceFlexSidecar } from './cybersource-flex.js';
+import { admitCybersourceFlexPreparation, isCybersourceFlexTokenShape, sameCybersourceFlexPreparation } from './cybersource-flex.generated.js';
+import { CYBERSOURCE_FLEX_CAPABILITY, CYBERSOURCE_FLEX_PSP, validCybersourceFlexSidecar, } from './cybersource-flex.js';
 import { JUSPAY_CAPABILITY, JUSPAY_PSP, juspayPageAnswer } from './juspay-gate.js';
 import { CARD_ENDPOINT_MODE, CARD_ENDPOINT_PSP, CardEndpointRefusedError, cardEndpointById, cardEndpointLive, cardEndpointSessionRefusal, } from './card-endpoint.js';
+import { merchantCardEndpointFactsRefusal as sharedFactsRefusal, readMerchantCardEndpointFacts as sharedReadFacts, } from './merchant-card-endpoints.generated.js';
 import { DATATRANS_CAPABILITY } from './datatrans.js';
 import { PELECARD_CAPABILITY, PELECARD_PSP } from './pelecard.js';
 import { PRIMER_CAPABILITY, PRIMER_PSP, primerTokenAnswer } from './primer.js';
@@ -154,8 +155,11 @@ export const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
  * verifone.js blob sent to the merchant's server), which this build pauses and pays
  * only through a prepared checkout (verifone.ts); the API serves the Verifone
  * profiles only to a build that lists it, for a company Agentcard turned Verifone on for.
+ * `ekashu_hosted_payment_page`: NMI's hosted payment page, whose card-free entry this
+ * build pauses for the cardholder's device and whose card page this build never lets
+ * the agent's browser post to (pre-claim.ts, ekashu.ts); served on the same terms.
  */
-export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture'];
+export const SUPPORTED_CAPABILITIES = ['fiserv_card_capture', GMO_CAPABILITY, CYBERSOURCE_FLEX_CAPABILITY, JUSPAY_CAPABILITY, DATATRANS_CAPABILITY, 'authorize_net_dpm_form', PELECARD_CAPABILITY, ACI_CAPABILITY, 'creditguard_pps_process', PRIMER_CAPABILITY, PAYRAILS_CAPABILITY, CONVERGE_CAPABILITY, EPROTECT_CAPABILITY, WSPAY_CAPABILITY, SHIJI_STS_CAPABILITY, AMADEUS_CHECKOUT_CAPABILITY, 'worldline_mycheckout_form', 'verifone_card_capture', 'ekashu_hosted_payment_page'];
 /**
  * Processors whose paused request names no amount at all, so the pair the
  * agent passes is the amount the cardholder approves: authorize() refuses one
@@ -436,6 +440,15 @@ export const RUNTIME_CANCEL_REASONS = ['merchant_request_aborted', 'merchant_nev
 export class PaymentOutcomeUnknownError extends Error {
     authorizationId;
     reason;
+    /**
+     * False when the API confirmed it retired this authorization before any processor
+     * request started: authorize() cancels an authorization it could not finish (a card
+     * endpoint, a prepared or a native checkout, or a request the page abandoned), and the
+     * cancel came back with `processor_request_started: false`, so nothing reached the
+     * processor or the merchant. Null when that is not known. The controller still reads
+     * `outcome_unknown`; a card form navigation's page reads this to say nothing was sent.
+     */
+    processorRequestStarted = null;
     constructor(authorizationId, reason) {
         super(`payment outcome unknown${authorizationId ? ` for ${authorizationId}` : ''}: ${reason}; check the merchant order before retrying`);
         this.authorizationId = authorizationId;
@@ -919,6 +932,26 @@ const FISERV_PREPARATION_REFUSALS = [
  * holds that pin). Only for an eProtect checkout.
  */
 const EPROTECT_PREPARATION_REFUSALS = ['merchant_profile_mismatch'];
+/**
+ * Refusals a CyberSource Flex preparation that tokenizes before Pay answers (4xx) before any
+ * preparation exists, surfaced as the CheckoutPreparationError reason: the processor is off for
+ * this company (`processor_unavailable`), the environment is not the client's mode, or the capture
+ * context or fields read from the page cannot be verified or rebuilt. Only for such a preparation;
+ * a Flex preparation without a capture context keeps `preparation_unconfirmed`, as before.
+ */
+const CYBERSOURCE_FLEX_PREPARATION_REFUSALS = [
+    'processor_unavailable', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row', 'capture_context_invalid', 'microform_unsupported',
+    'cybersource_environment_mismatch',
+];
+/** Why payment-core refused a Flex preparation's capture context or fields, as a CheckoutPreparationError reason. */
+function cybersourceFlexPreparationRefusal(error) {
+    const reason = error?.reason;
+    if (reason === 'microform_version' || reason === 'fields')
+        return 'microform_unsupported';
+    if (reason === 'environment_mismatch')
+        return 'cybersource_environment_mismatch';
+    return 'capture_context_invalid';
+}
 /** 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];
@@ -1370,6 +1403,25 @@ export class VaultClient {
             throw fail('paypage_id_invalid');
         if (eprotect && !input.cardId)
             throw fail('card_required');
+        // CyberSource Flex, tokenized before Pay: the loaded card field's capture context and fields,
+        // verified here against the keys payment-core pins before anything is created (the API and the
+        // cardholder's device verify them again).
+        if (input.tokenizeBeforePay !== undefined && typeof input.tokenizeBeforePay !== 'boolean')
+            throw fail('tokenize_before_pay_invalid');
+        const flexContext = input.cybersourceFlex;
+        if (input.tokenizeBeforePay === true && !flexContext)
+            throw fail('microform_not_loaded');
+        if (flexContext) {
+            if (input.psp !== CYBERSOURCE_FLEX_PSP)
+                throw fail('unsupported_processor');
+            try {
+                await admitCybersourceFlexPreparation({ capture_context: flexContext.captureContext,
+                    microform: { version: flexContext.microform.version, fields: [...flexContext.microform.fields] }, environment: input.environment }, { crypto: globalThis.crypto });
+            }
+            catch (error) {
+                throw fail(cybersourceFlexPreparationRefusal(error));
+            }
+        }
         if (!validAmountInput(input.amount) || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency)) {
             throw new CheckoutPreparationError(null, 'amount_required', undefined, input.amount != null && !validAmountInput(input.amount) ? amountRefusal(input.amount, input.currency) : undefined);
         }
@@ -1417,6 +1469,8 @@ export class VaultClient {
                 ...(declaration ? { sandbox_declaration: { endpoint: declaration.endpoint, client_key: declaration.clientKey, environment: 'test' } } : {}),
                 ...(input.psp === 'creditguard' ? { payment_page_url: input.paymentPageUrl } : {}),
                 ...(eprotect ? { paypage_id: input.paypageId } : {}),
+                ...(flexContext ? { capture_context: flexContext.captureContext,
+                    microform: { version: flexContext.microform.version, fields: [...flexContext.microform.fields] } } : {}),
             }, 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');
@@ -1456,7 +1510,9 @@ export class VaultClient {
                         || state.psp !== input.psp || state.mode !== preparationMode(input.psp) || state.environment !== input.environment
                         || state.checkout_key !== input.checkoutKey
                         // eProtect: the merchant and the card the cardholder approved are the ones asked for.
-                        || (eprotect && (state.paypage_id !== input.paypageId || state.card_id !== input.cardId)))
+                        || (eprotect && (state.paypage_id !== input.paypageId || state.card_id !== input.cardId))
+                        // The API says a preparation tokenizes before Pay exactly when this one carried a capture context.
+                        || (state.tokenize_before_pay === true) !== !!flexContext)
                         throw fail('ready_unconfirmed', id);
                     const prepared = Object.freeze({
                         id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, mode: preparationMode(input.psp), expiresAt: state.ready_expires_at,
@@ -1470,6 +1526,8 @@ export class VaultClient {
                         ...(declaration ? { sandboxDeclaration: declaration } : {}),
                         ...(input.psp === 'creditguard' ? { paymentPageUrl: input.paymentPageUrl } : {}),
                         ...(eprotect ? { paypageId: input.paypageId } : {}),
+                        ...(flexContext ? { cybersourceFlex: Object.freeze({ captureContext: flexContext.captureContext,
+                                microform: Object.freeze({ version: flexContext.microform.version, fields: Object.freeze([...flexContext.microform.fields]) }) }) } : {}),
                     });
                     this.preparations.add(prepared);
                     ready = true;
@@ -1494,7 +1552,8 @@ export class VaultClient {
             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 === EPROTECT_PSP && EPROTECT_PREPARATION_REFUSALS.includes(error.code))))
+                    || (input.psp === EPROTECT_PSP && EPROTECT_PREPARATION_REFUSALS.includes(error.code))
+                    || (!!flexContext && CYBERSOURCE_FLEX_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);
@@ -1717,6 +1776,11 @@ export class VaultClient {
         if (mode === 'device_encrypt' && (!sidecar || typeof sidecar.encryption_public_key !== 'string' || !sidecar.encryption_public_key)) {
             throw new Error('A Payrails card save needs request.payrails.encryption_public_key, the session key from the checkout\'s Payrails init payload (the adapters capture it). Nothing was created.');
         }
+        // A preparation that tokenized before Pay pays only a field request loaded under the capture
+        // context and fields its cardholder approved: the device holds CyberSource's token for that context.
+        if (preparation?.cybersourceFlex && !(flex && sameCybersourceFlexPreparation({ capture_context: preparation.cybersourceFlex.captureContext, microform: preparation.cybersourceFlex.microform }, { capture_context: input.request.capture_context, microform: input.request.microform }))) {
+            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
+        }
         // Say no rather than coerce. Each recognizer's card request has exactly one
         // method (recognizerRequestMethod): a POST body, or for Worldpay eProtect the
         // GET whose query carries the card. The service stores the replay template
@@ -1791,7 +1855,7 @@ export class VaultClient {
             execution_mode: 'user_approval',
             checkout_origin: cardEndpoint.session.page_origin,
             request: { url: cardEndpoint.session.url, method: 'POST', headers: {}, body: '' },
-            merchant_card_endpoint: { profile: cardEndpoint.profile, session: cardEndpoint.session },
+            merchant_card_endpoint: { profile: cardEndpoint.profile, session: cardEndpoint.session, ...(cardEndpoint.facts ? { facts: cardEndpoint.facts } : {}) },
         } : {
             user: input.user,
             merchant: input.merchant,
@@ -1882,6 +1946,13 @@ export class VaultClient {
         // registration is read every 500 ms instead of waiting out 2 seconds.
         const preparedFastPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000
             : preparation?.psp === EPROTECT_PSP ? Date.now() + 15_000 : 0;
+        // A preparation that tokenized before Pay: the cardholder's device already holds CyberSource's
+        // token and approves as soon as this bind reaches it, while the page may give createToken only
+        // seconds (Alaska Airlines' flight checkout gives it three). Poll every 100 ms for 10 seconds,
+        // then at the caller's interval; at the default 2 seconds the first read alone would miss it.
+        // The API's bind names 100 ms as such a row's poll interval, so slow_down admits these reads
+        // (as an eProtect row names the 500 ms read above).
+        const preparedFlexPollUntil = preparation?.cybersourceFlex ? Date.now() + 10_000 : 0;
         let execution = {};
         let approvalDelivered = false;
         const deliverApproval = (state) => {
@@ -1897,6 +1968,8 @@ export class VaultClient {
             catch { /* observer only */ }
         };
         let failed = false;
+        // What this attempt throws, once it fails: a confirmed retirement below is written onto it.
+        let failure = null;
         let actionRequired = false;
         const checkAutopilotAction = (state) => {
             if (state.autopilot_status !== 'action_required')
@@ -1927,7 +2000,8 @@ export class VaultClient {
             while (Date.now() < deadline) {
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
-                const pollInterval = Date.now() < preparedFastPollUntil ? Math.min(this.pollIntervalMs, 500) : this.pollIntervalMs;
+                const pollInterval = Date.now() < preparedFastPollUntil ? Math.min(this.pollIntervalMs, 500)
+                    : Date.now() < preparedFlexPollUntil ? Math.min(this.pollIntervalMs, 100) : this.pollIntervalMs;
                 await interruptibleSleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())), stopSignal);
                 if (stopSignal?.aborted)
                     throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
@@ -2257,9 +2331,8 @@ export class VaultClient {
         }
         catch (error) {
             failed = true;
-            if (input.merchantSignal?.aborted)
-                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-            throw error;
+            failure = input.merchantSignal?.aborted ? new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted') : error;
+            throw failure;
         }
         finally {
             // An attested action-required result retains its claim and reservation.
@@ -2271,7 +2344,12 @@ export class VaultClient {
                 // known ID can be retired. An unacknowledged create remains unknown.
                 // A started/finalized replay or failed cleanup never becomes a claimed
                 // cancellation, and this best-effort cleanup never retries a payment.
-                await this.cancelAuthorization(authorizationId).catch(() => { });
+                const retired = await this.cancelAuthorization(authorizationId).catch(() => null);
+                // A retirement whose acknowledgement says no processor request started: the thrown error
+                // says so. The API echoes the reason the row carries, so a row retired earlier as
+                // merchant_never_retried can answer that a processor request did start; then nothing changes.
+                if (retired?.processor_request_started === false && failure instanceof PaymentOutcomeUnknownError)
+                    failure.processorRequestStarted = false;
             }
         }
     }
@@ -2632,9 +2710,11 @@ export class VaultClient {
  * approves every such payment); the agent's amount, the only authority here; a
  * session the API and the device would take (payment-core
  * merchantCardEndpointSessionRefusal: the profile's URL, headers, cookies, Referer and
- * body, paused on its checkout page); and the profile's status last, so that refusal
- * means every other check passed. Nothing it throws names the URL, the body or a
- * session value.
+ * body, paused on its checkout page); for a merchant that keeps its own record of the
+ * order, that record, held to the agent's amount and currency, and refused for an order
+ * that renews or a checkout in test mode (admitCardEndpointFacts); and the profile's
+ * status last, so that refusal means every other check passed. Nothing it throws names
+ * the URL, the body or a session value.
  */
 function admitCardEndpoint(input) {
     const named = input.request.merchant_card_endpoint;
@@ -2657,9 +2737,45 @@ function admitCardEndpoint(input) {
     const refusal = cardEndpointSessionRefusal(profile, session);
     if (refusal)
         throw new CardEndpointRefusedError(profile.id, 'request_unsupported', refusal);
+    const facts = admitCardEndpointFacts(profile, session, named.facts, input);
     if (!cardEndpointLive(profile))
         throw new CardEndpointRefusedError(profile.id, 'not_enabled');
-    return { profile: profile.id, session };
+    return { profile: profile.id, session, ...(facts ? { facts } : {}) };
+}
+/**
+ * The merchant's own record of the order, for a profile whose merchant keeps one
+ * (profile.facts), read with the rules the API reads it with (payment-core
+ * readMerchantCardEndpointFacts and merchantCardEndpointFactsRefusal): required, bound
+ * to this checkout's session, in the reviewed layout; a total or currency that differs
+ * from the agent's is an AmountMismatchError against the merchant's total, and a
+ * renewing order or a checkout in test mode is refused. Card endpoint payments are live
+ * only, so the record must say the checkout is live. Undefined for any other profile,
+ * which sends none.
+ */
+function admitCardEndpointFacts(profile, session, sent, input) {
+    if (!profile.facts) {
+        if (sent !== undefined)
+            throw new CardEndpointRefusedError(profile.id, 'request_unsupported', 'the request carries an order record this merchant has none of');
+        return undefined;
+    }
+    if (sent === undefined)
+        throw new CardEndpointRefusedError(profile.id, 'facts_unavailable', `${profile.merchant}'s own record of this order was not read`);
+    const read = sharedReadFacts(profile.id, session.url, sent);
+    if (!read.ok)
+        throw new CardEndpointRefusedError(profile.id, 'facts_unavailable', read.refusal);
+    const currency = String(input.currency).toLowerCase();
+    const refusal = sharedFactsRefusal(profile.id, read.facts, { amountCents: typeof input.amount === 'number' ? input.amount : Number.NaN, currency, live: true });
+    if (refusal?.code === 'amount' || refusal?.code === 'currency') {
+        // An integer amount is compared here; a decimal string is left to the API, which
+        // reads it in the currency's units and holds it to the same total.
+        if (typeof input.amount === 'number') {
+            throw new AmountMismatchError(null, input.amount, read.facts.amount.amountCents, currency, read.facts.amount.currency, 'create', 'merchant_total');
+        }
+    }
+    else if (refusal) {
+        throw new CardEndpointRefusedError(profile.id, 'facts_refused', refusal.reason);
+    }
+    return sent;
 }
 /**
  * The merchant's answer to the device's card request, as the API serves it once
@@ -2682,8 +2798,9 @@ function cardEndpointReplay(s, authorizationId, profile, metadata) {
         throw unknown('merchant_answer_malformed');
     const base = { mode: CARD_ENDPOINT_MODE, authorizationId, profile, status: answer.status, ...metadata };
     if (answer.withheld !== undefined) {
-        if (answer.withheld !== 'card_in_response' && answer.withheld !== 'unreadable_in_response')
+        if (answer.withheld !== 'card_in_response' && answer.withheld !== 'unreadable_in_response' && answer.withheld !== 'refused_step_in_response') {
             throw unknown('merchant_answer_malformed');
+        }
         return { ...base, headers: {}, setCookies: [], body: '', withheld: answer.withheld };
     }
     const headers = answer.headers;

package/dist/creditguard.generated.d.ts

@@ -54,7 +54,7 @@ declare function parseCreditguardTransaction(body: any, txId: any): {
     personalIdAlwaysEnabled: boolean;
     inputs: any;
 } | null;
-declare function creditguardTransactionRefusal(txn: any, expectation: any): "otp" | "keep_on_file" | "dcc" | "installments" | "personal_id" | "jwe_unsupported" | "amount_mismatch" | "currency_mismatch" | "transaction_unreadable" | "three_d_secure" | "transaction_type" | "form_inputs" | "card_field_hidden" | "no_retries_left" | "environment_mismatch" | "jwe_public_key_malformed" | null;
+declare function creditguardTransactionRefusal(txn: any, expectation: any): "otp" | "keep_on_file" | "dcc" | "installments" | "personal_id" | "jwe_unsupported" | "amount_mismatch" | "environment_mismatch" | "currency_mismatch" | "transaction_unreadable" | "three_d_secure" | "transaction_type" | "form_inputs" | "card_field_hidden" | "no_retries_left" | "jwe_public_key_malformed" | null;
 declare function creditguardSendWindowRefusal(timing: any): "timing_unknown" | "page_expired" | "recaptcha_expired" | null;
 declare var CREDITGUARD_REFUSAL_CODES: readonly string[];
 declare function creditguardResponseOutcome(status: any, body: any, options: any): {

package/dist/cybersource-flex.d.ts

@@ -158,6 +158,8 @@ export declare class MicroformFrames {
     /** A frame's committed document URL, fragment included. A URL that is not a field iframe's forgets the frame. */
     observe(frameId: unknown, url: unknown): void;
     forget(frameId: unknown): void;
+    /** The card Microform whose field documents this attachment recorded, for prepare({ tokenizeBeforePay: true }). */
+    loadedCard(): LoadedCardMicroform;
     /**
      * Judge a POST the frame `frameId` sent. When that frame is not on record, `reread` reads the
      * pausing session's frame tree once (recording what it finds) and resolves to the frame's
@@ -173,6 +175,34 @@ export declare class MicroformFrames {
  * request's frame could not be read at all.
  */
 export declare function judgeMicroformFrameUrls(request: FlexRequest, issuingUrl: string | undefined, frameUrls: Iterable<string | undefined>, contexts: CaptureContexts): CybersourceFlexDecision | Promise<CybersourceFlexDecision>;
+/**
+ * What prepare({ tokenizeBeforePay: true }) reads from the page before Pay: the one card Microform
+ * whose fields loaded, its capture context and its fields, or why there is none to read.
+ */
+export type LoadedCardMicroform = {
+    ok: true;
+    captureContext: string;
+    environment: string;
+    microform: {
+        version: string;
+        fields: MicroformField[];
+    };
+} | {
+    ok: false;
+    reason: 'microform_not_loaded' | 'microform_ambiguous' | 'microform_unsupported';
+};
+/**
+ * The card Microform a page loaded, for prepare({ tokenizeBeforePay: true }): every committed card
+ * field-iframe document, grouped by capture context, microform id, version and host. One group of a
+ * reviewed version, with a card number field and at most a security code field, is the checkout the
+ * cardholder's device tokenizes before Pay. No group is `microform_not_loaded` (prepare once the card
+ * fields show), two or more are `microform_ambiguous`, and any other group is `microform_unsupported`.
+ * A check (eCheck) Microform carries no card and is not counted. Reads the frames only; the capture
+ * context is verified by prepareCheckout, the API and the device.
+ */
+export declare function loadedCardMicroform(frames: Iterable<MicroformFrame>): LoadedCardMicroform;
+/** The Playwright adapter's read: every frame URL on the page (Playwright keeps the fragment in frame.url()). */
+export declare function loadedCardMicroformFromUrls(urls: Iterable<string | undefined>): LoadedCardMicroform;
 /**
  * Whether a create's sidecar has the shape the API admits (routes/api/v2/checkout.ts
  * createSchema): a capture context of 1 to 16384 characters, and a Microform version with a

package/dist/cybersource-flex.generated.d.ts

@@ -89,4 +89,30 @@ declare function transientTokenFacts(status: any, body: any, verified: any, card
 }>;
 declare function cybersourceFlexPreparationUrl(environment: any): any;
 declare function isPreparedCybersourceFlexRequest(url: any, method: any, body: any, environment: any, headers: any): boolean;
-export { CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH, CYBERSOURCE_FLEX_CONTENT_TYPE, CYBERSOURCE_FLEX_PSP, CYBERSOURCE_FLEX_REFUSAL_REASONS, CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS, CYBERSOURCE_FLEX_RULES_SOURCE, CYBERSOURCE_FLEX_SIGNING_KEYS, CYBERSOURCE_FLEX_TEST_PANS, CYBERSOURCE_FLEX_TOKENS_URLS, CybersourceFlexError, assertCybersourceFlexTemplate, buildCardPlaintext, cybersourceFlexEnvironment, flexHostEnvironment as cybersourceFlexHostEnvironment, cybersourceFlexPreparationUrl, cybersourceFlexRefusalCode, cybersourceFlexTemplateKid, detectCardTypes, isCybersourceFlexMediaType, isCybersourceFlexRequest, isCybersourceFlexTemplateBody, isCybersourceFlexTokenShape, isPreparedCybersourceFlexRequest, isVerifiedCaptureContext, parseMicroformFragment, sealForContext, transientTokenFacts, transientTokenSigned, verifyCaptureContext };
+declare var CYBERSOURCE_FLEX_PRESEAL_TRIGGER: string;
+declare function admitCybersourceFlexPreparation(prepared: any, { crypto, now }?: {}): Promise<Readonly<{
+    context: Readonly<{
+        raw: any;
+        signingKid: any;
+        environment: any;
+        origin: string;
+        path: string;
+        url: string;
+        jwk: Readonly<{
+            kty: "RSA";
+            n: any;
+            e: any;
+            kid: any;
+        }>;
+        modulusBytes: number;
+        index: any;
+        contextType: any;
+        allowedCardNetworks: readonly any[] | null;
+        targetOrigins: readonly any[];
+        iat: any;
+        exp: any;
+    }>;
+    fields: readonly string[];
+}>>;
+declare function sameCybersourceFlexPreparation(prepared: any, request: any): boolean;
+export { CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH, CYBERSOURCE_FLEX_CONTENT_TYPE, CYBERSOURCE_FLEX_PRESEAL_TRIGGER, CYBERSOURCE_FLEX_PSP, CYBERSOURCE_FLEX_REFUSAL_REASONS, CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS, CYBERSOURCE_FLEX_RULES_SOURCE, CYBERSOURCE_FLEX_SIGNING_KEYS, CYBERSOURCE_FLEX_TEST_PANS, CYBERSOURCE_FLEX_TOKENS_URLS, CybersourceFlexError, admitCybersourceFlexPreparation, assertCybersourceFlexTemplate, buildCardPlaintext, cybersourceFlexEnvironment, flexHostEnvironment as cybersourceFlexHostEnvironment, cybersourceFlexPreparationUrl, cybersourceFlexRefusalCode, cybersourceFlexTemplateKid, detectCardTypes, isCybersourceFlexMediaType, isCybersourceFlexRequest, isCybersourceFlexTemplateBody, isCybersourceFlexTokenShape, isPreparedCybersourceFlexRequest, isVerifiedCaptureContext, parseMicroformFragment, sameCybersourceFlexPreparation, sealForContext, transientTokenFacts, transientTokenSigned, verifyCaptureContext };

package/dist/cybersource-flex.generated.js

@@ -1,6 +1,6 @@
 // @ts-nocheck
 // Generated from @agent-cards/payment-core. Do not edit.
-// artifact-sha256: a2260c2d905a5cd4ef148ab8a79e90fb2f9f6790d9efba06e95ed35f8bea2755
+// artifact-sha256: a2baaac410b5aaa629b3d5031136f88645c7b45c67c3bbc154cad72de216a04e
 // src/cybersource-flex-rules.js
 var CYBERSOURCE_FLEX_RULES_SOURCE = Object.freeze({ version: "2.12.1", sha256: "8429ebae83e9745cd53ad8ff0d9ba69bee0087c1435ed0695a25444bed418327" });
 var CYBERSOURCE_FLEX_RULES = [
@@ -686,4 +686,44 @@ function iframeHeaders(headers) {
 function isPreparedCybersourceFlexRequest(url, method, body, environment, headers) {
     return (environment === "production" || environment === "sandbox") && method === "POST" && cybersourceFlexEnvironment(url) === environment && iframeHeaders(headers) && isCybersourceFlexTemplateBody(body);
 }
-export { CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH, CYBERSOURCE_FLEX_CONTENT_TYPE, CYBERSOURCE_FLEX_PSP, CYBERSOURCE_FLEX_REFUSAL_REASONS, CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS, CYBERSOURCE_FLEX_RULES_SOURCE, CYBERSOURCE_FLEX_SIGNING_KEYS, CYBERSOURCE_FLEX_TEST_PANS, CYBERSOURCE_FLEX_TOKENS_URLS, CybersourceFlexError, assertCybersourceFlexTemplate, buildCardPlaintext, cybersourceFlexEnvironment, flexHostEnvironment as cybersourceFlexHostEnvironment, cybersourceFlexPreparationUrl, cybersourceFlexRefusalCode, cybersourceFlexTemplateKid, detectCardTypes, isCybersourceFlexMediaType, isCybersourceFlexRequest, isCybersourceFlexTemplateBody, isCybersourceFlexTokenShape, isPreparedCybersourceFlexRequest, isVerifiedCaptureContext, parseMicroformFragment, sealForContext, transientTokenFacts, transientTokenSigned, verifyCaptureContext };
+var CYBERSOURCE_FLEX_PRESEAL_TRIGGER = "number";
+var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+function preparedLayout(microform) {
+    if (!isRecord(microform) || typeof microform.version !== "string" || !CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS.includes(microform.version)) {
+        refuse("microform_version", "this payment's card field is not a Microform version this device can rebuild.");
+    }
+    if (Object.keys(microform).some((key) => key !== "version" && key !== "fields")) {
+        refuse("fields", "the Microform fields this payment loaded are not a card number field and an optional security code field.");
+    }
+    fieldSet(microform.fields, CYBERSOURCE_FLEX_PRESEAL_TRIGGER);
+    return Object.freeze(FIELD_TYPES.filter((field) => microform.fields.includes(field)));
+}
+async function admitCybersourceFlexPreparation(prepared, { crypto, now } = {}) {
+    if (!isRecord(prepared))
+        refuse("request", "malformed checkout preparation.");
+    const fields = preparedLayout(prepared.microform);
+    const { environment } = prepared;
+    if (environment !== "production" && environment !== "sandbox") {
+        refuse("environment_mismatch", "the preparation names no CyberSource environment.");
+    }
+    const context = await verifyCaptureContext(prepared.capture_context, { crypto, now });
+    if (context.environment !== environment || context.url !== CYBERSOURCE_FLEX_TOKENS_URLS[environment]) {
+        refuse("environment_mismatch", "the CyberSource test and live environments are mixed in this payment.");
+    }
+    return Object.freeze({ context, fields });
+}
+function sameCybersourceFlexPreparation(prepared, request) {
+    if (!isRecord(prepared) || !isRecord(request) || !isRecord(prepared.microform) || !isRecord(request.microform))
+        return false;
+    const context = prepared.capture_context;
+    if (typeof context !== "string" || context.length < 1 || context.length > CAPTURE_CONTEXT_MAX_LENGTH || request.capture_context !== context)
+        return false;
+    const one = prepared.microform;
+    const two = request.microform;
+    if (typeof one.version !== "string" || one.version !== two.version || !Array.isArray(one.fields) || !Array.isArray(two.fields))
+        return false;
+    const mine = new Set(one.fields);
+    const theirs = new Set(two.fields);
+    return mine.size === one.fields.length && theirs.size === two.fields.length && mine.size === theirs.size && [...mine].every((field) => theirs.has(field));
+}
+export { CYBERSOURCE_FLEX_CAPTURE_CONTEXT_MAX_LENGTH, CYBERSOURCE_FLEX_CONTENT_TYPE, CYBERSOURCE_FLEX_PRESEAL_TRIGGER, CYBERSOURCE_FLEX_PSP, CYBERSOURCE_FLEX_REFUSAL_REASONS, CYBERSOURCE_FLEX_REVIEWED_IFRAME_VERSIONS, CYBERSOURCE_FLEX_RULES_SOURCE, CYBERSOURCE_FLEX_SIGNING_KEYS, CYBERSOURCE_FLEX_TEST_PANS, CYBERSOURCE_FLEX_TOKENS_URLS, CybersourceFlexError, admitCybersourceFlexPreparation, assertCybersourceFlexTemplate, buildCardPlaintext, cybersourceFlexEnvironment, flexHostEnvironment as cybersourceFlexHostEnvironment, cybersourceFlexPreparationUrl, cybersourceFlexRefusalCode, cybersourceFlexTemplateKid, detectCardTypes, isCybersourceFlexMediaType, isCybersourceFlexRequest, isCybersourceFlexTemplateBody, isCybersourceFlexTokenShape, isPreparedCybersourceFlexRequest, isVerifiedCaptureContext, parseMicroformFragment, sameCybersourceFlexPreparation, sealForContext, transientTokenFacts, transientTokenSigned, verifyCaptureContext };

package/dist/cybersource-flex.js

@@ -222,6 +222,10 @@ export class MicroformFrames {
         if (typeof frameId === 'string')
             this.frames.delete(frameId);
     }
+    /** The card Microform whose field documents this attachment recorded, for prepare({ tokenizeBeforePay: true }). */
+    loadedCard() {
+        return loadedCardMicroform(this.frames.values());
+    }
     /**
      * Judge a POST the frame `frameId` sent. When that frame is not on record, `reread` reads the
      * pausing session's frame tree once (recording what it finds) and resolves to the frame's
@@ -251,6 +255,48 @@ export function judgeMicroformFrameUrls(request, issuingUrl, frameUrls, contexts
     }
     return judgeMicroformRequest(request, issuingUrl === undefined ? undefined : frameOf(issuingUrl), frames, contexts);
 }
+/**
+ * The card Microform a page loaded, for prepare({ tokenizeBeforePay: true }): every committed card
+ * field-iframe document, grouped by capture context, microform id, version and host. One group of a
+ * reviewed version, with a card number field and at most a security code field, is the checkout the
+ * cardholder's device tokenizes before Pay. No group is `microform_not_loaded` (prepare once the card
+ * fields show), two or more are `microform_ambiguous`, and any other group is `microform_unsupported`.
+ * A check (eCheck) Microform carries no card and is not counted. Reads the frames only; the capture
+ * context is verified by prepareCheckout, the API and the device.
+ */
+export function loadedCardMicroform(frames) {
+    const groups = new Map();
+    for (const frame of frames) {
+        if (frame.microformType !== 'card')
+            continue;
+        const key = JSON.stringify([frame.captureContext, frame.microformId, frame.version, frame.environment]);
+        const group = groups.get(key);
+        if (group)
+            group.types.add(frame.fieldType);
+        else
+            groups.set(key, { frame, types: new Set([frame.fieldType]) });
+    }
+    if (groups.size === 0)
+        return { ok: false, reason: 'microform_not_loaded' };
+    if (groups.size > 1)
+        return { ok: false, reason: 'microform_ambiguous' };
+    const [{ frame, types }] = [...groups.values()];
+    if (!frame.reviewed || !types.has('number') || [...types].some((type) => !MICROFORM_FIELDS.includes(type))) {
+        return { ok: false, reason: 'microform_unsupported' };
+    }
+    return { ok: true, captureContext: frame.captureContext, environment: frame.environment,
+        microform: { version: frame.version, fields: MICROFORM_FIELDS.filter((field) => types.has(field)) } };
+}
+/** The Playwright adapter's read: every frame URL on the page (Playwright keeps the fragment in frame.url()). */
+export function loadedCardMicroformFromUrls(urls) {
+    const frames = [];
+    for (const url of urls) {
+        const frame = frameOf(url);
+        if (frame)
+            frames.push(frame);
+    }
+    return loadedCardMicroform(frames);
+}
 /**
  * Whether a create's sidecar has the shape the API admits (routes/api/v2/checkout.ts
  * createSchema): a capture context of 1 to 16384 characters, and a Microform version with a