@paydock/client-sdk 1.147.0 → 1.148.0

package/bundles/index.cjs.d.ts

@@ -2316,298 +2316,6 @@ 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;
-    /**
-     * Origins allowed to deliver a processed 3DS outcome to the page via postMessage: the Paydock API
-     * (inline callback page) and the Paydock widget (remote-app landing page), for the current env/alias.
-     */
-    protected getTrustedMessageOrigins(api: ApiBase): string[];
-    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 of `chargeAuthChallengeLoaded` (Standalone 3DS, challenge flow only).
- * Emitted exactly once per challenge, after `chargeAuthChallenge`.
- */
-interface Canvas3dsChallengeLoadedPayload {
-    /** The Paydock 3DS charge identifier the challenge belongs to. */
-    charge_3ds_id: string;
-    /**
-     * `'load'` — the challenge iframe fired its first `load`: the ACS page has painted.
-     * `'timeout'` — no `load` arrived within the SDK's 2.5 s safety fallback; the event is emitted anyway so a
-     * loader is never held forever (the page may still be loading and will paint on its own). Useful for
-     * analytics (how often the fallback fires) — you do not need to handle the two differently.
-     */
-    reason: 'load' | 'timeout';
-}
-/**
- * Payload of `chargeAuthChallengeCompleted` (Standalone 3DS, challenge and decoupled flows).
- * Emitted at most once per authentication, after the shopper finished the challenge (or approved a decoupled
- * authentication) and always before the terminal event.
- */
-interface Canvas3dsChallengeCompletedPayload {
-    /** The Paydock 3DS charge identifier the authentication belongs to. */
-    charge_3ds_id: string;
-    /**
-     * How the SDK learned that the issuer delivered the result:
-     * `'poll'` — the 3DS Server's result monitor reported it (the usual case: it flips as soon as the issuer's
-     * result reaches the 3DS Server, before the challenge iframe has even left the bank's page);
-     * `'callback'` — the callback message carrying the outcome arrived first (the terminal event follows
-     * immediately). Informational only — handle both the same way.
-     */
-    source: 'poll' | 'callback';
-}
-/**
- * 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;
-    /**
-     * The challenge iframe has painted (first `load`), or the 2.5 s fallback elapsed — see `reason`. Standalone-only,
-     * challenge flow only (never emitted for decoupled challenges). Fires once, after `chargeAuthChallenge`.
-     *
-     * Recommended loader pattern: show a loader before the charge POST, keep it through `chargeAuthChallenge`,
-     * reveal the challenge on this event, cover it with "Completing verification" on `chargeAuthChallengeCompleted`,
-     * and finish on `chargeAuthSuccess` / `chargeAuthReject` / `error`.
-     */
-    chargeAuthChallengeLoaded: Canvas3dsChallengeLoadedPayload;
-    /**
-     * The shopper finished the challenge (or approved a decoupled authentication): the issuer delivered the final
-     * result to the 3DS Server and the SDK is obtaining the outcome. Cover the challenge iframe with your own
-     * "Completing verification" state — whatever the bank or the 3DS Server render from here on is plumbing, not
-     * UX. Standalone-only. Fires at most once per authentication, always before `chargeAuthSuccess` /
-     * `chargeAuthReject` / `error`, and never after them. A wrong OTP or a further interactive step does NOT fire
-     * it (no result has been delivered yet), so no grace timer or reveal fallback is needed on your side.
-     */
-    chargeAuthChallengeCompleted: Canvas3dsChallengeCompletedPayload;
-    /** 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
- * @enum TOKEN_FORMAT
- *
- * @type {object}
- * @param {string} HTML=html
- */
-declare enum TOKEN_FORMAT {
-    HTML = "html",
-    URL = "url",
-    STANDALONE_3DS = "standalone_3ds"
-}
-/**
- * List of available event's name
- * @const EVENT
- *
- * @type {object}
- * @param {string} CHARGE_AUTH_SUCCESS=chargeAuthSuccess
- * @param {string} CHARGE_AUTH_REJECT=chargeAuthReject
- * @param {string} ADDITIONAL_DATA_SUCCESS=additionalDataCollectSuccess
- * @param {string} ADDITIONAL_DATA_REJECT=additionalDataCollectReject
- * @param {string} CHARGE_AUTH=chargeAuth
- */
-/**
- * List of available event's name for Standalone 3ds flow
- * @const STANDALONE_3DS_EVENT
- *
- * @type {object}
- * @param {string} AUTH_SUCCESS=chargeAuthSuccess
- * @param {string} AUTH_ERROR=chargeAuthReject
- * @param {string} DECOUPLED=chargeAuthDecoupled
- * @param {string} CHALLENGE=chargeAuthChallenge
- * @param {string} CHALLENGE_LOADED=chargeAuthChallengeLoaded - challenge iframe painted (first `load`, or 2.5 s fallback); reveal your challenge UI here
- * @param {string} CHALLENGE_COMPLETED=chargeAuthChallengeCompleted - the shopper finished the challenge (issuer result delivered to the 3DS Server); cover the challenge iframe with your own loader until the terminal event
- * @param {string} INFO=chargeAuthInfo
- * @param {string} ERROR=error
- */
-/**
- * Class Canvas3ds include method for working on html
- * @constructor
- *
- * @param {string} selector - Selector of html element. Container for widget
- * @param {string} token - Pre authorized token
- * @example
- * var widget = new Canvas3ds('#widget', 'token');
- *
- *
- */
-declare class Canvas3ds {
-    protected link: Link;
-    protected configs: Configuration[];
-    protected publicKey: string;
-    protected token: {
-        content: string;
-        format: TOKEN_FORMAT;
-        charge_3ds_id: string;
-    };
-    protected standalone3dsService: Standalone3dsService;
-    protected container: Container;
-    protected iFrame: IFrame;
-    protected event: IFrameEvent;
-    protected eventEmitter: EventEmitter;
-    /** @constructs */ constructor(selector: string, token: string);
-    protected static extractToken(token: string): {
-        content: string;
-        format: TOKEN_FORMAT;
-        charge_3ds_id: string;
-    };
-    /**
-     * The final method to beginning, the load process of widget to html
-     *
-     */
-    load(): 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
-     *
-     * @example
-     * widget.setEnv('production');
-     * @param {string} env - sandbox, production
-     * @param {string} [alias] - Own domain alias
-     */
-    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>;
-    /**
-     * Using this method you can hide widget after load
-     * @param {boolean} [saveSize=false] - using this param you can save iframe's size
-     */
-    hide(saveSize: boolean): void;
-    /**
-     * Using this method you can show widget after using hide method
-     *
-     */
-    show(): void;
-    /**
-     * Using this method you can reload widget
-     *
-     */
-    reload(): void;
-}
-
 /**
  * Canonical shared response shapes used by both Charge and Checkout internal APIs.
  * Extracted here to remove the prior duplicated definitions in
@@ -2660,353 +2368,821 @@ interface ProcessAuthenticationResponse {
         description?: string;
     };
 }
-
-declare class ApiChargeInternal {
-    protected api: ApiInternal;
-    constructor(api: ApiInternal);
-    walletCapture(payload: WalletCaptureBody): Promise<WalletCaptureResponse>;
-    walletCallback(payload: WalletCallbackBody): Promise<WalletCallbackResponse>;
-    standalone3dsHandle(): Promise<HandleResponseInterface>;
+
+declare class ApiChargeInternal {
+    protected api: ApiInternal;
+    constructor(api: ApiInternal);
+    walletCapture(payload: WalletCaptureBody): Promise<WalletCaptureResponse>;
+    walletCallback(payload: WalletCallbackBody): Promise<WalletCallbackResponse>;
+    /** Two-step mode: runs the deferred Standalone 3DS authentication (AReq). Charge-token auth, like `standalone3dsHandle`. */
+    standalone3dsProcess(payload: Standalone3dsProcessBody): Promise<ProcessAuthenticationResponse>;
+    standalone3dsHandle(): Promise<HandleResponseInterface>;
+}
+interface WalletCaptureResponse {
+    id: string;
+    amount: number;
+    currency: string;
+    status: string;
+}
+interface WalletCaptureBody {
+    payment_method_id?: string;
+    customer?: {
+        payment_source?: {
+            type?: string;
+            card_name?: string;
+            card_scheme?: string;
+            card_number_last4?: string;
+            expire_month?: number;
+            expire_year?: number;
+            address_line1?: string;
+            address_line2?: string;
+            address_city?: string;
+            address_postcode?: string;
+            address_state?: string;
+            address_country?: string;
+            external_payer_id?: string;
+            ref_token?: string;
+            wallet_express?: boolean;
+        };
+    };
+}
+interface WalletCallbackBody {
+    request_type: string;
+}
+interface Standalone3dsProcessBody {
+    charge_3ds_id: string;
+}
+interface WalletCallbackResponse {
+    id: string;
+    status: string;
+    callback_method: string;
+    callback_rel: string;
+    callback_url: 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 {
+    protected api: ApiInternal;
+    constructor(api: ApiInternal);
+    getWalletConfig(gateway_id: string): Promise<GetWalletConfigResponse>;
+}
+interface GetWalletConfigResponse {
+    type: string;
+    mode: string;
+    credentials?: object;
+}
+
+declare class ApiServiceInternal {
+    protected api: ApiInternal;
+    constructor(api: ApiInternal);
+    getConfig(service_id: string): Promise<GetConfigResponse>;
+}
+interface GetConfigResponse {
+    type: SERVICE_TYPES;
+    merchant: string;
+    username: string;
+    password: string;
+    certificate: string;
+    certificate_passphrase: string;
+}
+declare enum SERVICE_TYPES {
+    ACCERTIFY = "Accertify",
+    BOOKING = "Booking",
+    GPAYMENTS = "GPayments",
+    CLICK_TO_PAY = "ClickToPay",
+    MASTERCARD_NT = "MastercardSCOF",
+    VISA_NT = "VisaVTS",
+    FORTER = "Forter",
+    APPLE_PAY = "ApplePay",
+    GOOGLE_PAY = "GooglePay"
+}
+
+declare enum PAYLOAD_FORMAT {
+    ENCRYPTED_STRING = "encrypted_string"
+}
+
+declare enum SERVICE_GROUP {
+    CLICK_TO_PAY = "click_to_pay",
+    WALLET = "wallet"
+}
+
+/**
+ * Token types returned in the OTT (One-Time Token) creation response.
+ */
+declare enum TOKEN_TYPE {
+    /** FPAN - Funding Primary Account Number (Google Pay only). */
+    CARD = "card",
+    /** DPAN - Device Primary Account Number (Apple Pay & Google Pay). */
+    CARD_SCHEME_TOKEN = "card_scheme_token"
+}
+
+type WalletType = WALLET_TYPES;
+declare enum WALLET_TYPES {
+    APPLE_PAY = "apple",
+    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;
 }
-interface WalletCaptureResponse {
-    id: 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;
-    currency: string;
-    status: string;
+    /** 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;
 }
-interface WalletCaptureBody {
-    payment_method_id?: string;
-    customer?: {
-        payment_source?: {
-            type?: string;
-            card_name?: string;
-            card_scheme?: string;
-            card_number_last4?: string;
-            expire_month?: number;
-            expire_year?: number;
-            address_line1?: string;
-            address_line2?: string;
-            address_city?: string;
-            address_postcode?: string;
-            address_state?: string;
-            address_country?: string;
-            external_payer_id?: string;
-            ref_token?: string;
-            wallet_express?: boolean;
-        };
-    };
+/**
+ * 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;
 }
-interface WalletCallbackBody {
-    request_type: string;
+/**
+ * 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;
 }
-interface WalletCallbackResponse {
+/**
+ * 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;
 }
-
-declare class ApiCheckoutInternal {
-    protected api: ApiInternal;
-    constructor(api: ApiInternal);
-    instructions(): Observable<object>;
-    private getInstructionLink;
-    callback(payload: Object): Promise<Object>;
-    status(id: string): Promise<Object>;
+/**
+ * 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;
+    };
 }
 
-declare class ApiGatewayInternal {
+declare class ApiPaymentSourceInternal {
     protected api: ApiInternal;
     constructor(api: ApiInternal);
-    getWalletConfig(gateway_id: string): Promise<GetWalletConfigResponse>;
+    createOTT(payload: CreateOTTRequest): Promise<CreateOTTResponse>;
+    createSession(payload: CreateSessionRequest): Promise<CreateSessionResponse>;
 }
-interface GetWalletConfigResponse {
-    type: string;
-    mode: string;
-    credentials?: object;
+
+declare class ApiInternal extends ApiBase {
+    charge(): ApiChargeInternal;
+    service(): ApiServiceInternal;
+    checkout(): ApiCheckoutInternal;
+    gateway(): ApiGatewayInternal;
+    paymentSource(): ApiPaymentSourceInternal;
 }
 
-declare class ApiServiceInternal {
+/**
+ * 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";
+    /**
+     * Two-step mode only: fingerprint done, SDK waiting for `Canvas3ds.authenticate()`. Emitted once, before any
+     * outcome event (`INFO` may precede it); never for a one-step charge. Payload: `Canvas3dsReadyPayload`.
+     */
+    readonly READY: "chargeAuthReady";
+    /**
+     * The challenge iframe fired its FIRST `load` after `chargeAuthChallenge` (the ACS page has painted),
+     * or the `CHALLENGE_LOADED_FALLBACK_MS` safety fallback elapsed without one. Emitted exactly once per
+     * challenge; never emitted for a decoupled challenge (no challenge iframe). Payload: `Canvas3dsChallengeLoadedPayload`.
+     */
+    readonly CHALLENGE_LOADED: "chargeAuthChallengeLoaded";
+    /**
+     * The issuer delivered the final authentication result to the 3DS Server (the shopper finished the
+     * challenge, or approved a decoupled authentication) and the SDK is now obtaining the outcome. Emitted at
+     * most once per authentication, always before the terminal event. Detected through the `secondary_url`
+     * result monitor (`source: 'poll'`) or, when the callback message arrives first, right before the outcome
+     * it carries (`source: 'callback'`). Payload: `Canvas3dsChallengeCompletedPayload`.
+     */
+    readonly CHALLENGE_COMPLETED: "chargeAuthChallengeCompleted";
+    /** 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";
+};
+declare class GPaymentsService {
+    protected container: Container;
     protected api: ApiInternal;
-    constructor(api: ApiInternal);
-    getConfig(service_id: string): Promise<GetConfigResponse>;
-}
-interface GetConfigResponse {
-    type: SERVICE_TYPES;
-    merchant: string;
-    username: string;
-    password: string;
-    certificate: string;
-    certificate_passphrase: string;
-}
-declare enum SERVICE_TYPES {
-    ACCERTIFY = "Accertify",
-    BOOKING = "Booking",
-    GPAYMENTS = "GPayments",
-    CLICK_TO_PAY = "ClickToPay",
-    MASTERCARD_NT = "MastercardSCOF",
-    VISA_NT = "VisaVTS",
-    FORTER = "Forter",
-    APPLE_PAY = "ApplePay",
-    GOOGLE_PAY = "GooglePay"
+    protected eventEmitter: EventEmitter;
+    /** Origins allowed to deliver a processed outcome (`process_status`) via postMessage. */
+    protected trustedOrigins: string[];
+    protected browserAndChallengeContainer: Container;
+    protected iFrameAuthorization: IFrame;
+    protected monitoringContainer: Container;
+    protected iFrameSecondaryUrl?: IFrame;
+    protected iFrameEvent: IFrameEvent;
+    protected resultRead: boolean;
+    /** `chargeAuthChallengeLoaded` already emitted for the current challenge (by `load` or by the fallback). */
+    protected challengeLoadedEmitted: boolean;
+    /** `chargeAuthChallengeCompleted` already emitted for the current authentication (poll or callback). */
+    protected challengeCompletedEmitted: boolean;
+    /** Set once a terminal event was emitted: no lifecycle event may follow (reset when a new challenge starts). */
+    protected challengeLifecycleClosed: boolean;
+    protected challengeLoadedTimer: ReturnType<typeof setTimeout> | null;
+    protected resultPollTimer: ReturnType<typeof setTimeout> | null;
+    /** One-shot guard for the `chargeAuth` leg — the callback message may be delivered more than once. */
+    protected authHandled: boolean;
+    /** Two-step mode: `charge_3ds_id` of the deferred callback message; `null` until it arrives (always for one-step). */
+    protected deferredCharge3dsId: string | null;
+    /** `authenticate()` latch; consumed when the deferred message arrives, reset only after a `/process` transport failure. */
+    protected authenticateRequested: boolean;
+    /** One `/process` call per widget instance (a transport failure allows one more `authenticate()`). */
+    protected authenticationStarted: boolean;
+    /** The single `/process` retry after a transport failure has been granted; the next failure is final. */
+    protected authenticationRetryUsed: boolean;
+    constructor(container: Container, api: ApiInternal, eventEmitter: EventEmitter, 
+    /** Origins allowed to deliver a processed outcome (`process_status`) via postMessage. */
+    trustedOrigins?: string[]);
+    load({ initialization_url, secondary_url, charge_3ds_id }: ITokenStandalone3DS, title: string): void;
+    private initializeIFrames;
+    private hideIframes;
+    private setupIFrameEvents;
+    /**
+     * Two-step mode: run the deferred authentication (`POST /standalone-3ds/process`). Never throws: runs now if
+     * the deferred message already arrived, otherwise as soon as it does; a no-op on one-step charges, repeated
+     * calls or after a terminal outcome. The outcome flows through the usual events.
+     */
+    authenticate(): void;
+    /**
+     * Calls `/process` once per instance (reachable from both the deferred message and `authenticate()`). The
+     * response has the callback-outcome shape, so the challenge / decoupled / result legs are shared with
+     * one-step. A rejection surfaces as `error`, with the same error object shape as the one-step callback
+     * (`toOutcomeError`). An API answer (stale session, rejected authentication…) is terminal. The first transport
+     * failure is not: the AReq may have run with its response lost, so the latches are reset and the merchant may
+     * call `authenticate()` once more — `/process` is idempotent and replays the stored outcome. A failure of that
+     * retry, of any kind, is final.
+     */
+    private performAuthentication;
+    /**
+     * A message carries a processed outcome only when it has `process_status` AND comes from a trusted
+     * origin. Used by the result leg: an untrusted `process_status` is never acted upon — the SDK falls
+     * back to `GET /handle` (still needed for decoupled challenges / polling). The authentication leg
+     * ignores untrusted senders outright, before this check.
+     */
+    private hasChainedOutcome;
+    private isTrustedOrigin;
+    private removeIframes;
+    private clearChallengeLoadedTimer;
+    /**
+     * Challenge iframe lifecycle (`chargeAuthChallengeLoaded`).
+     *
+     * The challenge iframe is cross-origin, but its `load` event still fires when the ACS page finishes loading:
+     * the first one means the page painted (merchants can drop their loader). A fallback timer
+     * (`armChallengeLoadedFallback`) guarantees `chargeAuthChallengeLoaded` within `CHALLENGE_LOADED_FALLBACK_MS`
+     * even if no `load` ever fires; a late paint after that is simply ignored. Later `load`s are NOT a usable
+     * signal for "the shopper submitted": the post-submit hops are HTTP redirects and self-submitting pages whose
+     * loads abort, and the final callback page posts its message before its own `load` — so the post-submit
+     * moment is `chargeAuthChallengeCompleted`, driven by the `secondary_url` result monitor instead.
+     *
+     * Nothing is emitted once the flow reached a terminal outcome (`finishChallengeLifecycle`), and a
+     * decoupled challenge (no challenge iframe) never emits `chargeAuthChallengeLoaded`.
+     *
+     * Resets the per-challenge state and returns the `load` handler to attach to the challenge iframe.
+     */
+    private startChallengeLifecycle;
+    /**
+     * Arms the `chargeAuthChallengeLoaded` fallback — only when a challenge iframe actually exists (the
+     * container may be gone, or `IFrame.load` may have no-op'd on an already-present iframe).
+     */
+    private armChallengeLoadedFallback;
+    private emitChallengeLoaded;
+    /**
+     * `chargeAuthChallengeCompleted` — once per authentication, never after a terminal event. Idempotent so the
+     * poll and the callback message can both call it: the first transport to notice the issuer's result wins.
+     */
+    private emitChallengeCompleted;
+    /** Call before emitting any terminal event: no lifecycle event may follow it, and the result poll stops. */
+    private finishChallengeLifecycle;
+    private stopResultPolling;
+    private parseResultData;
+    private parseHandleResponse;
+    private parseError;
+    private processResult;
+    /** Final (post-challenge) outcome delivered by the API through the callback message. */
+    private handleResultOutcome;
+    private externalAPI;
+    /**
+     * Polls the GPayments result monitor (`secondary_url`) until `AuthResultReady`. It is the primary source of
+     * `chargeAuthChallengeCompleted` (the monitor flips as soon as the issuer's RReq reaches the 3DS Server) and
+     * the fallback transport for the outcome itself (`GET /handle`) when the callback message never arrives —
+     * the only transport for decoupled challenges. Stops once an outcome was obtained or the lifecycle closed.
+     * Transport failures are retried on the same cadence; an unparsable body or an unknown event is fatal.
+     */
+    private doPolling;
+    /**
+     * Branches on the authentication outcome — delivered by the API through the callback message
+     * (`process_status` → `status`) or, in two-step mode, returned by `/process` (same shape).
+     */
+    private handleAuthenticationOutcome;
 }
 
-declare enum PAYLOAD_FORMAT {
-    ENCRYPTED_STRING = "encrypted_string"
+/**
+ * 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 enum SERVICE_GROUP {
-    CLICK_TO_PAY = "click_to_pay",
-    WALLET = "wallet"
+declare class Standalone3dsService {
+    protected container: Container;
+    protected eventEmitter: EventEmitter;
+    protected env: string;
+    protected alias: string;
+    /** Provider flow created by `load()`; `undefined` before it. */
+    protected gpaymentsService?: GPaymentsService;
+    constructor(container: Container, eventEmitter: any);
+    load(token: string, options: {
+        title: string;
+    }): void;
+    /**
+     * Two-step mode: forwards `Canvas3ds.authenticate()` to the provider flow. Calling it before `load()` is an
+     * integration bug (nothing to authenticate yet): it emits `error` and is not remembered.
+     */
+    authenticate(token: string): void;
+    /** `charge_3ds_id` from the standalone 3DS charge token, `undefined` when it cannot be decoded. */
+    private static readCharge3dsId;
+    /**
+     * Origins allowed to deliver a processed 3DS outcome to the page via postMessage: the Paydock API
+     * (inline callback page) and the Paydock widget (remote-app landing page), for the current env/alias.
+     */
+    protected getTrustedMessageOrigins(api: ApiBase): string[];
+    setEnv(env: string, alias?: string): void;
 }
 
 /**
- * Token types returned in the OTT (One-Time Token) creation response.
+ * Payload emitted by the Standalone 3DS flow for auth-related events
+ * (chargeAuthSuccess, chargeAuthReject, chargeAuthChallenge, chargeAuthDecoupled).
  */
-declare enum TOKEN_TYPE {
-    /** FPAN - Funding Primary Account Number (Google Pay only). */
-    CARD = "card",
-    /** DPAN - Device Primary Account Number (Apple Pay & Google Pay). */
-    CARD_SCHEME_TOKEN = "card_scheme_token"
+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;
+    };
 }
-
-type WalletType = WALLET_TYPES;
-declare enum WALLET_TYPES {
-    APPLE_PAY = "apple",
-    GOOGLE_PAY = "google"
+/** Payload of `chargeAuthReady` (two-step Standalone 3DS only): fingerprint done, SDK waiting for `Canvas3ds.authenticate()`. */
+interface Canvas3dsReadyPayload {
+    /** Paydock 3DS charge id of the deferred authentication. */
+    charge_3ds_id: string;
 }
-
 /**
- * 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).
+ * Payload of `chargeAuthChallengeLoaded` (Standalone 3DS, challenge flow only).
+ * Emitted exactly once per challenge, after `chargeAuthChallenge`.
  */
-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;
+interface Canvas3dsChallengeLoadedPayload {
+    /** The Paydock 3DS charge identifier the challenge belongs to. */
+    charge_3ds_id: string;
+    /**
+     * `'load'` — the challenge iframe fired its first `load`: the ACS page has painted.
+     * `'timeout'` — no `load` arrived within the SDK's 2.5 s safety fallback; the event is emitted anyway so a
+     * loader is never held forever (the page may still be loading and will paint on its own). Useful for
+     * analytics (how often the fallback fires) — you do not need to handle the two differently.
+     */
+    reason: 'load' | 'timeout';
 }
 /**
- * Billing address captured from the wallet payment sheet, when requested via
- * `required_billing_contact_fields` (Apple Pay) or equivalent (Google Pay).
+ * Payload of `chargeAuthChallengeCompleted` (Standalone 3DS, challenge and decoupled flows).
+ * Emitted at most once per authentication, after the shopper finished the challenge (or approved a decoupled
+ * authentication) and always before the terminal event.
  */
-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;
+interface Canvas3dsChallengeCompletedPayload {
+    /** The Paydock 3DS charge identifier the authentication belongs to. */
+    charge_3ds_id: string;
+    /**
+     * How the SDK learned that the issuer delivered the result:
+     * `'poll'` — the 3DS Server's result monitor reported it (the usual case: it flips as soon as the issuer's
+     * result reaches the 3DS Server, before the challenge iframe has even left the bank's page);
+     * `'callback'` — the callback message carrying the outcome arrived first (the terminal event follows
+     * immediately). Informational only — handle both the same way.
+     */
+    source: 'poll' | 'callback';
 }
 /**
- * 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.
+ * Payload emitted by the Standalone 3DS flow for error events.
+ * `error` is intentionally `unknown` — upstream emitters do not guarantee a shape.
  */
-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;
+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;
 }
 /**
- * Internal payload the SDK sends to Paydock when creating a One-Time Token.
- * Exposed publicly so integrators can construct fixtures for testing.
+ * 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 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;
+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;
+    };
 }
 /**
- * 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;
+ * 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;
+    /**
+     * Two-step mode only (`_3ds.authentication_flow: 'two_step'`): the background fingerprint is done and the SDK waits for
+     * `Canvas3ds.authenticate()`. Standalone-only; fires once, after `load()` and before any outcome event
+     * (`chargeAuthInfo` may precede it); never fires for a one-step charge, nor for inbuilt 3DS (`html` / `url`)
+     * tokens (no event at all for those).
+     *
+     * Pattern: `load()` in a hidden container when the review page opens, `authenticate()` on Pay (a call before
+     * `chargeAuthReady` is remembered; one before `load()` emits `error`), reveal the container only on `chargeAuthChallenge`, finish on the outcome events.
+     */
+    chargeAuthReady: Canvas3dsReadyPayload;
+    /**
+     * The challenge iframe has painted (first `load`), or the 2.5 s fallback elapsed — see `reason`. Standalone-only,
+     * challenge flow only (never emitted for decoupled challenges). Fires once, after `chargeAuthChallenge`.
+     *
+     * Recommended loader pattern: show a loader before the charge POST, keep it through `chargeAuthChallenge`,
+     * reveal the challenge on this event, cover it with "Completing verification" on `chargeAuthChallengeCompleted`,
+     * and finish on `chargeAuthSuccess` / `chargeAuthReject` / `error`.
+     */
+    chargeAuthChallengeLoaded: Canvas3dsChallengeLoadedPayload;
+    /**
+     * The shopper finished the challenge (or approved a decoupled authentication): the issuer delivered the final
+     * result to the 3DS Server and the SDK is obtaining the outcome. Cover the challenge iframe with your own
+     * "Completing verification" state — whatever the bank or the 3DS Server render from here on is plumbing, not
+     * UX. Standalone-only. Fires at most once per authentication, always before `chargeAuthSuccess` /
+     * `chargeAuthReject` / `error`, and never after them. A wrong OTP or a further interactive step does NOT fire
+     * it (no result has been delivered yet), so no grace timer or reveal fallback is needed on your side.
+     */
+    chargeAuthChallengeCompleted: Canvas3dsChallengeCompletedPayload;
+    /** 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;
 /**
- * Request body sent when initiating a wallet session against Paydock
- * (used by the Apple Pay merchant validation flow).
+ * 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.
  */
-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;
-}
+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];
+
 /**
- * Response returned by Paydock after creating a wallet session.
- * Used internally by the SDK to drive merchant validation; rarely consumed directly.
+ * List of available token's content formats
+ * @enum TOKEN_FORMAT
+ *
+ * @type {object}
+ * @param {string} HTML=html
  */
-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;
+declare enum TOKEN_FORMAT {
+    HTML = "html",
+    URL = "url",
+    STANDALONE_3DS = "standalone_3ds"
 }
 /**
- * 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.
+ * List of available event's name
+ * @const EVENT
+ *
+ * @type {object}
+ * @param {string} CHARGE_AUTH_SUCCESS=chargeAuthSuccess
+ * @param {string} CHARGE_AUTH_REJECT=chargeAuthReject
+ * @param {string} ADDITIONAL_DATA_SUCCESS=additionalDataCollectSuccess
+ * @param {string} ADDITIONAL_DATA_REJECT=additionalDataCollectReject
+ * @param {string} CHARGE_AUTH=chargeAuth
  */
-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.
+ * List of available event's name for Standalone 3ds flow
+ * @const STANDALONE_3DS_EVENT
+ *
+ * @type {object}
+ * @param {string} AUTH_SUCCESS=chargeAuthSuccess
+ * @param {string} AUTH_ERROR=chargeAuthReject
+ * @param {string} DECOUPLED=chargeAuthDecoupled
+ * @param {string} CHALLENGE=chargeAuthChallenge
+ * @param {string} READY=chargeAuthReady - two-step mode only: fingerprint done, waiting for `authenticate()`
+ * @param {string} CHALLENGE_LOADED=chargeAuthChallengeLoaded - challenge iframe painted (first `load`, or 2.5 s fallback); reveal your challenge UI here
+ * @param {string} CHALLENGE_COMPLETED=chargeAuthChallengeCompleted - the shopper finished the challenge (issuer result delivered to the 3DS Server); cover the challenge iframe with your own loader until the terminal event
+ * @param {string} INFO=chargeAuthInfo
+ * @param {string} ERROR=error
  */
-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.
+ * Class Canvas3ds include method for working on html
+ * @constructor
+ *
+ * @param {string} selector - Selector of html element. Container for widget
+ * @param {string} token - Pre authorized token
+ * @example
+ * var widget = new Canvas3ds('#widget', 'token');
+ *
  *
- * 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;
+declare class Canvas3ds {
+    protected link: Link;
+    protected configs: Configuration[];
+    protected publicKey: string;
+    protected token: {
+        content: string;
+        format: TOKEN_FORMAT;
+        charge_3ds_id: string;
+    };
+    protected standalone3dsService: Standalone3dsService;
+    protected container: Container;
+    protected iFrame: IFrame;
+    protected event: IFrameEvent;
+    protected eventEmitter: EventEmitter;
+    /** @constructs */ constructor(selector: string, token: string);
+    protected static extractToken(token: string): {
+        content: string;
+        format: TOKEN_FORMAT;
+        charge_3ds_id: string;
     };
-}
-
-declare class ApiPaymentSourceInternal {
-    protected api: ApiInternal;
-    constructor(api: ApiInternal);
-    createOTT(payload: CreateOTTRequest): Promise<CreateOTTResponse>;
-    createSession(payload: CreateSessionRequest): Promise<CreateSessionResponse>;
-}
-
-declare class ApiInternal extends ApiBase {
-    charge(): ApiChargeInternal;
-    service(): ApiServiceInternal;
-    checkout(): ApiCheckoutInternal;
-    gateway(): ApiGatewayInternal;
-    paymentSource(): ApiPaymentSourceInternal;
-}
-
-/**
- * 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";
     /**
-     * The challenge iframe fired its FIRST `load` after `chargeAuthChallenge` (the ACS page has painted),
-     * or the `CHALLENGE_LOADED_FALLBACK_MS` safety fallback elapsed without one. Emitted exactly once per
-     * challenge; never emitted for a decoupled challenge (no challenge iframe). Payload: `Canvas3dsChallengeLoadedPayload`.
+     * The final method to beginning, the load process of widget to html
+     *
      */
-    readonly CHALLENGE_LOADED: "chargeAuthChallengeLoaded";
+    load(): void;
     /**
-     * The issuer delivered the final authentication result to the 3DS Server (the shopper finished the
-     * challenge, or approved a decoupled authentication) and the SDK is now obtaining the outcome. Emitted at
-     * most once per authentication, always before the terminal event. Detected through the `secondary_url`
-     * result monitor (`source: 'poll'`) or, when the callback message arrives first, right before the outcome
-     * it carries (`source: 'callback'`). Payload: `Canvas3dsChallengeCompletedPayload`.
+     * Current method can change environment. By default environment = sandbox.
+     * Also we can change domain alias for this environment. By default domain_alias = paydock.com
+     *
+     * @example
+     * widget.setEnv('production');
+     * @param {string} env - sandbox, production
+     * @param {string} [alias] - Own domain alias
      */
-    readonly CHALLENGE_COMPLETED: "chargeAuthChallengeCompleted";
-    /** 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";
-};
+    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>;
+    /**
+     * Two-step mode only (`_3ds.authentication_flow: 'two_step'`): runs the authentication the API deferred after the
+     * fingerprint. Call it when the shopper confirms (e.g. presses "Pay"); the outcome arrives through the
+     * usual events (`chargeAuthChallenge`, `chargeAuthSuccess`, `chargeAuthReject`, `error`).
+     *
+     * Never throws. After `chargeAuthReady` the authentication starts at once; before it, the call is
+     * remembered and runs as soon as the fingerprint completes. One-step charges, repeated calls and calls after
+     * a terminal outcome are no-ops. For inbuilt 3DS (`html` / `url`) tokens it is a silent no-op: no event is
+     * emitted at all, so do not wait for `error` there. Calling it before `load()` is an integration error: it emits `error` and
+     * is not remembered. If `/process` could not be reached (`error` with `error_code` `service_unreachable` /
+     * `aborted`), `authenticate()` may be called once more; any other `error`, and any failure of that retry,
+     * is final.
+     * No client-side deadline: a stale 3DS Server session surfaces as `error` / `chargeAuthReject`.
+     *
+     * @example
+     * const widget = new Canvas3ds('#widget', token); // charge created with _3ds.authentication_flow: 'two_step'
+     * widget.on('chargeAuthReady', () => payButton.disabled = false);
+     * widget.on('chargeAuthChallenge', () => showChallengeModal());
+     * widget.on('chargeAuthSuccess', (data) => completePayment(data.charge_3ds_id));
+     * widget.on('chargeAuthReject', () => showDeclined());
+     * widget.on('error', () => showError());
+     * widget.load(); // fingerprint runs while the shopper reviews the order
+     *
+     * payButton.addEventListener('click', () => widget.authenticate());
+     */
+    authenticate(): void;
+    /**
+     * Using this method you can hide widget after load
+     * @param {boolean} [saveSize=false] - using this param you can save iframe's size
+     */
+    hide(saveSize: boolean): void;
+    /**
+     * Using this method you can show widget after using hide method
+     *
+     */
+    show(): void;
+    /**
+     * Using this method you can reload widget
+     *
+     */
+    reload(): void;
+}
 
 /**
  * Payload emitted by `Checkout.onPaymentSuccessful`.
@@ -7557,4 +7733,4 @@ declare global {
 }
 
 export { AfterpayCheckoutButton, AfterpayOnSiteMessaging, Api, ApplePayOpenWalletButton, ApplePayWalletButtonExpress, CANVAS_3DS_EVENT, CARD_SCHEME, 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 { ApplePayAvailabilityOptions, ApplePayAvailabilityResult, ApplePayButtonStyle, ApplePayButtonType, ApplePayCapabilityToken, ApplePayCredentialStatus, ApplePayOpenWalletMeta, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, Canvas3dsAuthPayload, Canvas3dsChallengeCompletedPayload, Canvas3dsChallengeLoadedPayload, Canvas3dsChargeAuthEventPayload, Canvas3dsErrorEventPayload, Canvas3dsErrorPayload, Canvas3dsEventMap, Canvas3dsEventName, CheckoutIntentTokenPayload, CheckoutPaymentExpiredPayload, CheckoutPaymentFailurePayload, CheckoutPaymentSuccessPayload, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, GooglePayAvailabilityOptions, GooglePayAvailabilityResult, 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, OpenWalletAvailabilityOptions, OpenWalletAvailabilityResult, 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 };
+export type { ApplePayAvailabilityOptions, ApplePayAvailabilityResult, ApplePayButtonStyle, ApplePayButtonType, ApplePayCapabilityToken, ApplePayCredentialStatus, ApplePayOpenWalletMeta, ApplePayWalletMeta, AppleShippingType, BaseWalletMeta, Billing, Canvas3dsAuthPayload, Canvas3dsChallengeCompletedPayload, Canvas3dsChallengeLoadedPayload, Canvas3dsChargeAuthEventPayload, Canvas3dsErrorEventPayload, Canvas3dsErrorPayload, Canvas3dsEventMap, Canvas3dsEventName, Canvas3dsReadyPayload, CheckoutIntentTokenPayload, CheckoutPaymentExpiredPayload, CheckoutPaymentFailurePayload, CheckoutPaymentSuccessPayload, CheckoutResponse, CreateOTTData, CreateOTTRequest, CreateOTTResponse, CreateSessionRequest, CreateSessionResponse, EventTypes, FraudPreventionEvent, FraudPreventionEventType, FraudPreventionProvider, GooglePayAvailabilityOptions, GooglePayAvailabilityResult, 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, OpenWalletAvailabilityOptions, OpenWalletAvailabilityResult, 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 };