@agent-cards/sdk 0.20.0 → 0.22.0

package/dist/client.d.ts

@@ -3,10 +3,15 @@ import type { Substitutions } from './substitute.js';
 import { type MerchantHostedSubstitutions, type MerchantProfile, type SandboxMerchantDeclaration } from './merchant-hosted.js';
 import { type MerchantTotalApproved, type MerchantTotalCapture } from './merchant-total.js';
 import { type PreparationMode, type PreparationProcessor } from './prepared-processor.js';
+import { type VerifoneProfile, type VerifoneSubstitutions } from './verifone.js';
+import { type MerchantSessionCapture } from './merchant-session-probe.js';
 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 CardEndpointSession } from './card-endpoint.js';
+import { type PayrailsSidecar } from './payrails.js';
 export interface PausedRequest {
     url: string;
     method: string;
@@ -14,11 +19,38 @@ export interface PausedRequest {
     body: string;
     /** Captured native Checkout Pro initialization, validated before use. */
     mercado_checkout?: unknown;
+    /**
+     * CyberSource Flex only: the capture context the card field iframe was loaded with, byte for
+     * byte from its URL fragment. The cardholder's device seals the real card under it, so the API
+     * verifies it before anything exists. The adapters read it; refused on any other processor.
+     */
+    capture_context?: string;
+    /** CyberSource Flex only: the Microform fields that loaded and the one that sent this request. */
+    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`.
+     */
+    merchant_card_endpoint?: {
+        profile: string;
+        session: CardEndpointSession;
+    };
+    /**
+     * A Payrails card save (mode device_encrypt) only: the session key the page's
+     * Payrails init payload named (vaultConfiguration.encryptionPublicKey), which
+     * the save itself does not carry. The adapters capture it; a caller running
+     * its own interception passes it here, and a save without it is refused
+     * before anything is created.
+     */
+    payrails?: PayrailsSidecar;
 }
 /**
  * The modes this SDK can finish. Asked for on syncRegistry (the API serves
  * only recognizers in these modes, so a request this build cannot complete
- * is never paused) and sent on every create.
+ * is never paused) and sent on every create. `device_encrypt`: the adapters
+ * capture the Payrails session key the page's init payload names (payrails.ts),
+ * and the cardholder's device encrypts and sends the save.
  */
 export declare const SUPPORTED_MODES: readonly CheckoutMode[];
 /**
@@ -34,12 +66,109 @@ export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
 /**
  * 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
+ * these, and only to an org Agentcard enabled for the processor.
+ * `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.
+ * `gmo_shared_pk`: GMO token v2's getToken on the shared-key path, which this
+ * build judges before it pauses (gmo.ts) and pays only for the amount the
+ * agent passes. A gated recognizer never sits in BUILTIN_REGISTRY, so it is
+ * paused only after a sync.
+ * `capture_context`: CyberSource Flex Microform, whose create carries the capture
+ * context this build reads from the card field iframe (cybersource-flex.ts); the API
+ * serves Flex's recognizer the same way, only for a company Agentcard turned it on for.
+ * A gated recognizer is never in BUILTIN_REGISTRY, so a build reaches it only through a
+ * sync that declares its capability.
+ * `juspay_txns.v1`: Juspay's card flow (juspay-gate.ts), whose page tokenize
+ * this build answers locally and whose /txns it pauses, served and refused by
+ * the same rule. A gated recognizer is never in BUILTIN_REGISTRY, so a build
+ * reaches it only through a sync that declares its capability.
+ * `datatrans_secure_fields_tokenize`: Datatrans Secure Fields' TOKENIZE card
+ * post, which this build judges before it pauses, under the card-on-file
+ * policy served with the entry, and answers again for a repeat of the same
+ * form (datatrans.ts). A gated recognizer never sits in BUILTIN_REGISTRY, so
+ * it is paused only after a sync.
+ * `authorize_net_dpm_form`: the Authorize.Net Direct Post Method and SIM card
+ * form, one form navigation to transact.dll that the cardholder's device submits
+ * itself (hosted_form). This build finishes it with the hosted_form flow it
+ * already speaks, holds the bare endpoint the entry names (bareEndpoint in
+ * findRecognizer), and reads the form's keys without regard to case
+ * (card-fields.js). The API serves it, like Fiserv's, only to an org Agentcard
+ * enabled for that processor; every other org is served the ungated catalog.
+ * `pelecard_transaction`: Pelecard's card submission, which this build judges
+ * before it pauses (pelecard.ts) and pays only for the amount the agent passes.
+ * Declaring it is not enough: the API serves a gated recognizer only to an org
+ * Agentcard has enabled for that processor, so for every other org this build
+ * syncs the same catalog as one that declares nothing and leaves the processor's
+ * requests alone. A gated recognizer never sits in BUILTIN_REGISTRY, so it is
+ * paused only after a sync.
+ * `aci_split_card.v1`: ACI's COPYandPAY widget, whose card reaches ACI as
+ * several requests to one checkout. This build pauses the card-number request
+ * for a prepared checkout, holds the page's own CVC and expiry requests and
+ * answers them with that request's answer, and continues the page's /payment
+ * submission once, with the placeholder expiry removed (aci.ts). A gated
+ * recognizer is never in BUILTIN_REGISTRY, so a build reaches it only through a
+ * sync that declares its capability, and whether an org may pay through it
+ * stays the API's decision.
+ * `creditguard_pps_process`: CreditGuard's hosted payment page (Hyp PPS), whose
+ * card submit this build pays only under a prepared checkout that names the
+ * framed page (prepare({ psp: 'creditguard', environment, paymentPageUrl })). The
+ * API serves CreditGuard's recognizer on the same terms as Fiserv's.
+ * `primer_payment_instruments`: Primer's card tokenization, which this build
+ * judges before it pauses (primer.ts) and hands back to the page only as a
+ * single-use token. A merchant's client session can save the card after the
+ * payment with no sign in that request, so the API creates a Primer
+ * authorization only for a test-mode client and refuses a live one (400
+ * invalid_primer_request, live_keep_on_file) until the cardholder can consent
+ * to that save; this build then aborts the paused request with nothing sent. A
+ * gated recognizer never sits in BUILTIN_REGISTRY, so it is paused only after a
+ * sync.
+ * `payrails_device_encrypt`: Payrails' card-form save, which this build pauses
+ * only once it has bound the save to a captured session (payrails.ts). A gated
+ * recognizer never sits in BUILTIN_REGISTRY, so it is paused only after a sync.
+ * `converge_hpp_process`: Elavon Converge's Hosted Payment Page card request
+ * (elavon-converge.ts), paused in token mode and judged by the pre-claim gate.
+ * A gated recognizer never sits in BUILTIN_REGISTRY, so it is paused only after a
+ * sync, and the API also refuses a Converge payment for every company the
+ * processor is off for.
+ * `worldpay_eprotect_jsonp`: Worldpay eProtect, whose card rides in the query of
+ * a JSONP <script> GET that this build pauses, binds to a prepared checkout and
+ * answers with the registration in the script's own callback (eprotect.ts). A
+ * gated recognizer is never in BUILTIN_REGISTRY, so a build reaches either only
+ * through a sync that declares its capability, and the API serves it on that
+ * sync only for a company it has turned the processor on for.
+ * `wspay_confirm`: WSPay Components' card confirm, which this build judges
+ * before it pauses (wspay.ts) and pays only for the amount the agent passes.
+ * The API serves a gated recognizer only to a build that lists its capability
+ * and only for a company Agentcard turned that processor on for, so an older
+ * SDK never pauses a request it cannot finish and no SDK pauses one for a
+ * company the processor is off for; the API also refuses that processor's
+ * payment for every such company. A gated recognizer never sits in
+ * BUILTIN_REGISTRY, so it is paused only after a sync.
+ * `shiji_sts_pinned_key`: this build swaps Shiji STS's ciphertexts at the body
+ * root under the pinned key, binds the getCvvId companion to the getTokenId it
+ * continued, and refuses every other Shiji request in the browser (shiji-sts.ts).
+ * The API serves it on the same terms, only for a company Agentcard turned Shiji
+ * STS on for.
+ * `amadeus_checkout_actions.v1`: Amadeus Checkout (the Checkout Web SDK add and
+ * the Data Collection Page store), served on the same terms. This build lets every
+ * other action on those URLs through without claiming a preparation, so the page's
+ * own `load` never spends or blocks one, takes the card request only through a
+ * prepared checkout bound to the approved page's host, and fails a paused SDK add
+ * the device has not started 20 seconds after the pause (AMADEUS_SEND_WINDOW_MS).
+ * `worldline_mycheckout_form`: Worldline MyCheckout's card form (DHL Express),
+ * a top-level form POST this build holds like Tranzila's (mode hosted_form) and
+ * answers with the submission notice once the cardholder's device submitted the
+ * form itself. The page's cancel and its other payment methods on the same URL
+ * carry no card and continue untouched. The API serves the recognizer only to a
+ * build that lists it and only for a company Agentcard turned it on for.
+ * `verifone_card_capture`: a reviewed Verifone merchant's own card request (a
+ * 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.
  */
 export declare const SUPPORTED_CAPABILITIES: readonly string[];
 /**
@@ -58,6 +187,17 @@ export declare const SUPPORTED_CAPABILITIES: readonly string[];
 export type AmountAuthority = 'processor' | 'agent' | 'page' | 'none';
 /** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
 export declare function validAmountInput(amount: unknown): amount is number | string;
+/** Digits after the point when the API reads an amount in `currency`. */
+export declare function amountDigits(currency: string): 0 | 2 | 3;
+/**
+ * Why an amount is refused, worded for the agent that sent it: the rule, the value it passed, and
+ * each amount that value can mean, in the forms the API accepts. An agent told only the rule sends
+ * the same value again, and a tool harness that serializes every argument as text turns 2667 into
+ * "2667" on each try. A value that does not read as a price (long, or more digits than any amount)
+ * is described and never echoed, so a card number typed into the wrong field cannot reach a log
+ * line. A value below zero is named as such and never offered back as a positive amount.
+ */
+export declare function amountRefusal(amount: unknown, currency?: unknown): string;
 /** How an existing authorization is being handled; omitted by older APIs. */
 export interface ExecutionMetadata {
     executionMode?: 'user_approval' | 'autopilot';
@@ -121,6 +261,14 @@ export interface CseReplay extends ExecutionMetadata {
     kind?: undefined;
     authorizationId: string;
     substitutions: Substitutions;
+    /**
+     * Shiji STS only: the getCvvId keySequence values the API reviewed as the booking page's own and
+     * served beside the set (`shiji_sts_companion`). The adapters bind the companion getCvvId to them
+     * (shiji-sts.ts ShijiStsCompanions), so the device's CVV goes under no other key.
+     */
+    shijiStsCompanion?: Readonly<{
+        keySequences: readonly string[];
+    }>;
     amountAuthority?: AmountAuthority;
 }
 /**
@@ -157,6 +305,29 @@ export interface MerchantHostedReplay extends ExecutionMetadata {
     merchantTotal?: MerchantTotalApproved;
     amountAuthority?: AmountAuthority;
 }
+/**
+ * The cse flow at a reviewed Verifone merchant's OWN endpoint (verifone.ts): the
+ * cardholder's device encrypted the card with verifone.js's format under the key
+ * Agentcard pinned for that merchant, and nothing was sent. The paused request
+ * continues from this browser with the device's blob in place of the page's
+ * (substituteVerifoneBody), and only when the live body still hashes to
+ * `bodySha256`, the body the API checked at create. The merchant's server charges
+ * the card and answers its own page; its order state is the outcome. Only a
+ * prepared checkout pays one, never Autopilot.
+ */
+export interface VerifoneReplay extends ExecutionMetadata {
+    mode: 'cse';
+    kind: 'verifone';
+    authorizationId: string;
+    /** The reviewed Verifone profile the approval pays. */
+    profile: string;
+    substitutions: VerifoneSubstitutions;
+    /** SHA-256 (lowercase hex) of the paused body the API checked at create. */
+    bodySha256: string;
+    /** When the API stops serving this blob, if it said. */
+    substitutionsExpiresAt: string | null;
+    amountAuthority?: AmountAuthority;
+}
 /**
  * The hosted_form flow (Tranzila): the cardholder's device rebuilt the
  * processor's own form with the real card and submitted it itself, top-level,
@@ -185,8 +356,54 @@ export interface HostedFormReplay extends ExecutionMetadata {
     submittedAt: string;
     amountAuthority?: AmountAuthority;
 }
+/**
+ * The card_endpoint flow: a reviewed merchant's own card endpoint. The cardholder's
+ * device sent the merchant's card request itself, with the real card and the paused
+ * request's session, and reported the merchant's answer, which the adapters hand to
+ * the paused request: `status`, the profile's answer `headers`, and `body`, with
+ * `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.
+ */
+export interface CardEndpointReplay extends ExecutionMetadata {
+    mode: 'card_endpoint';
+    authorizationId: string;
+    /** The reviewed profile the device paid. */
+    profile: string;
+    /** The merchant's HTTP status for the card request. */
+    status: number;
+    headers: Record<string, string>;
+    setCookies: string[];
+    body: string;
+    withheld: 'card_in_response' | 'unreadable_in_response' | null;
+    amountAuthority?: AmountAuthority;
+}
+/**
+ * The device_encrypt flow (Payrails): the cardholder's device encrypted the
+ * real card under the session key the page's init payload named and sent the
+ * save to Payrails itself. This is Payrails' 201 for that save, rebuilt from an
+ * allow-list (the instrument's identifiers, its status, the network, the BIN
+ * cut to six digits, the last four, the expiry, the holder name and the
+ * fingerprint), to replay into the paused request as in the token flow. The
+ * ciphertext the device made never reaches the runtime or the page. Never an
+ * autopilot result: autopilot refuses this mode.
+ */
+export interface DeviceEncryptReplay extends ExecutionMetadata {
+    mode: 'device_encrypt';
+    authorizationId: string;
+    status: number;
+    headers: Record<string, string>;
+    /** Body to hand back to the browser, verbatim. */
+    body: string;
+    amountAuthority?: AmountAuthority;
+}
 /** What authorize() resolves with; branch on `mode` (absent means token). */
-export type ReplayResponse = TokenReplay | CseReplay | MerchantHostedReplay | HostedFormReplay;
+export type ReplayResponse = TokenReplay | CseReplay | MerchantHostedReplay | VerifoneReplay | HostedFormReplay | CardEndpointReplay | DeviceEncryptReplay;
 export interface PrepareCheckoutOptions {
     psp: PreparationProcessor;
     /** The processor environment, independent of your Agentcard client's mode. */
@@ -203,8 +420,34 @@ export interface PrepareCheckoutOptions {
      * approve a payment to the merchant that key belongs to, so the checkout's `merchant`
      * must be that merchant's name (`Agentcard sandbox` for `agentcard_sandbox`), and the
      * one card capture this preparation pays must carry an envelope under that key.
+     *
+     * A Verifone checkout (psp 'verifone'): the id of the Verifone profile Agentcard
+     * reviewed for the merchant, which this client must have armed and enabled
+     * (syncRegistry), in the profile's own environment. The cardholder is shown the
+     * merchant the profile names, whatever label `merchant` carries, and the profile's
+     * reviewed card request is the one request this preparation pays.
      */
     merchantProfile?: string;
+    /**
+     * CreditGuard only, and required there: the address of CreditGuard's hosted
+     * payment page the checkout framed, the iframe's `src` as CreditGuard handed
+     * it to the merchant (https://pps.creditguard.co.il/?txId=<transaction id>;
+     * pps2 is production too, ppsuat is the sandbox). Agentcard reads that
+     * transaction from CreditGuard before the cardholder is asked, and only that
+     * transaction's card submit can use the preparation.
+     */
+    paymentPageUrl?: string;
+    /**
+     * Worldpay eProtect only, and required there: the merchant's eProtect
+     * paypageId, 1 to 64 letters and digits. It names the Worldpay merchant the
+     * card registration is for, which is also the merchant Worldpay lets charge
+     * the card again, so it is fixed before the page sends anything: a
+     * registration naming another paypageId never spends the approval. Read it off
+     * the checkout before Pay (the Worldpay iframe's `payframe_<paypageId>_...`
+     * URL, or the merchant's eProtect configuration). Refused on every other
+     * processor.
+     */
+    paypageId?: string;
     signal?: AbortSignal;
 }
 export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
@@ -247,11 +490,22 @@ export interface PreparedCheckout {
         endpoint: string;
         clientKey: string;
     }>;
+    /** CreditGuard only: the hosted payment page whose transaction the cardholder approved. */
+    readonly paymentPageUrl?: string;
+    /** Worldpay eProtect only: the paypageId the API confirmed, the one merchant whose registration may spend this approval. */
+    readonly paypageId?: string;
 }
 export declare class CheckoutPreparationError extends Error {
     preparationId: string | null;
     reason: string;
-    constructor(preparationId: string | null, reason: string);
+    /**
+     * The API's own reason code under `reason`, when it gave one: a CreditGuard
+     * transaction refused as `creditguard_transaction_refused` names what the
+     * Vault cannot finish here (`three_d_secure`, `otp`, `installments`, ...).
+     */
+    readonly detail?: string;
+    /** `explanation` follows the reason in the message: what the caller passed and what to send instead. */
+    constructor(preparationId: string | null, reason: string, detail?: string, explanation?: string);
 }
 export interface AuthorizeInput extends ExecutionMetadata {
     /** Native Checkout defaults to TEST; LIVE requires this explicit opt-in. */
@@ -273,6 +527,13 @@ export interface AuthorizeInput extends ExecutionMetadata {
      * smallest unit is refused with nothing charged (an AmountMismatchError;
      * `stage` says which check). Agentcard derives the display string; you
      * never send one. Both or neither: one without the other is refused.
+     * Required when the processor's request names no amount at all (GMO,
+     * Pelecard, WSPay): then this pair is what the cardholder approves, and a
+     * request without it throws AmountRequiredError before anything is created.
+     * No Pelecard answer states an amount, so for Pelecard the page's total
+     * (`pageAmount`) is required beside it: see the README's Pelecard section.
+     * WSPay's answer is compared with it only when that answer names an amount;
+     * a 3-D Secure step names none (see the README's WSPay section).
      */
     amount?: number | string;
     currency?: string;
@@ -280,6 +541,9 @@ export interface AuthorizeInput extends ExecutionMetadata {
      * The total read off the checkout page, the lowest authority: used only
      * when neither the processor's request nor your hint names an amount. The
      * adapters fill it from `[data-agentcard-amount]` when a page carries one.
+     * Required for Pelecard, whose request names no amount: the API holds the
+     * agent's pair to it, and a Pelecard request without it throws
+     * PageAmountRequiredError before anything is created.
      */
     pageAmount?: {
         amount: number;
@@ -337,6 +601,51 @@ export declare class UnsupportedModeError extends Error {
     mode: string;
     constructor(mode: string);
 }
+/**
+ * The recognizer is gated behind a dark-launch capability this SDK build does not
+ * declare (SUPPORTED_CAPABILITIES), so it cannot send what that processor's create
+ * needs. Thrown locally before any create or prompt, and terminal. A registry the
+ * API served never holds such an entry (it serves a gated one only to a build that
+ * declares it); a hand-built one can.
+ */
+export declare class UnsupportedCapabilityError extends Error {
+    capability: string;
+    constructor(capability: string);
+}
+/**
+ * placeholderCard() found no stored card to describe (`card_not_found`), the stored card's
+ * network has no documented placeholder number (`brand_unsupported`), or the stored card
+ * carries no usable expiry (`expiry_unknown`). Nothing was created and nothing was charged.
+ */
+export declare class PlaceholderCardError extends Error {
+    reason: 'card_not_found' | 'brand_unsupported' | 'expiry_unknown';
+    constructor(reason: 'card_not_found' | 'brand_unsupported' | 'expiry_unknown');
+}
+/**
+ * What the agent types into a checkout so the page's own card facts match the stored card
+ * that pays: a documented test number of the same network, a placeholder security code of that
+ * network's length, and the stored card's real expiry. CyberSource Flex merchants post the brand
+ * the card field detected from the typed number and the expiry typed into their own fields beside
+ * the token (Sonos, Amtrak), so a mismatch there fails the merchant's payment.
+ */
+export interface PlaceholderCard {
+    /**
+     * The stored card these facts describe (GET /api/v2/vault_cards). Pass it as `cardId` to
+     * attachToCdp, attachToPlaywright or authorize(): the approval page then preselects this card.
+     * Without it the page preselects its own choice, which can be another card.
+     */
+    readonly cardId: string;
+    /** Its network, as GET /api/v2/vault_cards names it. */
+    readonly brand: string;
+    /** A documented test card number of that network. Never a real card: the device supplies the real one. */
+    readonly number: string;
+    /** A placeholder security code of the length that network uses. */
+    readonly securityCode: string;
+    /** The stored card's expiry month, two digits ("04"). */
+    readonly expiryMonth: string;
+    /** The stored card's expiry year, four digits ("2031"). */
+    readonly expiryYear: string;
+}
 /**
  * The recognizer says this processor is preparation-required, and no preparation
  * was passed. Its card may be sent only after the cardholder approved a
@@ -349,6 +658,38 @@ export declare class PreparationRequiredError extends Error {
     psp: string;
     constructor(psp: string);
 }
+/**
+ * The paused request names no amount and none was passed. A GMO card token
+ * request carries no amount (the merchant's server charges the token later),
+ * and neither does a Pelecard card submission (the merchant's server bound it
+ * to the payment page when it created it) or a WSPay confirm (WSPay fixed it
+ * when the merchant's server created the payment), so the `amount` and
+ * `currency` you pass are what the cardholder approves, and for WSPay the
+ * figure the API compares with WSPay's answer when that answer names one (a
+ * 3-D Secure step names none). Thrown locally before any create or
+ * prompt, and terminal: the same request without an amount fails the same
+ * way. The API answers 400 amount_required for the same case. A page total
+ * (`pageAmount`) does not count.
+ */
+export declare class AmountRequiredError extends Error {
+    psp: string;
+    readonly code: "amount_required";
+    constructor(psp: string);
+}
+/**
+ * The paused request names no amount, and the total its payment page shows
+ * (`pageAmount`) was not passed. Pelecard's merchant bound the total to the
+ * payment page when it created it, and no Pelecard request or answer states
+ * it, so the page's total is the one figure that ties the `amount` the
+ * cardholder approves to what the page charges. Thrown locally before any
+ * create or prompt; the API answers 400 page_amount_required for the same
+ * case. Not terminal: the page's next submission reads the total again.
+ */
+export declare class PageAmountRequiredError extends Error {
+    psp: string;
+    readonly code: "page_amount_required";
+    constructor(psp: string);
+}
 export declare class ApprovalTimeoutError extends Error {
     constructor(ms: number);
 }
@@ -609,9 +950,20 @@ export declare class CheckoutApiError extends Error {
      * already has, or already answered, the prompt for this submission, and
      * once that prior authorization is declined or expired the same form is a
      * new question. The adapters quiet the page's re-post the way they quiet a
-     * decline instead of latching the attachment.
+     * decline instead of latching the attachment. NOT a stale form fingerprint
+     * either (isStaleFingerprint): the bytes of that form are refused for good,
+     * but the merchant's page renders a fresh fingerprint on reload, so the
+     * page's next form is a new question and is quieted the same way.
      */
     get permanent(): boolean;
+    /**
+     * True for a 400 `hosted_form_field_refused` whose reason is
+     * `stale_fingerprint`: an Authorize.Net DPM or SIM form signed more than 40
+     * minutes before the create, or ahead of the API's clock. Authorize.Net
+     * would refuse that fingerprint itself, and the page renders a fresh one
+     * when it reloads, so the refusal holds for this form only.
+     */
+    get isStaleFingerprint(): boolean;
 }
 /** The client-credentials exchange was refused: the RFC 6749 error, with the status the token endpoint answered. */
 export declare class CheckoutAuthError extends Error {
@@ -623,6 +975,13 @@ export declare class CheckoutAuthError extends Error {
  * A URL as it may appear in an error message: origin + path only. A paused
  * request's URL can carry a client secret in its query string, and error
  * messages travel further than anyone intends (onEvent, logs, crash reports).
+ * CreditGuard puts one in the path: on its hosts the transaction id after
+ * /txn/ is that transaction's only credential (payment-core's creditguard.js),
+ * so it reads {txId}, as does any other id-shaped segment there.
+ * On the Monri and WSPay hosts the secret is a path segment, so it is replaced
+ * with `{client_secret}`: https://proxy.wspay.biz/v2/payment/{client_secret}/confirm.
+ * A string that is not a URL keeps the part before any `?` or `#`, with the
+ * same segment masked.
  */
 export declare function redactUrl(raw: string): string;
 export interface VaultClientOptions {
@@ -706,6 +1065,12 @@ export declare class VaultClient {
      * in 'observe' until a sync reads that the API enabled it (armServedProfiles).
      */
     private merchantProfiles;
+    /**
+     * The reviewed Verifone profiles this client arms: only the ones the API served on the
+     * last sync, which it serves only to a company Agentcard turned Verifone on for
+     * (armServedVerifoneProfiles). None before a sync.
+     */
+    private verifoneProfiles;
     /** This client's own sandbox declarations (sandboxMerchants), armed at construction, one per profile. */
     private readonly declaredProfiles;
     private readonly preparations;
@@ -757,10 +1122,26 @@ export declare class VaultClient {
         find: (url: string) => Recognizer | null;
     };
     private mergedRegistry;
-    /** The recogniser that claims a card request (`POST` to a recognised endpoint), or null; what a paused request names as `recognizer`. */
+    /**
+     * The recogniser that claims a card request, or null; what a paused request names as
+     * `recognizer`. A POST to a recognised endpoint, or for a recognizer whose card request is a
+     * GET (Worldpay eProtect) that exact GET, query included.
+     */
     recognizerOf(url: string, method?: string): Recognizer | null;
     /** Refresh recognizers from the API so new PSPs work without a redeploy. */
     syncRegistry(): Promise<void>;
+    /**
+     * The armed Verifone profile whose endpoint origin this URL is on, with its status on
+     * this client; null for any other URL, and for every URL before a sync served one. The
+     * adapters pause every request to that origin and judge it with
+     * classifyVerifoneProfileRequest. A raw runtime that pauses one must never continue a
+     * body carrying a verifone.js blob there unless authorize() paid it.
+     */
+    verifoneProfileOf(url: string): VerifoneProfile | null;
+    /** The armed Verifone profile with this id, or null. */
+    verifoneProfile(id: string): VerifoneProfile | null;
+    /** Fetch.enable globs for every armed Verifone profile's endpoint origins; none before a sync served one. */
+    verifoneProfileUrlPatterns(): string[];
     /**
      * 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
@@ -780,21 +1161,52 @@ export declare class VaultClient {
      * after syncRegistry; a sync changes only a profile's status.
      */
     merchantProfileUrlPatterns(): string[];
-    /** True when this request is a card tokenization we can take over. */
+    /**
+     * The card-on-file policy the API served with the recognizer for this
+     * request (Recognizer.cardOnFile), or null when no recognizer matches or
+     * its entry names none. The Datatrans gate refuses a post that asks to keep
+     * the card on file only while this is `refuse` or a value it does not know.
+     */
+    cardOnFilePolicy(url: string, method?: string): string | null;
+    /**
+     * True when this request is a card tokenization we can take over: a POST to
+     * a recognized endpoint, or for a recognizer whose card request is a GET
+     * (Worldpay eProtect) that exact GET, query included.
+     */
     isCardRequest(url: string, method?: string): boolean;
+    /**
+     * Whether the current registry holds this processor's recognizer. A
+     * processor that ships dark is served only to a build that declares its
+     * capability (syncRegistry does), so before a sync, or against an API that
+     * withheld it, the adapters leave that processor's traffic exactly as they
+     * found it. prepare() asks this for ACI, whose card-number request names a
+     * checkout id the merchant mints only at Pay time, and for a processor whose
+     * card request is a GET (Worldpay eProtect), since that request is recognized
+     * by a query the page has not written yet.
+     */
+    recognizesProcessor(psp: string): boolean;
     /**
      * What happens to a card request (by URL) whose body carries no card: null
      * when it carries one, so it is a card request as usual; 'continue' when the
      * recognizer marks the endpoint as one where such requests are routine and
      * never ours; 'refuse' otherwise, such as a Stripe confirmation paying with
-     * a method this checkout never approved. The adapters ask only after their
-     * holds, so a request that would reuse an approved token is refused there
-     * first. A body that could not be read is not judged here.
+     * a method this checkout never approved. The adapters continue a 'continue'
+     * in every state and judge a 'refuse' after their holds. A body that could
+     * not be read is not judged here.
+     *
+     * `handedTo` lists the requests the attachment has already handed the card
+     * to (CheckoutLifecycle.cardHandoffs). Once one of them went to the same
+     * processor, a processor in CARD_FREE_AFTER_HANDOFF_REFUSED answers 'refuse'
+     * where it would have answered 'continue'.
+     *
+     * A sandbox client's loopback fixture is judged on the processor's own
+     * hosts, as it is recognised (urlsOnProcessorHosts), so a card-free request
+     * the catalog lets through there continues on the fixture too.
      */
-    withoutCard(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
+    withoutCard(url: string, body: string | null | undefined, handedTo?: readonly string[]): 'continue' | 'refuse' | null;
     /**
-     * How the card would reach the processor on this request (`token`, `cse`
-     * or `hosted_form`; absent on the entry means `token`), or null when the
+     * How the card would reach the processor on this request (`token`, `cse`,
+     * `hosted_form` or `device_encrypt`; absent on the entry means `token`), or null when the
      * registry does not recognize it. The adapters read it to decide whether an
      * approval outlives the page's own request: a hosted form is a navigation
      * and cannot.
@@ -812,10 +1224,35 @@ export declare class VaultClient {
      * these patterns pause.
      */
     cardUrlPatterns(): string[];
+    /**
+     * What to type into a checkout so the page's own card facts match the stored card that
+     * pays (see PlaceholderCard): read from GET /api/v2/vault_cards, which lists each stored card's
+     * network and expiry. `cardId` names the stored card; omitted, the user's most recently added
+     * card. Pin the returned `cardId` on the attachment or authorize(), so the approval page
+     * preselects that card: without a pin the page preselects its own choice (its recommended
+     * card, or the first card the cardholder's device can open), which can be another card. After
+     * prepare(), pass the prepared checkout's `cardId`, the card the cardholder already approved.
+     * The facts hold only while the cardholder pays with that card. Throws PlaceholderCardError
+     * when there is no such card, its network has no placeholder, or it carries no expiry.
+     */
+    placeholderCard(input: {
+        user: string;
+        cardId?: string;
+        signal?: AbortSignal;
+    }): Promise<PlaceholderCard>;
     /** Wait for real device approval before the caller starts native tokenization. */
     prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
     /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
     cancelPreparation(id: string): Promise<void>;
+    /**
+     * Retire a ready preparation whose authorization create has not answered, and name the request
+     * that already holds it. Resolves null once the API confirms no merchant request can bind the
+     * preparation any more (cancelled or expired: the API takes a cancel and a create's bind under one
+     * lock), or the ID of the authorization it is already bound to, which the caller retires like any
+     * other (cancelAuthorization). Rejects when the API confirms neither. The Amadeus send window uses
+     * it (amadeus.ts).
+     */
+    retirePreparation(id: string): Promise<string | null>;
     observePreparation(id: string, guidance: 'presented_not_filled' | 'not_presented', reason?: string): Promise<void>;
     reportDuplicateGuard(authorizationId: string): Promise<void>;
     /**
@@ -872,6 +1309,49 @@ export declare class VaultClient {
         amount: number;
         currency: string;
     }>;
+    /**
+     * Ask whether the page may save the card with the Stripe payment method an
+     * approval produced: a SetupIntent confirm that carries no card and pays with
+     * exactly the approved payment method (the page's own, or written by the
+     * adapters in place of a card the confirm carries again).
+     * The API allows a card save only for a company Agentcard turned it on for,
+     * for an approval given on the Vault page, not by voice, with no amount, and
+     * a SetupIntent Stripe reports still confirmable on the same Stripe account;
+     * any other answer rejects with a CheckoutApiError whose code says why (for
+     * example `continuation_invalid` where it is off, `amount_mismatch`). Nothing
+     * is charged: the adapters continue the page's request once this resolves.
+     */
+    checkStripeSetupContinuation(authorizationId: string, request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }): Promise<{
+        setupIntentId: string;
+    }>;
+    /**
+     * Create a merchant-session probe, the phase-0 read of the deterministic merchant total:
+     * `user` is the org's connected user, who opens the returned Vault link and reads the
+     * merchant's own total once through Agentcard's merchant-session relay. The capture is
+     * the merchant's cookie jar as captureMerchantSession read it; the capture rules run
+     * again here, so no bot-manager cookie and no signed-in session ever leaves. No card is
+     * involved. The API answers 404 for every org not on its probe list.
+     */
+    createMerchantSessionProbe(input: {
+        user: string;
+        capture: MerchantSessionCapture;
+    }): Promise<{
+        id: string;
+        profile: string;
+        approvalUrl: string;
+        expiresAt: string;
+    }>;
+    /**
+     * Record the same read made from the autopilot egress by the rustls runner (the API's
+     * egressResultSchema: statuses, header names, sizes, times, totals, hashes and the
+     * certificate chain's SPKI hashes). Once per probe.
+     */
+    recordMerchantSessionEgress(probeId: string, result: unknown): Promise<void>;
     /**
      * 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`