@paydock/client-sdk 1.143.0-beta → 1.144.0-beta

package/bundles/widget.umd.js.d.ts

@@ -291,6 +291,65 @@ declare class Api extends ApiBase {
     charge(): ApiCharge;
 }
 
+/**
+ * Decoded payload of the Standalone 3DS charge token (the JWT body) the SDK
+ * receives in `Canvas3ds`'s constructor when the token format is `standalone_3ds`.
+ *
+ * This shape is set by the Paydock backend when minting the token. Integrators
+ * who decode the token themselves can use this interface to type the result.
+ */
+interface ITokenStandalone3DS {
+    /** Optional merchant-side correlation identifier carried through from the original charge request. */
+    external_id?: string;
+    /** URL of the first iframe the SDK loads to bootstrap the 3DS provider's authentication flow. */
+    initialization_url: string;
+    /**
+     * @deprecated No longer read by the Standalone 3DS flow. The field is kept
+     * on the interface for backwards compatibility with tokens minted by older
+     * API versions; it will be removed in a future major release. Prefer
+     * `initialization_url` + `secondary_url`.
+     */
+    authorization_url?: string;
+    /** Optional URL of a secondary iframe used by some providers (e.g. GPayments) for monitoring/polling alongside the main flow. */
+    secondary_url?: string;
+    /** The Paydock 3DS charge identifier this token authorizes. Echoed back in every event payload emitted during the flow. */
+    charge_3ds_id: string;
+    /** Identifier of the 3DS gateway the SDK should delegate to. Currently only `'GPayments'` is handled; other values fall through. */
+    service_type: string;
+}
+declare class Standalone3dsService {
+    protected container: Container;
+    protected eventEmitter: EventEmitter;
+    protected env: string;
+    protected alias: string;
+    constructor(container: Container, eventEmitter: any);
+    load(token: string, options: {
+        title: string;
+    }): void;
+    setEnv(env: string, alias?: string): void;
+}
+
+declare class IFrame {
+    protected container: Container;
+    constructor(container: Container);
+    load(link: string, options?: {
+        title?: string;
+        attributes?: Record<string, string>;
+        styles?: Record<string, string>;
+    }, iframeClass?: string): void;
+    loadFromHtml(content: string, options?: {
+        title?: string;
+    }, iframeClass?: string): void;
+    remove(): void;
+    show(): void;
+    hide(saveSize?: boolean): void;
+    isExist(): boolean;
+    getElement(): HTMLIFrameElement;
+    setStyle(property: string, value: string): void;
+    setIframeHeight(iframeElement: HTMLIFrameElement, iFrameDocument: Document, selector: string): void;
+    private setStyles;
+}
+
 /**
  * List of available form field validators dedicated to cards and their definition
  *
@@ -704,65 +763,57 @@ type WalletRawDataInitialization = {
 } | object;
 type ApplePayRawDataInitialization = ApplePayJS.ApplePayPaymentRequest;
 type GooglePayRawDataInitialization = google.payments.api.IsReadyToPayPaymentMethodSpecification | google.payments.api.PaymentMethodSpecification;
+/**
+ * Metadata for the multi-wallet `WalletButtons` container (chargeToken-based flow).
+ * Drives the appearance and behavior of every wallet button rendered by the container.
+ *
+ * Most fields are optional because their defaults are derived from the chargeToken
+ * the constructor decodes; set them explicitly only to override.
+ */
 interface IWalletMeta {
+    /** Label shown next to the total in the wallet sheet (e.g. `'TOTAL'`). */
     amount_label?: string;
+    /** ISO 3166-1 alpha-2 country code for the transaction (e.g. `'AU'`). */
     country?: string;
+    /** Enable PayPal's Pay Later messaging when the PayPal wallet is rendered. */
     pay_later?: boolean;
+    /** Hide PayPal's Pay Later message copy. */
     hide_message?: boolean;
+    /** Render the PayPal standalone button instead of the smart button group. */
     standalone?: boolean;
+    /** Whether to surface billing address fields in the wallet sheet. */
     show_billing_address?: boolean;
+    /** Whether to collect the payer's name. */
     request_payer_name?: boolean;
+    /** Whether to collect the payer's email. */
     request_payer_email?: boolean;
+    /** Whether to collect the payer's phone number. */
     request_payer_phone?: boolean;
+    /** Whether to collect a shipping address. */
     request_shipping?: boolean;
+    /** Available shipping options to display. The first item is selected by default. */
     shipping_options?: IShippingOption[];
+    /** Merchant display name shown in the wallet sheet. */
     merchant_name?: string;
+    /** Wallet-native payment request objects passed through verbatim (advanced — overrides SDK defaults). */
     raw_data_initialization?: WalletRawDataInitialization;
+    /** Optional access token for wallets that require additional auth beyond the chargeToken. */
     access_token?: string;
+    /** Optional refresh token paired with `access_token`. */
     refresh_token?: string;
+    /** Visual styling overrides for the wallet buttons. */
     style?: WalletStyles;
+    /** Restrict which wallets the container should render. Defaults to all wallets the chargeToken authorizes. */
     wallets?: WALLET_TYPE[];
+    /** Optional client identifier passed through to the wallet provider when required. */
     client_id?: string;
+    /**
+     * Apple Pay device capabilities allowed for the button to be considered available.
+     * Used as a relaxation knob for testing — defaults to `['paymentCredentialsAvailable']` only.
+     */
     apple_pay_capabilities?: Array<'credentials_available' | 'credentials_status_unknown' | 'credentials_unavailable'>;
 }
 
-declare class Link {
-    protected env: Env;
-    protected linkResource: string;
-    protected params: IParams;
-    protected widgetId: string;
-    constructor(linkResource: string);
-    getNetUrl(): string;
-    getUrl(): string;
-    setParams(params: IParams | IWalletParams | ISRCParams): void;
-    concatParams(params: IParams): void;
-    getParams(): IParams;
-    setEnv(env: string, alias?: string): void;
-    getEnv(): string;
-    getBaseUrl(): string;
-}
-
-declare class IFrame {
-    protected container: Container;
-    constructor(container: Container);
-    load(link: string, options?: {
-        title?: string;
-        attributes?: Record<string, string>;
-        styles?: Record<string, string>;
-    }, iframeClass?: string): void;
-    loadFromHtml(content: string, options?: {
-        title?: string;
-    }, iframeClass?: string): void;
-    remove(): void;
-    show(): void;
-    hide(saveSize?: boolean): void;
-    isExist(): boolean;
-    getElement(): HTMLIFrameElement;
-    setStyle(property: string, value: string): void;
-    setIframeHeight(iframeElement: HTMLIFrameElement, iFrameDocument: Document, selector: string): void;
-    private setStyles;
-}
-
 /**
  * List of available payment source types
  *
@@ -971,6 +1022,22 @@ declare class Trigger {
     push(triggerName: string, data?: ITriggerData): void;
 }
 
+declare class Link {
+    protected env: Env;
+    protected linkResource: string;
+    protected params: IParams;
+    protected widgetId: string;
+    constructor(linkResource: string);
+    getNetUrl(): string;
+    getUrl(): string;
+    setParams(params: IParams | IWalletParams | ISRCParams): void;
+    concatParams(params: IParams): void;
+    getParams(): IParams;
+    setEnv(env: string, alias?: string): void;
+    getEnv(): string;
+    getBaseUrl(): string;
+}
+
 /**
  * Current constant include available type of element for styling
  * @const STYLABLE_ELEMENT
@@ -1069,42 +1136,90 @@ interface IElementStyleTitleDescription {
     margin?: string;
 }
 
+/**
+ * Top-level classification of an error. Used by the SDK to route errors to the
+ * right category in instrumentation and to give consumers a coarse-grained
+ * tag for grouping/filtering. See {@link getErrorCategory} for the mapping
+ * between {@link ERROR_CAUSE} and {@link ERROR_CATEGORY}.
+ */
 declare const ERROR_CATEGORY: {
+    /** SDK was misconfigured (missing keys, invalid options, etc.). */
     readonly CONFIGURATION: "configuration";
+    /** Authentication or authorization failure. */
     readonly IDENTITY: "identity_access_management";
+    /** SDK internal failure or upstream service problem. */
     readonly INTERNAL: "internal";
+    /** Flow lifecycle event (user cancelled, aborted, etc.) — not a real fault. */
     readonly PROCESS: "process";
+    /** Resource lookup failed or was rate-limited. */
     readonly RESOURCE: "resource";
+    /** Invalid input or business-rule validation failure. */
     readonly VALIDATION: "validation";
 };
 type ErrorCategory = (typeof ERROR_CATEGORY)[keyof typeof ERROR_CATEGORY];
+/**
+ * Concrete cause of an error. More specific than {@link ERROR_CATEGORY} —
+ * useful for deciding programmatic responses (e.g. show a retry button only
+ * when `cause` is `'service_unreachable'` or `'server_busy'`).
+ */
 declare const ERROR_CAUSE: {
+    /** Operation was aborted programmatically. */
     readonly ABORTED: "aborted";
+    /** Caller has insufficient permissions for the operation. */
     readonly ACCESS_FORBIDDEN: "access_forbidden";
+    /** Resource already exists when create was expected. */
     readonly ALREADY_EXISTS: "already_exists";
+    /** User cancelled the flow (e.g. closed the wallet sheet). */
     readonly CANCELED: "canceled";
+    /** SDK was instantiated or invoked with invalid configuration. */
     readonly INVALID_CONFIGURATION: "invalid_configuration";
+    /** Input failed structural or business-rule validation. */
     readonly INVALID_INPUT: "invalid_input";
+    /** Resource was not found by the backend. */
     readonly NOT_FOUND: "not_found";
+    /** Operation is not supported in the current context or version. */
     readonly NOT_IMPLEMENTED: "not_implemented";
+    /** Caller exceeded the allowed request rate. */
     readonly RATE_LIMITED: "rate_limited";
+    /** Backend is healthy but currently overloaded — typically retryable. */
     readonly SERVER_BUSY: "server_busy";
+    /** Backend or third-party service could not be reached — typically retryable. */
     readonly SERVICE_UNREACHABLE: "service_unreachable";
+    /** Caller is not authenticated. */
     readonly UNAUTHORIZED: "unauthorized";
+    /** Catch-all when no other cause applies. */
     readonly UNKNOWN: "unknown_error";
+    /** Request was syntactically valid but semantically rejected. */
     readonly UNPROCESSABLE_ENTITY: "unprocessable_entity";
 };
 type ErrorCause = (typeof ERROR_CAUSE)[keyof typeof ERROR_CAUSE];
+/**
+ * Diagnostic detail attached to every {@link IEventError}.
+ * Useful for logging, surfacing user-facing messages, and correlating with
+ * server-side logs via `contextId`.
+ */
 interface ErrorDetails {
+    /** Concrete cause classification (mirrors the top-level `cause` on `IEventError`). */
     cause: ErrorCause;
+    /** Correlation identifier — typically a request id or trace id from the backend. Empty string when none is available. */
     contextId: string;
+    /** Human-readable message safe to surface to developers (NOT necessarily safe for end-users). */
     message: string;
+    /** ISO 8601 UTC timestamp captured at error creation time. */
     timestamp: string;
 }
+/**
+ * Standard error envelope emitted by the SDK on event payloads (`IEventData.error`)
+ * and exposed publicly so integrators can `instanceof`/structurally narrow against it.
+ */
 interface IEventError {
+    /** Concrete cause of the error. See {@link ERROR_CAUSE} for the full list. */
     cause: ErrorCause;
+    /** Coarse-grained category derived from `cause`. See {@link ERROR_CATEGORY}. */
     category: ErrorCategory;
+    /** Whether the operation can be retried as-is. Must be set explicitly by the producer; `EventError.create()` defaults it to `false`. The intended candidates for `true` are transient causes such as `service_unreachable` and `server_busy`. */
     retryable: boolean;
+    /** Diagnostic detail (message, timestamp, correlation id). */
     details: ErrorDetails;
 }
 
@@ -2129,7 +2244,7 @@ interface IEventData$1 {
     ref_id?: string;
     error?: IEventError;
 }
-declare const EVENT$2: {
+declare const EVENT$3: {
     readonly AFTER_LOAD: "afterLoad";
     readonly SUBMIT: "submit";
     readonly FINISH: "finish";
@@ -2161,7 +2276,7 @@ declare const EVENT$2: {
     readonly DISPATCH_SUCCESS: "dispatchSuccess";
     readonly DISPATCH_ERROR: "dispatchError";
 };
-type EventTypes = typeof EVENT$2[keyof typeof EVENT$2];
+type EventTypes = typeof EVENT$3[keyof typeof EVENT$3];
 interface Listener {
     event: string;
     listener: (event: any) => void;
@@ -2177,17 +2292,99 @@ declare class IFrameEvent {
     private subscribe;
 }
 
-declare class Standalone3dsService {
-    protected container: Container;
-    protected eventEmitter: EventEmitter;
-    protected env: string;
-    protected alias: string;
-    constructor(container: Container, eventEmitter: any);
-    load(token: string, options: {
-        title: string;
-    }): void;
-    setEnv(env: string, alias?: string): void;
+/**
+ * Payload emitted by the Standalone 3DS flow for auth-related events
+ * (chargeAuthSuccess, chargeAuthReject, chargeAuthChallenge, chargeAuthDecoupled).
+ */
+interface Canvas3dsAuthPayload {
+    /** The Paydock 3DS charge identifier (e.g. `'chrg_3ds_xxxxx'`) used to correlate the authentication with the underlying charge. */
+    charge_3ds_id: string;
+    /** Authentication outcome status reported by the 3DS provider (e.g. `'authenticated'`, `'rejected'`, `'pending'`). */
+    status: string;
+    /** Optional result details. Present when the 3DS provider returns additional context for the outcome. */
+    result?: {
+        /** Human-readable description of the outcome (e.g. `'frictionless'`). */
+        description?: string;
+    };
 }
+/**
+ * Payload emitted by the Standalone 3DS flow for error events.
+ * `error` is intentionally `unknown` — upstream emitters do not guarantee a shape.
+ */
+interface Canvas3dsErrorPayload {
+    /** The Paydock 3DS charge identifier associated with the failed authentication attempt. */
+    charge_3ds_id: string;
+    /** The underlying error. Typed as `unknown` to force the consumer to narrow it before use. */
+    error: unknown;
+}
+/**
+ * Payload emitted by the iframe-based 3DS flow for auth-related events
+ * (`chargeAuth`, `chargeAuthSuccess`, `chargeAuthReject`).
+ *
+ * Extends `IEventData` with optional 3DS-specific fields that the widget
+ * merges into the message envelope for charge correlation.
+ */
+interface Canvas3dsChargeAuthEventPayload extends IEventData$1 {
+    /** The Paydock 3DS charge identifier. Present when the widget correlates the event with a charge. */
+    charge_3ds_id?: string;
+    /** Authentication outcome status reported by the widget (e.g. `'authenticated'`, `'server_error'`). */
+    status?: string;
+    /** Optional result details forwarded from the 3DS provider. */
+    result?: {
+        /** Human-readable description of the outcome (e.g. `'frictionless'`). */
+        description?: string;
+    };
+}
+/**
+ * Payload emitted by the iframe-based 3DS flow for error events.
+ * Extends `IEventData` with optional 3DS-specific fields for charge correlation.
+ */
+interface Canvas3dsErrorEventPayload extends IEventData$1 {
+    /** The Paydock 3DS charge identifier associated with the error. */
+    charge_3ds_id?: string;
+}
+/**
+ * Maps Canvas3ds event names to their callback data types.
+ *
+ * Events that can fire from both the iframe (html/url) and standalone flows
+ * use a union to accommodate both shapes. Standalone-only and iframe-only events
+ * use a single payload type.
+ */
+interface Canvas3dsEventMap {
+    /** Successful authentication. Standalone path emits `Canvas3dsAuthPayload`; iframe path emits `Canvas3dsChargeAuthEventPayload`. Narrow with `'event' in data` for iframe vs standalone. */
+    chargeAuthSuccess: Canvas3dsAuthPayload | Canvas3dsChargeAuthEventPayload;
+    /** Rejected authentication. Same dual-emit pattern as `chargeAuthSuccess`. */
+    chargeAuthReject: Canvas3dsAuthPayload | Canvas3dsChargeAuthEventPayload;
+    /** Authentication or processing error. Standalone path emits `Canvas3dsErrorPayload`; iframe path emits `Canvas3dsErrorEventPayload`. */
+    error: Canvas3dsErrorPayload | Canvas3dsErrorEventPayload;
+    /** Challenge required — issuer demands user interaction (OTP, biometric, etc.). Standalone-only. */
+    chargeAuthChallenge: Canvas3dsAuthPayload;
+    /** Decoupled authentication — issuer will authenticate out-of-band and notify later. Standalone-only. */
+    chargeAuthDecoupled: Canvas3dsAuthPayload;
+    /** Iframe-path authentication event. Extends `IEventData` with optional 3DS correlation fields (`charge_3ds_id`, `status`). */
+    chargeAuth: Canvas3dsChargeAuthEventPayload;
+    /** User cancelled the authentication flow before completion. Iframe-only. */
+    chargeAuthCancelled: IEventData$1;
+    /** Additional data collection step completed successfully. Iframe-only. */
+    additionalDataCollectSuccess: IEventData$1;
+    /** Additional data collection step was rejected. Iframe-only. */
+    additionalDataCollectReject: IEventData$1;
+}
+/** Union of all known Canvas3ds event names. */
+type Canvas3dsEventName = keyof Canvas3dsEventMap;
+/**
+ * Public, tree-shakeable alias for the internal `TOKEN_FORMAT` enum in canvas-3ds.ts.
+ * Mirrors the string values of that enum without exposing the private enum itself.
+ */
+declare const Canvas3dsTokenFormat: {
+    /** Token whose `content` is a complete HTML page. The SDK renders it inside an iframe. */
+    readonly HTML: "html";
+    /** Token whose `content` is a URL. The SDK loads it inside an iframe. */
+    readonly URL: "url";
+    /** Token whose `content` describes a standalone 3DS service (e.g. GPayments). The SDK delegates to that service's flow. */
+    readonly STANDALONE_3DS: "standalone_3ds";
+};
+type Canvas3dsTokenFormat = (typeof Canvas3dsTokenFormat)[keyof typeof Canvas3dsTokenFormat];
 
 /**
  * List of available token's content formats
@@ -2223,7 +2420,7 @@ declare enum TOKEN_FORMAT {
  * @param {string} CHARGE_AUTH_CHALLENGE=chargeAuthChallenge
  * @param {string} CHARGE_AUTH_INFO=chargeAuthInfo
  * @param {string} ERROR=error
-*/
+ */
 /**
  * Class Canvas3ds include method for working on html
  * @constructor
@@ -2271,8 +2468,10 @@ declare class Canvas3ds {
      */
     setEnv(env: string, alias?: string): void;
     getEnv(): string;
+    on<E extends keyof Canvas3dsEventMap>(eventName: E, cb: (data: Canvas3dsEventMap[E]) => void): void;
+    on<E extends keyof Canvas3dsEventMap>(eventName: E): Promise<Canvas3dsEventMap[E]>;
+    on(eventName: string, cb: (data: IEventData$1) => void): void;
     on(eventName: string): Promise<IEventData$1>;
-    on(eventName: string, cb: (data: IEventData$1) => void): any;
     /**
      * Using this method you can hide widget after load
      * @param {boolean} [saveSize=false] - using this param you can save iframe's size
@@ -2290,6 +2489,59 @@ declare class Canvas3ds {
     reload(): void;
 }
 
+/**
+ * Canonical shared response shapes used by both Charge and Checkout internal APIs.
+ * Extracted here to remove the prior duplicated definitions in
+ * api-charge-internal.ts and api-checkout-internal.ts.
+ */
+interface HandleResponseInterface {
+    status: string;
+    error: string;
+    result: {
+        reference: string;
+        reference_2: string;
+        identifier: string;
+        identifier_2: string;
+        identifier_3: string;
+        identifier_4: string;
+        identifier_5: string;
+        type: string;
+        status: string;
+        status_2: string;
+        status_code: string;
+        ref_token: string;
+        cancellation: string;
+        count: string;
+        version: string;
+        whitelist: {
+            status: string;
+            source: string;
+        };
+        result: string;
+    };
+}
+interface ProcessAuthenticationResponse {
+    status: string;
+    error?: string;
+    result?: {
+        challenge: string;
+        challenge_url: string;
+        decoupled_challenge: boolean;
+        frictionless: boolean;
+        identifier: string;
+        identifier_3: string;
+        identifier_4: string;
+        reference: string;
+        reference_2: string;
+        secondary_url: string;
+        skipped: boolean;
+        status: string;
+        type: string;
+        version: string;
+        description?: string;
+    };
+}
+
 declare class ApiChargeInternal {
     protected api: ApiInternal;
     constructor(api: ApiInternal);
@@ -2339,52 +2591,14 @@ interface WalletCallbackResponse {
 interface Standalone3dsProcessBody {
     charge_3ds_id: string;
 }
-interface HandleResponseInterface {
-    status: string;
-    error: string;
-    result: {
-        reference: string;
-        reference_2: string;
-        identifier: string;
-        identifier_2: string;
-        identifier_3: string;
-        identifier_4: string;
-        identifier_5: string;
-        type: string;
-        status: string;
-        status_2: string;
-        status_code: string;
-        ref_token: string;
-        cancellation: string;
-        count: string;
-        version: string;
-        whitelist: {
-            status: string;
-            source: string;
-        };
-        result: string;
-    };
-}
-interface ProcessAuthenticationResponse {
-    status: string;
-    error?: string;
-    result?: {
-        challenge: string;
-        challenge_url: string;
-        decoupled_challenge: boolean;
-        frictionless: boolean;
-        identifier: string;
-        identifier_3: string;
-        identifier_4: string;
-        reference: string;
-        reference_2: string;
-        secondary_url: string;
-        skipped: boolean;
-        status: string;
-        type: string;
-        version: string;
-        description?: string;
-    };
+
+declare class ApiCheckoutInternal {
+    protected api: ApiInternal;
+    constructor(api: ApiInternal);
+    instructions(): Observable<object>;
+    private getInstructionLink;
+    callback(payload: Object): Promise<Object>;
+    status(id: string): Promise<Object>;
 }
 
 declare class ApiGatewayInternal {
@@ -2448,80 +2662,184 @@ declare enum WALLET_TYPES {
     GOOGLE_PAY = "google"
 }
 
+/**
+ * The created One-Time Token (OTT) returned by the SDK after the user authorizes
+ * a wallet payment. Use `temp_token` server-side to create the actual charge via
+ * `POST /v1/charges` (or equivalent).
+ */
 interface CreateOTTResponse {
+    /** The temporary one-time token string. Single use, short TTL — exchange it server-side immediately. */
     temp_token: string;
+    /** Token classification. `CARD` for FPAN (Google Pay only); `CARD_SCHEME_TOKEN` for DPAN (Apple Pay & Google Pay). */
     token_type: TOKEN_TYPE;
 }
+/**
+ * Billing address captured from the wallet payment sheet, when requested via
+ * `required_billing_contact_fields` (Apple Pay) or equivalent (Google Pay).
+ */
 interface Billing {
+    /** First street address line. */
     address_line1: string;
+    /** Second street address line. Empty string when the wallet did not provide it. */
     address_line2: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. `'AU'`, `'US'`). */
     address_country: string;
+    /** City. */
     address_city: string;
+    /** Postal/ZIP code. */
     address_postcode: string;
+    /** State or administrative area (e.g. `'NSW'`, `'CA'`). */
     address_state: string;
 }
+/**
+ * Card details captured when the wallet returns a card-scheme token (DPAN).
+ * Only the non-sensitive metadata is exposed — full card numbers never reach the SDK.
+ */
 interface CardInfo {
+    /** Card network identifier from the wallet (e.g. `'visa'`, `'mastercard'`, `'amex'`). */
     card_scheme: string;
+    /** Last 4 digits of the card, when the wallet provider exposes them. */
     card_number_last4?: string;
 }
+/**
+ * Internal payload the SDK sends to Paydock when creating a One-Time Token.
+ * Exposed publicly so integrators can construct fixtures for testing.
+ */
 interface CreateOTTData {
+    /** Charge amount as a number (e.g. `19.99`). */
     amount: number;
+    /** Shipping address and contact info captured from the wallet. */
     shipping: Shipping;
+    /** Billing address captured from the wallet. */
     billing: Billing;
+    /** Card metadata captured from the wallet (network, last 4). */
     card_info: CardInfo;
+    /** Wallet-provider reference token (DPAN/FPAN payload) used by Paydock to settle the charge. */
     ref_token: string;
 }
+/**
+ * Request body used internally when calling Paydock's OTT-creation endpoint.
+ * Exposed publicly so integrators can mirror the shape if they need to. */
 interface CreateOTTRequest {
+    /** The Paydock service ID configured in the merchant dashboard for this wallet. */
     service_id: string;
+    /** Wallet type identifier (Apple Pay, Google Pay, etc.). */
     service_type: SERVICE_TYPES;
+    /** Service group classification (e.g. `'WALLET'`). */
     service_group: SERVICE_GROUP;
+    /** Encrypted/encoded payload from the wallet (DPAN/FPAN data). */
     payload: string;
+    /** Encoding format of `payload` — currently `'encrypted_string'`. */
     payload_format: PAYLOAD_FORMAT;
 }
+/**
+ * Request body sent when initiating a wallet session against Paydock
+ * (used by the Apple Pay merchant validation flow).
+ */
 interface CreateSessionRequest {
+    /** The Paydock service ID for the wallet. */
     service_id: string;
+    /** Caller-controlled session identifier — Paydock binds the session to this id. */
     session_id: string;
+    /** Whether the wallet sheet should ask the user for shipping. */
     request_shipping?: boolean;
+    /** Merchant store name displayed in the wallet sheet. */
     store_name: string;
 }
+/**
+ * Response returned by Paydock after creating a wallet session.
+ * Used internally by the SDK to drive merchant validation; rarely consumed directly.
+ */
 interface CreateSessionResponse {
+    /** Paydock session identifier. */
     id: string;
+    /** Session status (e.g. `'active'`). */
     status: string;
+    /** HTTP method the SDK should use to invoke the callback URL. */
     callback_method: string;
+    /** Relation/role of the callback (e.g. `'merchant_validation'`). */
     callback_rel: string;
+    /** URL the SDK calls to complete the merchant validation step. */
     callback_url: string;
 }
+/**
+ * Union of the native wallet authorization payloads the SDK may receive
+ * from Apple Pay or Google Pay at the moment of payment authorization.
+ * Used internally; rarely exposed to integrators directly.
+ */
 type CheckoutResponse = ApplePayJS.ApplePayPaymentAuthorizedEvent | google.payments.api.PaymentAuthorizationResult | google.payments.api.PaymentData;
+/**
+ * Action codes returned by the SDK during the wallet checkout lifecycle.
+ * Mirrors the ApplePay payment authorization completion codes used internally
+ * to decide what UI/state transition to perform next.
+ */
 declare enum CheckoutActionCode {
+    /** Payment completed successfully. */
     COMPLETE = "COMPLETE",
+    /** User cancelled the wallet sheet. */
     CANCEL = "CANCEL",
+    /** An error occurred during payment authorization. */
     ERROR = "ERROR",
+    /** User opted to switch to a different card in the wallet. */
     CHANGE_CARD = "CHANGE_CARD",
+    /** User opted to add a new card to the wallet. */
     ADD_CARD = "ADD_CARD",
+    /** User switched to a different consumer (Click to Pay flow). */
     SWITCH_CONSUMER = "SWITCH_CONSUMER"
 }
+/**
+ * Token response shape returned by Paydock after creating an OTT.
+ * Used by the SDK to decide whether a follow-up 3DS step is required.
+ */
 interface OTTResponse {
+    /** The OTT string. */
     token: string;
+    /** Token type identifier (string form of {@link TOKEN_TYPE}). */
     token_type: string;
+    /** When `true`, the integrator must invoke a Canvas3DS step before settling the charge. */
     three_ds_required?: boolean;
+    /** Which wallet produced the token (Apple Pay or Google Pay). */
     wallet_type: WalletType;
 }
+/**
+ * Shipping address and contact information captured from the wallet payment sheet,
+ * when requested via `request_shipping` (and friends) on the wallet meta.
+ *
+ * All fields are optional because each wallet provider returns a different subset.
+ * Address line fields are typically Apple Pay-only (Google Pay returns a coarser shape).
+ */
 interface Shipping {
+    /** Selected shipping method identifier (e.g. `'standard'`, `'express'`). */
     method?: string;
+    /** Updated shipping options that were available when the user made their selection. */
     options?: IShippingOption[];
+    /** First street address line (Apple Pay only). */
     address_line1?: string;
+    /** Second street address line (Apple Pay only). */
     address_line2?: string;
+    /** City. */
     address_city?: string;
+    /** Postal/ZIP code. */
     address_postcode?: string;
+    /** State or administrative area. */
     address_state?: string;
+    /** ISO 3166-1 alpha-2 country code. */
     address_country?: string;
+    /** Company name on the address (when the wallet captured it). */
     address_company?: string;
+    /** Origin postal code — used for shipping calculations when the merchant ships from a fixed location. */
     address_origin_postcode?: string;
+    /** Shipping contact information (Apple Pay only). */
     contact?: {
+        /** Contact first name. */
         first_name?: string;
+        /** Contact last name. */
         last_name?: string;
+        /** Contact email address. */
         email?: string;
+        /** Contact phone number. */
         phone?: string;
+        /** Contact secondary phone number. */
         phone2?: string;
     };
 }
@@ -2541,13 +2859,52 @@ declare class ApiInternal extends ApiBase {
     paymentSource(): ApiPaymentSourceInternal;
 }
 
-declare class ApiCheckoutInternal {
-    protected api: ApiInternal;
-    constructor(api: ApiInternal);
-    instructions(): Observable<object>;
-    private getInstructionLink;
-    callback(payload: Object): Promise<Object>;
-    status(id: string): Promise<Object>;
+/**
+ * Public alias for GPAYMENTS_EVENT. Same object reference — no behavioral change.
+ * Prefer `CANVAS_3DS_EVENT` in public-facing code; `GPAYMENTS_EVENT` remains for
+ * backwards-compatible internal usage.
+ */
+declare const CANVAS_3DS_EVENT: {
+    /** Authentication succeeded. Payload: `Canvas3dsAuthPayload`. */
+    readonly AUTH_SUCCESS: "chargeAuthSuccess";
+    /** Authentication failed — covers issuer rejection, iframe timeout (`AuthTimedOut`), and invalid-event outcomes. Payload: `Canvas3dsAuthPayload`. */
+    readonly AUTH_ERROR: "chargeAuthReject";
+    /** Decoupled authentication — issuer will authenticate out-of-band. Payload: `Canvas3dsAuthPayload`. */
+    readonly DECOUPLED: "chargeAuthDecoupled";
+    /** Challenge required — issuer demands user interaction. Payload: `Canvas3dsAuthPayload`. */
+    readonly CHALLENGE: "chargeAuthChallenge";
+    /** Informational signal emitted by the GPayments flow. Internal — not part of the public typed surface. */
+    readonly INFO: "chargeAuthInfo";
+    /** Error during the flow (network, parsing, etc.). Payload: `Canvas3dsErrorPayload`. */
+    readonly ERROR: "error";
+};
+
+/**
+ * Payload emitted by `Checkout.onPaymentSuccessful`.
+ *
+ * Permissively extends `IEventData` because the Checkout emission contract
+ * is not yet fully documented (see D8). This gives a named surface that
+ * integrators can import while keeping the type backwards-compatible with
+ * the raw `IEventData` shape the runtime currently emits.
+ */
+interface CheckoutPaymentSuccessPayload extends IEventData$1 {
+}
+/**
+ * Payload emitted by `Checkout.onPaymentFailure`.
+ *
+ * Permissively extends `IEventData` — same reasoning as
+ * `CheckoutPaymentSuccessPayload`. Tighten in a follow-up once the emission
+ * contract is confirmed.
+ */
+interface CheckoutPaymentFailurePayload extends IEventData$1 {
+}
+/**
+ * Payload emitted by `Checkout.onPaymentExpired`.
+ *
+ * Permissively extends `IEventData` — same reasoning as
+ * `CheckoutPaymentSuccessPayload`.
+ */
+interface CheckoutPaymentExpiredPayload extends IEventData$1 {
 }
 
 type Instruction = new (selector: string, api: ApiInternal, checkoutWidget: Checkout, formSelector?: string) => InstructionHandler & InstructionDestroyable & InstructionDecorated;
@@ -2577,11 +2934,32 @@ declare class InstructionModule {
     getInstruction(id: string): Instruction | null;
 }
 
-interface IntentTokenPayload {
+/** Event name emitted when a checkout payment completes successfully. */
+declare const PAYMENT_SUCCESSFUL = "paymentSuccessful";
+/** Event name emitted when a checkout payment fails. */
+declare const PAYMENT_FAILURE = "paymentFailure";
+/** Event name emitted when a checkout session expires. */
+declare const PAYMENT_EXPIRED = "paymentExpired";
+declare const EVENT$2: {
+    PAYMENT_SUCCESSFUL: string;
+    PAYMENT_FAILURE: string;
+    PAYMENT_EXPIRED: string;
+};
+/**
+ * Decoded payload of the intent JWT the `Checkout` widget receives in its constructor.
+ * Issued by the Paydock backend when a checkout intent is created. Integrators who
+ * decode the token themselves (e.g. for diagnostics) can use this type to inspect it.
+ */
+interface CheckoutIntentTokenPayload {
+    /** Backend environment that minted this token (e.g. `'sandbox'`, `'production'`). */
     env: string;
+    /** The Paydock checkout intent identifier this token authorizes. */
     intent_id: string;
+    /** Token schema version. Used by the SDK for forward/backward compatibility. */
     version: number;
+    /** Human-readable alias for the environment (e.g. `'staging-3'`, `'multitenant-preprod'`). */
     env_alias: string;
+    /** Hostnames the token may be used from. When present, the SDK rejects the token if the current origin is not listed; an absent or empty array allows all origins. */
     whitelist_domains: string[];
 }
 /**
@@ -2601,7 +2979,7 @@ declare class Checkout {
     protected window: Window;
     protected eventEmitter: EventEmitter;
     protected container: Container;
-    protected intentTokenPayload: IntentTokenPayload;
+    protected intentTokenPayload: CheckoutIntentTokenPayload;
     protected api: ApiInternal;
     protected checkoutApi: ApiCheckoutInternal;
     protected instructions: InstructionModule;
@@ -2615,7 +2993,7 @@ declare class Checkout {
     fetchInstruction(): void;
     finaliseCheckout(): void;
     private setupTimeoutTimer;
-    private extractIntentTokenPayload;
+    private extractCheckoutIntentTokenPayload;
     validateJWTWhitelistedDomains(whitelist_domains: string[]): boolean;
     private ready;
     private initContractVersion;
@@ -2634,7 +3012,7 @@ declare class Checkout {
      *      console.log('Payment successful!');
      * });
      */
-    onPaymentSuccessful(handler: (data: IEventData$1) => void): () => void;
+    onPaymentSuccessful<T extends IEventData$1 = CheckoutPaymentSuccessPayload>(handler: (data: T) => void): () => void;
     /**
      * If the payment was not successful, the function passed as parameter will be called.
      * Important: Do not perform thread blocking operations in callback such as window.alert() calls.
@@ -2644,17 +3022,17 @@ declare class Checkout {
      *      console.log('Payment not successful');
      * });
      */
-    onPaymentFailure(handler: (data: IEventData$1) => void): () => void;
+    onPaymentFailure<T extends IEventData$1 = CheckoutPaymentFailurePayload>(handler: (data: T) => void): () => void;
     /**
      * If the payment was expired, the function passed as parameter will be called.
      * Important: Do not perform thread blocking operations in callback such as window.alert() calls.
      *
      * @example
-     * widget.onPaymentInReview((data) => {
-     *      console.log('Payment in fraud review');
+     * widget.onPaymentExpired((data) => {
+     *      console.log('Payment session expired');
      * });
      */
-    onPaymentExpired(handler: (data: IEventData$1) => void): () => void;
+    onPaymentExpired<T extends IEventData$1 = CheckoutPaymentExpiredPayload>(handler: (data: T) => void): () => void;
     createWidgetStructure(): void;
     private changeLoadingSpinnerVisibility;
 }
@@ -3734,6 +4112,18 @@ declare abstract class OpenWalletService implements IOpenWalletProvider {
      * @param meta - The updated metadata.
      */
     abstract setMeta(meta: OpenWalletMeta): void;
+    /**
+     * Returns whether the wallet button is currently disabled.
+     * Reads the `aria-disabled` attribute from the container element — set by the
+     * button class via {@link OpenWalletButtons.disable} / {@link OpenWalletButtons.enable}.
+     *
+     * Used to short-circuit click handlers in concrete wallet services for clicks
+     * that bypass the DOM `pointer-events: none` guard (e.g. invoked by the wallet
+     * provider's SDK callback).
+     *
+     * @returns `true` if the container is marked as disabled, `false` otherwise.
+     */
+    protected isButtonDisabled(): boolean;
     /**
      * Creates a One-Time Token (OTT) by sending the payment data to the API.
      * Emits {@link EVENT.SUCCESS} on success or {@link EVENT.ERROR} on failure.
@@ -3793,6 +4183,7 @@ declare abstract class OpenWalletButtons<TMeta extends OpenWalletMeta = OpenWall
     protected meta: TMeta;
     protected eventEmitter: EventEmitter;
     protected walletService: OpenWalletService | undefined;
+    protected isDisabled: boolean;
     private onShippingOptionsChangeHandlerRegistered;
     /** @private */
     abstract readonly walletType: WalletType;
@@ -3849,6 +4240,42 @@ declare abstract class OpenWalletButtons<TMeta extends OpenWalletMeta = OpenWall
      * button.load();
      */
     load(): void;
+    /**
+     * Enables the wallet button, restoring interactivity and visual appearance.
+     * If the button was previously disabled via `disable()`, calling this method
+     * re-enables clicks and removes the disabled visual state.
+     *
+     * Idempotent — calling on an already-enabled button has no effect.
+     *
+     * @example
+     * button.enable();
+     */
+    enable(): void;
+    /**
+     * Disables the wallet button, preventing clicks and applying a visual disabled state.
+     * When disabled, the button appears grayed out (`opacity: 0.5`) and does not
+     * respond to user interaction (`pointer-events: none`). For accessibility, the
+     * `aria-disabled="true"` attribute is also set on the container.
+     *
+     * Programmatic clicks (e.g. invoked by the wallet provider's SDK) are blocked
+     * by an explicit guard inside the click handler — the button's wallet service
+     * checks the disabled state before processing.
+     *
+     * Idempotent — calling on an already-disabled button has no effect.
+     * Safe to call before `load()` (no-throw); the styles are applied once the
+     * container element exists.
+     *
+     * @example
+     * button.disable();
+     */
+    disable(): void;
+    /**
+     * Applies the disabled / enabled visual state to the container element.
+     * Reads `this.isDisabled` and toggles the corresponding CSS + ARIA attributes.
+     *
+     * @private
+     */
+    protected applyDisabledStyles(): void;
     /**
      * Current method can change environment. By default environment = sandbox.
      * Also we can change domain alias for this environment. By default domain_alias = paydock.com
@@ -4628,13 +5055,53 @@ declare global {
         ApplePaySession: ApplePaySession;
     }
 }
+/** Styling configuration for the Apple Pay button. */
 interface ApplePayOpenWalletMetaStyles extends OpenWalletMetaStyles {
+    /** Variant displayed on the button (e.g. `'buy'`, `'donate'`, `'plain'`, `'check-out'`). */
     button_type?: ApplePayButtonType$1;
+    /** Color scheme: `'black'`, `'white'`, or `'white-outline'`. */
     button_style?: ApplePayButtonStyle$1;
 }
-interface ApplePayOpenWalletMeta extends OpenWalletMeta, ApplePayPaymentRequest {
+/**
+ * Fields that the SDK auto-populates in `adaptMeta()` if not provided by the merchant.
+ * Declared here so we can override them as optional in `ApplePayOpenWalletMeta` while
+ * keeping the strict `ApplePayPaymentRequest` intact for internal consumers.
+ */
+type ApplePayAutoFilledFields = 'merchant_capabilities' | 'supported_networks' | 'country_code' | 'currency_code' | 'total';
+/**
+ * Metadata required to configure an Apple Pay Open Wallet button.
+ * Extends {@link OpenWalletMeta} (amount, currency, country) plus most of the
+ * fields from Apple's `ApplePayPaymentRequest`. Fields that the SDK auto-populates
+ * in `adaptMeta()` are redeclared as optional below.
+ */
+interface ApplePayOpenWalletMeta extends OpenWalletMeta, Omit<ApplePayPaymentRequest, ApplePayAutoFilledFields> {
+    /** Label shown next to the total in the Apple Pay sheet (e.g. `'TOTAL'`, `'Order total'`). */
     amount_label: string;
+    /** Merchant's store name displayed during payment authorization. */
     store_name: string;
+    /**
+     * Auto-populated from `country.toUpperCase()` if not provided.
+     * Only set explicitly when you need a different country code than `country`.
+     */
+    country_code?: string;
+    /**
+     * Auto-populated from `currency.toUpperCase()` if not provided.
+     * Only set explicitly when you need a different currency code than `currency`.
+     */
+    currency_code?: string;
+    /**
+     * Auto-populated from `amount` and `amount_label` if not provided.
+     * Set explicitly to customize the total line item (e.g. with a specific `type`).
+     */
+    total?: ApplePayLineItem;
+    /**
+     * Defaults to `['supports3DS', 'supportsCredit', 'supportsDebit']` if not provided.
+     */
+    merchant_capabilities?: ApplePayMerchantCapability[];
+    /**
+     * Defaults to `['visa', 'masterCard', 'amex', 'discover']` if not provided.
+     */
+    supported_networks?: string[];
     /** Whether shipping address collection is required. */
     request_shipping?: boolean;
     /**
@@ -4643,8 +5110,14 @@ interface ApplePayOpenWalletMeta extends OpenWalletMeta, ApplePayPaymentRequest
      * Requires `request_shipping` to be `true`.
      */
     shipping_options?: IApplePayShippingOption$1[];
+    /** Whether to surface billing address fields in the sheet. When `true` and `required_billing_contact_fields` is unset, the SDK defaults the latter to `['name', 'postalAddress']`. */
     show_billing_address?: boolean;
+    /** Visual styling for the Apple Pay button. */
     style?: ApplePayOpenWalletMetaStyles;
+    /**
+     * Device capabilities allowed for the wallet button to be considered available.
+     * Used as a relaxation knob for testing — defaults to `['paymentCredentialsAvailable']` only.
+     */
     apple_pay_capabilities?: Array<'credentials_available' | 'credentials_status_unknown' | 'credentials_unavailable'>;
 }
 
@@ -4722,15 +5195,27 @@ type GooglePayButtonType = 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'p
 type GooglePayAuthMethod = 'PAN_ONLY' | 'CRYPTOGRAM_3DS';
 type GooglePayCardNetwork = 'AMEX' | 'DISCOVER' | 'ELECTRON' | 'ELO' | 'ELO_DEBIT' | 'INTERAC' | 'JCB' | 'MAESTRO' | 'MASTERCARD' | 'VISA';
 type BillingAddressFormat = 'MIN' | 'FULL';
+/**
+ * Styling configuration for the Google Pay button.
+ */
 interface GooglePayOpenWalletMetaStyles extends OpenWalletMetaStyles {
+    /** Variant displayed on the button (e.g. `'pay'`, `'buy'`, `'checkout'`). */
     button_type?: GooglePayButtonType;
+    /** Sizing strategy: `'static'` keeps the intrinsic size; `'fill'` stretches to the container. */
     button_size_mode?: GooglePayButtonSizeMode;
+    /** Color scheme: `'default'`, `'black'`, or `'white'`. */
     button_color?: GooglePayButtonColor;
 }
+/**
+ * Metadata required to configure a Google Pay Open Wallet button.
+ * Extends {@link OpenWalletMeta} (amount, currency, country) with Google Pay specifics.
+ */
 interface GooglePayOpenWalletMeta extends OpenWalletMeta {
+    /** Display name shown in the Google Pay sheet (e.g. `'Demo Store'`). */
     merchant_name?: string;
     /** Whether shipping address collection is required. */
     request_shipping?: boolean;
+    /** Whether to surface billing address fields in the sheet. */
     show_billing_address?: boolean;
     /**
      * Available shipping options to display in the payment sheet.
@@ -4738,38 +5223,72 @@ interface GooglePayOpenWalletMeta extends OpenWalletMeta {
      * Requires `request_shipping` to be `true`.
      */
     shipping_options?: IGooglePayShippingOption[];
+    /** Label shown next to the total amount in the sheet (e.g. `'TOTAL'`). */
     amount_label?: string;
+    /** Visual styling for the button. */
     style?: GooglePayOpenWalletMetaStyles;
+    /** Override the default card configuration (auth methods, allowed networks, tokenization). */
     card_config?: GooglePayCardConfig;
 }
+/**
+ * Card configuration passed to Google Pay's `PaymentDataRequest`.
+ * Mirrors Google Pay's
+ * [PaymentMethodSpecification](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethod)
+ * with snake_case keys.
+ */
 interface GooglePayCardConfig {
+    /** Payment method type Google Pay should display. `'CARD'` for card payments, `'PAYPAL'` for PayPal-via-Google Pay. */
     type: 'CARD' | 'PAYPAL';
+    /** Method-specific parameters that filter the cards Google Pay will offer. */
     parameters: {
+        /** Allowed authentication methods. `'PAN_ONLY'` for FPAN (server-side decryption); `'CRYPTOGRAM_3DS'` for DPAN (device tokens). */
         allowed_auth_methods: GooglePayAuthMethod[];
+        /** Card networks the merchant accepts. */
         allowed_card_networks: GooglePayCardNetwork[];
+        /** Whether prepaid cards are allowed. Defaults to Google Pay's default. */
         allow_prepaid_cards?: boolean;
+        /** Whether credit cards are allowed. Defaults to Google Pay's default. */
         allow_credit_cards?: boolean;
+        /** Request `assuranceDetails` in the payment response (gives risk-signal hints from Google). */
         assurance_details_required?: boolean;
+        /** Whether the billing address must be collected. */
         billing_address_required?: boolean;
+        /** Billing address collection options. Only honored when `billing_address_required` is `true`. */
         billing_address_parameters?: {
+            /** Format of the collected billing address: `'MIN'` (minimal) or `'FULL'`. */
             format: BillingAddressFormat;
+            /** Whether to also collect the phone number. */
             phone_number_required?: boolean;
         };
+        /** Per-network parameters such as acquirer routing hints. */
         card_network_parameters?: {
+            /** The card network this entry applies to. */
             card_network: GooglePayCardNetwork;
+            /** Acquirer BIN — used by the gateway to route the transaction. */
             acquirer_bin?: string;
+            /** Acquirer-assigned merchant identifier. */
             acquirer_merchant_id?: string;
         }[];
     };
+    /**
+     * How Google Pay should tokenize the payment method. Paydock typically configures this server-side
+     * and you should NOT pass it unless you fully understand the implications of overriding the default.
+     */
     tokenization_specification?: {
+        /** Standard payment-gateway tokenization. */
         type: 'PAYMENT_GATEWAY';
+        /** Gateway-specific tokenization parameters (e.g. `gateway`, `gatewayMerchantId`). */
         parameters: {
             [key: string]: string;
         };
     } | {
+        /** Direct integration where Google encrypts the payload with the merchant's public key. */
         type: 'DIRECT';
+        /** Direct-tokenization parameters required by Google's payload encryption. */
         parameters: {
+            /** Protocol version expected by the merchant (currently `'ECv2'`). */
             protocol_version: string;
+            /** Merchant's public key used to encrypt the payload. */
             public_key: string;
         };
     };
@@ -5382,48 +5901,102 @@ declare enum EventEnum {
     ON_WALLET_LOADED = "onWalletLoaded"
 }
 
+/**
+ * Payload of the `paymentSuccessful` event emitted by `WalletButtons`.
+ * Represents the final charge result returned by the backend.
+ *
+ * For tamper-resistant validation, do a server-to-server fetch using `id`
+ * — never trust this payload alone for fulfillment decisions.
+ */
 interface IWalletPaymentSuccessful {
+    /** Charge identifier returned by the backend. */
     id: string;
+    /** Final charge amount as a number. */
     amount: number;
+    /** ISO 4217 currency code of the charge. */
     currency: string;
+    /** Backend charge status (e.g. `'complete'`, `'pending'`). */
     status: string;
+    /** Payer's full name if collected by the wallet. */
     payer_name?: string;
+    /** Payer's email if collected by the wallet. */
     payer_email?: string;
+    /** Payer's phone number if collected by the wallet. */
     payer_phone?: string;
 }
+/**
+ * Payload of the `unavailable` event emitted by `WalletButtons`.
+ * Identifies which wallet became unavailable when more than one is configured.
+ */
 interface IWalletUnavailable {
+    /** The wallet type that is unavailable. Absent when the unavailability is generic. */
     wallet?: WALLET_TYPE;
 }
+/**
+ * Payload of the `onClick` event emitted by `WalletButtons`.
+ * Hand back a `Promise<void>` (defer the wallet sheet) or `Promise<boolean>` /
+ * `boolean` (return `false` to abort the flow) via `attachResult`.
+ */
 interface IWalletOnClick {
+    /** Attach the result of an async operation to control the wallet flow. Resolving with `false` aborts; `void`/`true` continues. */
     attachResult: (result: Promise<void> | boolean) => void;
 }
+/**
+ * Payload of the `update` event emitted by `WalletButtons` during the wallet flow
+ * (e.g. when the user authorizes the payment in the wallet sheet but before the
+ * server-side capture completes).
+ */
 interface IWalletUpdate {
+    /** Response code from the wallet provider (provider-specific). */
     wallet_response_code?: string;
+    /** Wallet provider's order identifier for this transaction. */
     wallet_order_id?: string;
+    /** Wallet provider's session identifier for this interaction. */
     wallet_session_id?: string;
+    /** Payment source details captured from the wallet. */
     payment_source?: {
+        /** Wallet's internal payment method identifier. */
         wallet_payment_method_id?: string;
+        /** Last 4 digits of the card. */
         card_number_last4?: string;
+        /** Card network/scheme (e.g. `'visa'`, `'mastercard'`). */
         card_scheme?: string;
     };
+    /** Loyalty account details if the wallet provider supports loyalty. */
     wallet_loyalty_account?: {
+        /** Loyalty account identifier. */
         id?: string;
+        /** Loyalty account barcode. */
         barcode?: string;
     };
+    /** Shipping address selected in the wallet sheet. */
     shipping?: {
+        /** Street address line 1. */
         address_line1?: string;
+        /** Street address line 2. */
         address_line2?: string;
+        /** Postal/ZIP code. */
         address_postcode?: string;
+        /** City. */
         address_city?: string;
+        /** State or administrative area. */
         address_state?: string;
+        /** ISO 3166 country code. */
         address_country?: string;
+        /** Company name on the address. */
         address_company?: string;
+        /** Post office box number. */
         post_office_box_number?: string;
+        /** Wallet provider's identifier for this saved address. */
         wallet_address_id?: string;
+        /** Display name for this saved address (e.g. `'Home'`). */
         wallet_address_name?: string;
+        /** ISO 8601 timestamp of when the address was saved. */
         wallet_address_created_timestamp?: string;
+        /** ISO 8601 timestamp of the last update to the address. */
         wallet_address_updated_timestamp?: string;
     };
+    /** The shipping option the user selected in the wallet sheet. */
     selected_shipping_option?: IShippingOption;
 }
 
@@ -5799,8 +6372,15 @@ declare enum EVENT {
     ON_SHIPPING_OPTIONS_CHANGE = "onShippingOptionsChange"
 }
 
+/**
+ * Base metadata required by every Wallet Buttons Express button.
+ * Concrete wallet metas (e.g. `ApplePayWalletMeta`, `PaypalWalletMeta`) extend
+ * this with wallet-specific configuration.
+ */
 interface BaseWalletMeta {
+    /** The payment amount as a number (e.g. `19.99`). */
     amount: number;
+    /** The ISO 4217 currency code (e.g. `'AUD'`, `'USD'`). */
     currency: string;
 }
 
@@ -6267,20 +6847,43 @@ interface IApplePayShippingOption {
     amount?: string;
 }
 
+/**
+ * Metadata required to configure an `ApplePayWalletButtonExpress` button.
+ * Extends {@link BaseWalletMeta} (`amount`, `currency`) plus Apple Pay specifics.
+ *
+ * The walletToken (JWT) returned from the `onClick` handler authorizes the actual
+ * charge; this meta only configures the button presentation and the Apple Pay sheet.
+ */
 interface ApplePayWalletMeta extends BaseWalletMeta {
+    /** Label shown next to the total in the Apple Pay sheet (e.g. `'TOTAL'`). */
     amount_label: string;
+    /** ISO 3166-1 alpha-2 country code (e.g. `'AU'`, `'US'`). Required by Apple Pay. */
     country: string;
+    /** Payment capabilities the merchant supports. Must include at least `'supports3DS'`. */
     merchant_capabilities?: Array<'supports3DS' | 'supportsEMV' | 'supportsCredit' | 'supportsDebit'>;
+    /** Card networks the merchant accepts. */
     supported_networks?: Array<'visa' | 'masterCard' | 'amex' | 'chinaUnionPay' | 'discover' | 'interac' | 'jcb' | 'privateLabel'>;
+    /** Billing contact fields the user must provide. Note: Apple does not currently return `'phone'` or `'email'`. */
     required_billing_contact_fields?: Array<'email' | 'name' | 'phone' | 'postalAddress'>;
+    /** Shipping contact fields the user must provide. Include `'postalAddress'` to surface the address fields in the sheet. */
     required_shipping_contact_fields?: Array<'email' | 'phone' | 'postalAddress'>;
+    /**
+     * Device capabilities allowed for the wallet button to be considered available.
+     * Used as a relaxation knob for testing — defaults to `['paymentCredentialsAvailable']` only.
+     */
     apple_pay_capabilities?: Array<'credentials_available' | 'credentials_status_unknown' | 'credentials_unavailable'>;
+    /** Restrict the cards Apple Pay offers to those issued in these ISO 3166 country codes. */
     supported_countries?: string[];
+    /** Visual styling for the Apple Pay button. */
     style?: {
+        /** Variant displayed on the button (e.g. `'buy'`, `'donate'`, `'plain'`). */
         button_type?: ApplePayButtonType;
+        /** Color scheme: `'black'`, `'white'`, or `'white-outline'`. */
         button_style?: ApplePayButtonStyle;
     };
+    /** Pre-filled shipping data to seed the Apple Pay sheet. */
     shipping?: AppleShippingType;
+    /** Whether the user can edit the shipping address: `'available'` allows editing; `'store_pickup'` locks it. */
     shipping_editing_mode?: ContactShippingEditingMode;
 }
 
@@ -6341,32 +6944,63 @@ declare class ApplePayWalletButtonExpress extends BaseWalletButton<ApplePayWalle
     private isUnsuportedBrowser;
 }
 
+/**
+ * Metadata required to configure a `PaypalWalletButtonExpress` button.
+ * Extends {@link BaseWalletMeta} (`amount`, `currency`) with PayPal-specific options.
+ *
+ * Most PayPal style options mirror the
+ * [PayPal Buttons Style Guide](https://developer.paypal.com/docs/multiparty/checkout/standard/customize/buttons-style-guide/).
+ */
 interface PaypalWalletMeta extends BaseWalletMeta {
+    /** Enable PayPal's Pay Later (Pay in 4) option. Defaults to `false`. */
     pay_later?: boolean;
+    /** Hide the Pay Later messaging copy under the button. Defaults to `false`. */
     hide_message?: boolean;
+    /** Render the standalone PayPal button instead of the smart button group. Defaults to `false`. */
     standalone?: boolean;
+    /** Capture the transaction immediately (`true`) or authorize for later capture (`false`). Defaults to `false`. */
     capture?: boolean;
+    /** Visual styling for the PayPal button. Mirrors PayPal's smart button style schema. */
     style?: {
+        /** Button layout orientation. */
         layout?: 'vertical' | 'horizontal';
+        /** Button color theme. */
         color?: 'gold' | 'blue' | 'silver' | 'black' | 'white';
+        /** Button shape. */
         shape?: 'rect' | 'pill' | 'sharp';
+        /** Custom border radius in pixels. Overrides `shape` corner roundness. */
         borderRadius?: number;
+        /** Button height in pixels. */
         height?: number;
+        /** When `true`, removes PayPal's default max-width constraint on the button. */
         disableMaxWidth?: boolean;
+        /** Label text displayed on the button. */
         label?: 'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment';
+        /** Whether to show the tagline beneath the button. */
         tagline?: boolean;
+        /** Pay Later messaging configuration shown alongside the button. */
         messages?: {
+            /** Layout type for the messaging block. */
             layout?: 'text' | 'flex';
+            /** PayPal logo configuration in the messaging block. */
             logo?: {
+                /** Logo variant. `'none'` removes the logo entirely. */
                 type?: 'primary' | 'alternative' | 'inline' | 'none';
+                /** Logo position relative to the message text. */
                 position?: 'left' | 'right' | 'top';
             };
+            /** Message text styling. */
             text?: {
+                /** Text color. */
                 color?: 'black' | 'white' | 'monochrome' | 'grayscale';
+                /** Font size in pixels (10-16). */
                 size?: 10 | 11 | 12 | 13 | 14 | 15 | 16;
+                /** Horizontal alignment. */
                 align?: 'left' | 'center' | 'right';
             };
+            /** Background color of the messaging block (used when `layout` is `'flex'`). */
             color?: 'blue' | 'black' | 'white' | 'white-no-border' | 'gray' | 'monochrome' | 'grayscale';
+            /** Aspect ratio of the messaging block. */
             ratio?: '1x1' | '1x4' | '8x1' | '20x1';
         };
     };
@@ -6597,7 +7231,8 @@ declare global {
             ExternalCheckoutBuilder: typeof Builder$1;
             ExternalCheckoutChecker: typeof Checker;
             PaymentSourceBuilder: typeof Builder;
-            Canvas3DS: typeof Canvas3ds;
+            Canvas3ds: typeof Canvas3ds;
+            Checkout: typeof Checkout;
             MultiWidget: typeof MultiWidget;
             HtmlMultiWidget: typeof HtmlMultiWidget;
             HtmlWidget: typeof HtmlWidget;
@@ -6608,5 +7243,5 @@ declare global {
     }
 }
 
-export { AfterpayCheckoutButton, AfterpayOnSiteMessaging, Api, ApplePayOpenWalletButton, ApplePayWalletButtonExpress, CHECKOUT_BUTTON_EVENT, Canvas3ds, Checkout, CheckoutActionCode, ClickToPay, Configuration, ContactShippingEditingMode, ELEMENT, ERROR_OPERATION, EVENT$2 as EVENT, Builder$1 as ExternalCheckoutBuilder, Checker as ExternalCheckoutChecker, FORM_FIELD, FRAUD_PREVENTION_EVENTS, FraudPreventionService, GooglePayOpenWalletButton, HtmlMultiWidget, HtmlPaymentSourceWidget, HtmlWidget, InstructionDebugger, MultiWidget, OpenWalletButtons, PAYMENT_TYPE, PURPOSE, PayPalDataCollector, PayPalSavePaymentSourceWidget, Builder as PaymentSourceBuilder, PaymentSourceWidget, PaypalCheckoutButton, PaypalWalletButtonExpress, STYLABLE_ELEMENT, STYLABLE_ELEMENT_STATE, STYLE, SUPPORTED_CARD_TYPES, TEXT, TOKEN_TYPE, TRIGGER, TYPE, VAULT_DISPLAY_STYLE, VaultDisplayWidget, EVENT as WALLET_BUTTONS_EXPRESS_EVENT, WALLET_TYPES, WalletButtons, ZipmoneyCheckoutButton };
-export type { ApplePayButtonStyle, ApplePayButtonType, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, IApplePayShippingOption, ICheckout, IClickToPayMeta, IDetails, IElementStyleInput, IEventAfterLoadData, IEventCheckoutFinishData, IEventData$1 as IEventData, IEventFinishData, IEventMetaData, IEventSizeData, IFormValidation, IOpenWalletProvider, IPayPalMeta, IStyles$1 as IStyles, ITexts, IWalletMeta, IWalletOnClickEvent, IWalletPaymentSuccessfulEvent, IWalletUnavailableEvent, IWalletUpdateData, IWalletUpdateEvent, OTTResponse, OnCancelEventData, OnClickEventData$1 as OnClickEventData, OnCreateOTTErrorEventData, OnCreateOTTErrorPayload, OnCreateOTTSuccessPayload, OnCreateOTTSuccessfulEventData, OnErrorEventData$1 as OnErrorEventData, OnErrorPayload, OnLoadedEventData, OnUnavailableDetails, OnUnavailableEventData$1 as OnUnavailableEventData, OnUnavailablePayload, OpenWalletBaseEvent, OpenWalletDataEvent, OpenWalletEventType, OpenWalletMeta, PaypalWalletMeta, Shipping, VaultDisplayStyle, OnClickEventData as WalletExpressOnClickEventData, OnCloseEventData as WalletExpressOnCloseEventData, OnErrorEventData as WalletExpressOnErrorEventData, OnPaymentErrorEventData as WalletExpressOnPaymentErrorEventData, OnPaymentInReviewEventData as WalletExpressOnPaymentInReviewEventData, OnPaymentSuccessfulEventData as WalletExpressOnPaymentSuccessfulEventData, OnShippingAddressChangeEventData as WalletExpressOnShippingAddressChangeEventData, OnShippingAddressChangeEventResponse as WalletExpressOnShippingAddressChangeEventResponse, OnShippingOptionChangeEventData as WalletExpressOnShippingOptionChangeEventData, OnShippingOptionChangeEventResponse as WalletExpressOnShippingOptionChangeEventResponse, OnUnavailableEventData as WalletExpressOnUnavailableEventData, WalletType, WidgetEventMap, WidgetEventName };
+export { AfterpayCheckoutButton, AfterpayOnSiteMessaging, Api, ApplePayOpenWalletButton, ApplePayWalletButtonExpress, CANVAS_3DS_EVENT, CHECKOUT_BUTTON_EVENT, EVENT$2 as CHECKOUT_EVENT, Canvas3ds, Canvas3dsTokenFormat, Checkout, CheckoutActionCode, ClickToPay, Configuration, ContactShippingEditingMode, ELEMENT, ERROR_OPERATION, EVENT$3 as EVENT, Builder$1 as ExternalCheckoutBuilder, Checker as ExternalCheckoutChecker, FORM_FIELD, FRAUD_PREVENTION_EVENTS, FraudPreventionService, GooglePayOpenWalletButton, HtmlMultiWidget, HtmlPaymentSourceWidget, HtmlWidget, InstructionDebugger, MultiWidget, OpenWalletButtons, PAYMENT_EXPIRED, PAYMENT_FAILURE, PAYMENT_SUCCESSFUL, PAYMENT_TYPE, PURPOSE, PayPalDataCollector, PayPalSavePaymentSourceWidget, Builder as PaymentSourceBuilder, PaymentSourceWidget, PaypalCheckoutButton, PaypalWalletButtonExpress, STYLABLE_ELEMENT, STYLABLE_ELEMENT_STATE, STYLE, SUPPORTED_CARD_TYPES, TEXT, TOKEN_TYPE, TRIGGER, TYPE, VAULT_DISPLAY_STYLE, VaultDisplayWidget, EVENT as WALLET_BUTTONS_EXPRESS_EVENT, WALLET_TYPES, WalletButtons, ZipmoneyCheckoutButton };
+export type { ApplePayButtonStyle, ApplePayButtonType, ApplePayOpenWalletMeta, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, Canvas3dsAuthPayload, Canvas3dsChargeAuthEventPayload, Canvas3dsErrorEventPayload, Canvas3dsErrorPayload, Canvas3dsEventMap, Canvas3dsEventName, CheckoutIntentTokenPayload, CheckoutPaymentExpiredPayload, CheckoutPaymentFailurePayload, CheckoutPaymentSuccessPayload, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, GooglePayCardConfig, GooglePayOpenWalletMeta, GooglePayOpenWalletMetaStyles, HandleResponseInterface, IApplePayShippingOption, ICheckout, IClickToPayMeta, IDetails, IElementStyleInput, IEventAfterLoadData, IEventCheckoutFinishData, IEventData$1 as IEventData, IEventError, IEventFinishData, IEventMetaData, IEventSizeData, IFormValidation, IOpenWalletProvider, IPayPalMeta, IStyles$1 as IStyles, ITexts, ITokenStandalone3DS, IWalletMeta, IWalletOnClickEvent, IWalletPaymentSuccessfulEvent, IWalletUnavailableEvent, IWalletUpdateData, IWalletUpdateEvent, OTTResponse, OnCancelEventData, OnClickEventData$1 as OnClickEventData, OnCreateOTTErrorEventData, OnCreateOTTErrorPayload, OnCreateOTTSuccessPayload, OnCreateOTTSuccessfulEventData, OnErrorEventData$1 as OnErrorEventData, OnErrorPayload, OnLoadedEventData, OnUnavailableDetails, OnUnavailableEventData$1 as OnUnavailableEventData, OnUnavailablePayload, OpenWalletBaseEvent, OpenWalletDataEvent, OpenWalletEventType, OpenWalletMeta, PaypalWalletMeta, ProcessAuthenticationResponse, Shipping, VaultDisplayStyle, OnClickEventData as WalletExpressOnClickEventData, OnCloseEventData as WalletExpressOnCloseEventData, OnErrorEventData as WalletExpressOnErrorEventData, OnPaymentErrorEventData as WalletExpressOnPaymentErrorEventData, OnPaymentInReviewEventData as WalletExpressOnPaymentInReviewEventData, OnPaymentSuccessfulEventData as WalletExpressOnPaymentSuccessfulEventData, OnShippingAddressChangeEventData as WalletExpressOnShippingAddressChangeEventData, OnShippingAddressChangeEventResponse as WalletExpressOnShippingAddressChangeEventResponse, OnShippingOptionChangeEventData as WalletExpressOnShippingOptionChangeEventData, OnShippingOptionChangeEventResponse as WalletExpressOnShippingOptionChangeEventResponse, OnUnavailableEventData as WalletExpressOnUnavailableEventData, WalletType, WidgetEventMap, WidgetEventName };