@tagadapay/plugin-sdk 3.1.12 → 3.1.24

package/dist/v2/standalone/payment-service.js

@@ -0,0 +1,928 @@
+/**
+ * PaymentService (Standalone / Vanilla JS)
+ *
+ * Complete standalone equivalent of the React SDK's payment system:
+ * - usePaymentQuery (orchestration)
+ * - usePaymentPolling (status polling)
+ * - usePaymentActionHandler (action routing)
+ * - usePaymentProcessors (card, APM, Apple Pay, Google Pay, saved instruments)
+ * - usePaymentInstruments (instrument creation)
+ * - useThreeds (3DS session + challenge)
+ * - useGenericPaymentReturn (generic redirect return)
+ * - useAirwallex3dsReturn (Airwallex-specific redirect return)
+ * - All action handlers: redirect, threeds_auth, processor_auth, error,
+ *   kesspay_auth, trustflow_auth, finix_radar, stripe_radar, airwallex radar,
+ *   mastercard_auth
+ *
+ * No React. No hooks. No DOM framework dependency.
+ */
+import { PaymentsResource, } from '../core/resources/payments';
+import { ThreedsResource } from '../core/resources/threeds';
+import { StoreConfigResource } from '../core/resources/storeConfig';
+import { getAssignedPaymentFlowId } from '../core/funnelClient';
+import { getBasisTheoryApiKey } from '../../react/config/payment';
+// =============================================================================
+// PAYMENT SERVICE
+// =============================================================================
+export class PaymentService {
+    constructor(config) {
+        this.callbacks = {};
+        // BasisTheory (lazy initialized)
+        this.basisTheory = null;
+        this.btInitPromise = null;
+        // BasisTheory 3DS (lazy initialized)
+        this.bt3dsClass = null;
+        this.bt3dsInitPromise = null;
+        // Store config (cached)
+        this.storeConfig = null;
+        this.storeConfigPromise = null;
+        // Polling state
+        this.pollTimer = null;
+        this.pollAttempts = 0;
+        this.isPollingActive = false;
+        // Redirect return guard
+        this.redirectReturnProcessed = false;
+        this.paymentsResource = new PaymentsResource(config.apiClient);
+        this.threedsResource = new ThreedsResource(config.apiClient);
+        this.storeConfigResource = new StoreConfigResource(config.apiClient);
+        this.storeId = config.storeId;
+    }
+    /** Expose paymentsResource for advanced consumers */
+    get payments() {
+        return this.paymentsResource;
+    }
+    // ==========================================================================
+    // LIFECYCLE
+    // ==========================================================================
+    setCallbacks(callbacks) {
+        this.callbacks = callbacks;
+    }
+    /** Pre-warm BasisTheory + store config (non-blocking). */
+    warmup() {
+        void this.initBasisTheory();
+        void this.initBt3ds();
+        if (this.storeId)
+            void this.fetchStoreConfig();
+    }
+    destroy() {
+        this.stopPolling();
+        this.basisTheory = null;
+        this.btInitPromise = null;
+        this.bt3dsClass = null;
+        this.bt3dsInitPromise = null;
+        this.storeConfig = null;
+        this.storeConfigPromise = null;
+    }
+    // ==========================================================================
+    // BASIS THEORY
+    // ==========================================================================
+    initBasisTheory() {
+        if (this.basisTheory)
+            return Promise.resolve(this.basisTheory);
+        if (this.btInitPromise)
+            return this.btInitPromise;
+        this.btInitPromise = (async () => {
+            try {
+                const apiKey = getBasisTheoryApiKey();
+                const { BasisTheory } = await import('@basis-theory/basis-theory-js');
+                const bt = await new BasisTheory().init(apiKey, { elements: false });
+                this.basisTheory = bt;
+                console.log('[PaymentService] BasisTheory initialized');
+                return this.basisTheory;
+            }
+            catch (error) {
+                console.error('[PaymentService] BasisTheory init failed:', error);
+                return null;
+            }
+        })();
+        return this.btInitPromise;
+    }
+    getBtApiKey() {
+        return getBasisTheoryApiKey();
+    }
+    /** Lazy-load @basis-theory/web-threeds (BasisTheory3ds class) */
+    initBt3ds() {
+        if (this.bt3dsClass)
+            return Promise.resolve(this.bt3dsClass);
+        if (this.bt3dsInitPromise)
+            return this.bt3dsInitPromise;
+        this.bt3dsInitPromise = (async () => {
+            try {
+                const { BasisTheory3ds } = await import('@basis-theory/web-threeds');
+                this.bt3dsClass = BasisTheory3ds;
+                console.log('[PaymentService] BasisTheory 3DS loaded');
+                return this.bt3dsClass;
+            }
+            catch (error) {
+                console.error('[PaymentService] BasisTheory 3DS load failed:', error);
+                return null;
+            }
+        })();
+        return this.bt3dsInitPromise;
+    }
+    // ==========================================================================
+    // STORE CONFIG
+    // ==========================================================================
+    fetchStoreConfig() {
+        if (this.storeConfig)
+            return Promise.resolve(this.storeConfig);
+        if (this.storeConfigPromise)
+            return this.storeConfigPromise;
+        if (!this.storeId)
+            return Promise.resolve(null);
+        this.storeConfigPromise = (async () => {
+            try {
+                this.storeConfig = await this.storeConfigResource.getStoreConfig(this.storeId);
+                return this.storeConfig;
+            }
+            catch {
+                return null;
+            }
+        })();
+        return this.storeConfigPromise;
+    }
+    // ==========================================================================
+    // POLLING
+    // ==========================================================================
+    stopPolling() {
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.isPollingActive = false;
+        this.pollAttempts = 0;
+    }
+    startPolling(paymentId, callbacks, maxAttempts = 20, interval = 1500) {
+        this.stopPolling();
+        this.isPollingActive = true;
+        this.pollAttempts = 0;
+        console.log('[PaymentService] Starting payment polling:', paymentId);
+        const check = async () => {
+            if (!this.isPollingActive)
+                return;
+            this.pollAttempts++;
+            try {
+                const payment = await this.paymentsResource.getPaymentStatus(paymentId);
+                console.log(`[PaymentService] Poll #${this.pollAttempts}: ${payment.status} / ${payment.subStatus}`);
+                if (!this.isPollingActive)
+                    return;
+                if (payment.status === 'succeeded' ||
+                    (payment.status === 'pending' && payment.subStatus === 'authorized')) {
+                    this.stopPolling();
+                    callbacks.onSuccess(payment);
+                    return;
+                }
+                if (payment.requireAction !== 'none' && payment.requireActionData && !payment.requireActionData.processed) {
+                    this.stopPolling();
+                    callbacks.onRequireAction?.(payment);
+                    return;
+                }
+                if (payment.status !== 'succeeded' && payment.status !== 'pending') {
+                    this.stopPolling();
+                    callbacks.onFailure(payment.status || 'Payment failed');
+                    return;
+                }
+                if (this.pollAttempts >= maxAttempts) {
+                    this.stopPolling();
+                    callbacks.onFailure('Payment verification timeout');
+                }
+            }
+            catch {
+                if (this.pollAttempts >= 3) {
+                    this.stopPolling();
+                    callbacks.onFailure('Payment verification failed due to network errors');
+                }
+            }
+        };
+        void check();
+        this.pollTimer = setInterval(() => void check(), interval);
+    }
+    // ==========================================================================
+    // COMMON: processPaymentDirect + result handling
+    // ==========================================================================
+    /**
+     * Internal: call processPaymentDirect and handle requireAction / polling.
+     * Shared by processCardPayment, processApplePayPayment, etc.
+     */
+    async processAndHandle(checkoutSessionId, paymentInstrumentId, threedsSessionId, extra) {
+        const paymentFlowId = getAssignedPaymentFlowId();
+        const response = await this.paymentsResource.processPaymentDirect(checkoutSessionId, paymentInstrumentId, threedsSessionId, {
+            initiatedBy: extra?.initiatedBy || 'customer',
+            source: extra?.source || 'checkout',
+            paymentFlowId,
+            processorId: extra?.processorId,
+            paymentMethod: extra?.paymentMethod,
+        });
+        console.log('[PaymentService] Payment response:', {
+            paymentId: response.payment?.id,
+            status: response.payment?.status,
+            requireAction: response.payment?.requireAction,
+        });
+        this.callbacks.onCurrentPaymentId?.(response.payment?.id || null);
+        if (response.payment.requireAction !== 'none') {
+            await this.handlePaymentAction(response.payment);
+            return { success: true, payment: response.payment, order: response.order, redirecting: true };
+        }
+        if (response.payment.status === 'succeeded') {
+            this.callbacks.onProcessing?.(false);
+            return { success: true, payment: response.payment, order: response.order };
+        }
+        return new Promise((resolve) => {
+            this.startPolling(response.payment.id, {
+                onSuccess: (payment) => {
+                    this.callbacks.onProcessing?.(false);
+                    resolve({ success: true, payment, order: response.order });
+                },
+                onFailure: (error) => {
+                    this.callbacks.onError?.(error);
+                    this.callbacks.onProcessing?.(false);
+                    resolve({ success: false, error });
+                },
+                onRequireAction: (payment) => {
+                    void this.handlePaymentAction(payment);
+                },
+            });
+        });
+    }
+    /**
+     * After radar / completePaymentAfterAction, handle the resumed payment.
+     */
+    async handleResumedPayment(resumedPayment) {
+        if (resumedPayment.status === 'declined' || resumedPayment.status === 'failed') {
+            const errorMsg = resumedPayment.error?.message
+                || resumedPayment.error?.processorMessage
+                || 'Payment declined';
+            this.callbacks.onError?.(errorMsg);
+            this.callbacks.onProcessing?.(false);
+            this.callbacks.onFailure?.(errorMsg);
+            return;
+        }
+        if (resumedPayment.status === 'succeeded') {
+            this.callbacks.onProcessing?.(false);
+            this.callbacks.onSuccess?.(resumedPayment);
+            return;
+        }
+        if (resumedPayment.requireAction !== 'none' && resumedPayment.requireActionData) {
+            await this.handlePaymentAction(resumedPayment);
+            return;
+        }
+        // Start polling for final status
+        this.startPolling(resumedPayment.id, {
+            onSuccess: (p) => {
+                this.callbacks.onProcessing?.(false);
+                this.callbacks.onSuccess?.(p);
+            },
+            onFailure: (e) => {
+                this.callbacks.onError?.(e);
+                this.callbacks.onProcessing?.(false);
+            },
+            onRequireAction: (p) => { void this.handlePaymentAction(p); },
+        });
+    }
+    // ==========================================================================
+    // PAYMENT ACTION HANDLER (mirrors usePaymentActionHandler)
+    // ==========================================================================
+    async handlePaymentAction(payment) {
+        if (payment.requireAction === 'none')
+            return;
+        if (payment.requireActionData?.processed)
+            return;
+        const actionData = payment.requireActionData;
+        if (!actionData)
+            return;
+        try {
+            await this.paymentsResource.markPaymentActionProcessed(payment.id);
+        }
+        catch { /* best-effort */ }
+        switch (actionData.type) {
+            case 'redirect':
+            case 'redirect_to_payment':
+            case 'processor_auth': {
+                const redirectUrl = actionData.metadata?.redirect?.redirectUrl || actionData.redirectUrl || actionData.url;
+                if (redirectUrl) {
+                    console.log('[PaymentService] Redirecting:', redirectUrl);
+                    window.location.href = redirectUrl;
+                }
+                else if (payment.status === 'succeeded') {
+                    this.callbacks.onProcessing?.(false);
+                    this.callbacks.onSuccess?.(payment);
+                }
+                break;
+            }
+            case 'threeds_auth': {
+                const session = actionData.metadata?.threedsSession;
+                if (session?.acsChallengeUrl) {
+                    console.log('[PaymentService] 3DS challenge redirect:', session.acsChallengeUrl);
+                    window.location.href = session.acsChallengeUrl;
+                }
+                break;
+            }
+            case 'error': {
+                const msg = actionData.message || 'Payment action failed';
+                this.callbacks.onError?.(msg);
+                this.callbacks.onProcessing?.(false);
+                break;
+            }
+            case 'kesspay_auth':
+                this.handleKessPayAuth(actionData);
+                break;
+            case 'trustflow_auth':
+                this.handleTrustFlowAuth(actionData);
+                break;
+            case 'finix_radar':
+                await this.handleFinixRadar(payment, actionData);
+                break;
+            case 'stripe_radar':
+                await this.handleStripeRadar(payment, actionData);
+                break;
+            case 'radar':
+                if (actionData.metadata?.provider === 'airwallex') {
+                    await this.handleAirwallexRadar(payment, actionData);
+                }
+                break;
+            case 'mastercard_auth':
+                await this.handleMasterCardAuth(payment, actionData);
+                break;
+            default: {
+                console.log('[PaymentService] Unhandled action, starting polling:', actionData.type);
+                this.startPolling(payment.id, {
+                    onSuccess: (p) => { this.callbacks.onProcessing?.(false); this.callbacks.onSuccess?.(p); },
+                    onFailure: (e) => { this.callbacks.onError?.(e); this.callbacks.onProcessing?.(false); },
+                    onRequireAction: (p) => { void this.handlePaymentAction(p); },
+                });
+                break;
+            }
+        }
+    }
+    // --------------------------------------------------------------------------
+    // KessPay Auth
+    // --------------------------------------------------------------------------
+    handleKessPayAuth(actionData) {
+        const threeDSData = actionData?.metadata?.threeds;
+        if (!threeDSData?.challengeHtml) {
+            this.callbacks.onError?.('Missing KessPay 3DS challenge HTML');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            this.callbacks.onProcessing?.(false);
+            const tempDoc = document.implementation.createHTMLDocument('KessPay 3DS');
+            tempDoc.body.innerHTML = threeDSData.challengeHtml;
+            const form = tempDoc.querySelector('form');
+            if (form) {
+                const redirectForm = document.createElement('form');
+                redirectForm.method = form.method || 'POST';
+                redirectForm.action = form.action || '';
+                redirectForm.style.display = 'none';
+                form.querySelectorAll('input').forEach(input => {
+                    const newInput = document.createElement('input');
+                    newInput.type = input.type;
+                    newInput.name = input.name;
+                    newInput.value = input.value;
+                    redirectForm.appendChild(newInput);
+                });
+                document.body.appendChild(redirectForm);
+                redirectForm.submit();
+            }
+            else {
+                document.open();
+                document.write(threeDSData.challengeHtml);
+                document.close();
+            }
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'KessPay 3DS failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // TrustFlow Auth
+    // --------------------------------------------------------------------------
+    handleTrustFlowAuth(actionData) {
+        const authData = actionData?.metadata?.trustflow;
+        if (!authData?.appId || !authData?.txnId || !authData?.hash) {
+            this.callbacks.onError?.('Missing Trust Flow 3DS data');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            this.callbacks.onProcessing?.(false);
+            const form = document.createElement('form');
+            form.method = 'POST';
+            form.action = authData.captureUrl;
+            form.style.display = 'none';
+            for (const [name, value] of [['APP_ID', authData.appId], ['TXN_ID', authData.txnId], ['HASH', authData.hash]]) {
+                const input = document.createElement('input');
+                input.type = 'hidden';
+                input.name = name;
+                input.value = value;
+                form.appendChild(input);
+            }
+            document.body.appendChild(form);
+            form.submit();
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'Trust Flow 3DS failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Finix Radar
+    // --------------------------------------------------------------------------
+    async handleFinixRadar(payment, actionData) {
+        const radarConfig = actionData.metadata?.radar;
+        if (!radarConfig) {
+            this.callbacks.onError?.('Finix radar config missing');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            await this.loadScript('https://js.finix.com/v/1/finix.js', () => typeof window.Finix?.Auth === 'function');
+            const sessionKey = await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => reject(new Error('Timeout waiting for Finix Auth')), 10000);
+                const FinixAuth = window.Finix.Auth(radarConfig.environment, radarConfig.merchantId, () => {
+                    clearTimeout(timeout);
+                    const key = FinixAuth.getSessionKey();
+                    key ? resolve(key) : reject(new Error('No Finix session key'));
+                });
+                const immediateKey = FinixAuth.getSessionKey();
+                if (immediateKey) {
+                    clearTimeout(timeout);
+                    resolve(immediateKey);
+                }
+            });
+            await this.paymentsResource.saveRadarSession({
+                orderId: radarConfig.orderId,
+                finixRadarSessionId: sessionKey,
+                finixRadarSessionData: {
+                    sessionKey,
+                    merchantId: radarConfig.merchantId,
+                    environment: radarConfig.environment,
+                    createdAt: new Date().toISOString(),
+                },
+            });
+            const resumed = await this.paymentsResource.completePaymentAfterAction(payment.id);
+            await this.handleResumedPayment(resumed);
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'Finix radar failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Stripe Radar
+    // --------------------------------------------------------------------------
+    async handleStripeRadar(payment, actionData) {
+        const radarConfig = actionData.metadata?.radar;
+        if (!radarConfig?.publishableKey) {
+            this.callbacks.onError?.('Stripe radar config missing');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            await this.loadScript('https://js.stripe.com/v3/', () => typeof window.Stripe === 'function');
+            const stripe = window.Stripe(radarConfig.publishableKey);
+            const result = await stripe.createRadarSession();
+            if (result.error)
+                throw new Error(result.error.message || 'Failed to create Radar session');
+            if (!result.radarSession)
+                throw new Error('No radar session returned from Stripe');
+            await this.paymentsResource.saveRadarSession({
+                orderId: radarConfig.orderId,
+                stripeRadarSessionId: result.radarSession.id,
+                stripeRadarSessionData: result.radarSession,
+            });
+            const resumed = await this.paymentsResource.completePaymentAfterAction(payment.id);
+            await this.handleResumedPayment(resumed);
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'Stripe radar failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Airwallex Radar
+    // --------------------------------------------------------------------------
+    async handleAirwallexRadar(payment, actionData) {
+        const isTest = actionData.metadata?.isTest || false;
+        const orderId = payment.order?.id;
+        const checkoutSessionId = payment.order?.checkoutSessionId;
+        if (!orderId || !checkoutSessionId) {
+            this.callbacks.onError?.('Missing order info for Airwallex radar');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            const sessionId = crypto.randomUUID();
+            const existingScript = document.getElementById('airwallex-fraud-api');
+            if (!existingScript) {
+                const baseUrl = isTest ? 'https://static-demo.airwallex.com' : 'https://static.airwallex.com';
+                const script = document.createElement('script');
+                script.type = 'text/javascript';
+                script.async = true;
+                script.id = 'airwallex-fraud-api';
+                script.setAttribute('data-order-session-id', sessionId);
+                script.src = `${baseUrl}/webapp/fraud/device-fingerprint/index.js`;
+                await new Promise((resolve, reject) => {
+                    script.onload = () => resolve();
+                    script.onerror = () => reject(new Error('Failed to load Airwallex fraud script'));
+                    document.body.appendChild(script);
+                });
+            }
+            else {
+                existingScript.setAttribute('data-order-session-id', sessionId);
+            }
+            await this.paymentsResource.saveRadarSession({
+                checkoutSessionId,
+                orderId,
+                airwallexRadarSessionId: sessionId,
+            });
+            const resumed = await this.paymentsResource.completePaymentAfterAction(payment.id);
+            await this.handleResumedPayment(resumed);
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'Airwallex radar failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // MasterCard Auth (3DS inline challenge)
+    // --------------------------------------------------------------------------
+    async handleMasterCardAuth(payment, actionData) {
+        const threeDSData = actionData?.metadata?.threeds;
+        if (!threeDSData?.sessionId || !threeDSData?.merchantId) {
+            this.callbacks.onError?.('Missing MasterCard 3DS data');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            this.callbacks.onProcessing?.(false);
+            await this.loadScript(threeDSData.scriptUrl, () => !!window.ThreeDS);
+            const containerId = 'mastercard-3ds-container';
+            let container = document.getElementById(containerId);
+            if (!container) {
+                container = document.createElement('div');
+                container.id = containerId;
+                container.style.cssText = 'position:absolute;top:-9999px;left:-9999px;width:1px;height:1px;overflow:hidden';
+                document.body.appendChild(container);
+            }
+            await new Promise((resolve, reject) => {
+                window.ThreeDS.configure({
+                    merchantId: threeDSData.merchantId,
+                    sessionId: threeDSData.sessionId,
+                    containerId,
+                    callback: () => {
+                        window.ThreeDS.isConfigured() ? resolve() : reject(new Error('ThreeDS configuration failed'));
+                    },
+                    configuration: { userLanguage: 'en-US', wsVersion: threeDSData.version ? parseInt(threeDSData.version, 10) : 72 },
+                });
+            });
+            const authResult = await new Promise((resolve) => {
+                window.ThreeDS.authenticatePayer(threeDSData.orderId, threeDSData.transactionId, resolve);
+            });
+            const challengeHtml = authResult?.htmlRedirectCode || authResult?.restApiResponse?.authentication?.redirect?.html;
+            if (challengeHtml) {
+                // For standalone, redirect via form submission (no modal support without React)
+                const tempDoc = document.implementation.createHTMLDocument('MasterCard 3DS');
+                tempDoc.body.innerHTML = challengeHtml;
+                const form = tempDoc.querySelector('form');
+                if (form) {
+                    const redirectForm = document.createElement('form');
+                    redirectForm.method = form.method || 'POST';
+                    redirectForm.action = form.action || '';
+                    redirectForm.style.display = 'none';
+                    form.querySelectorAll('input').forEach(input => {
+                        const newInput = document.createElement('input');
+                        newInput.type = input.type;
+                        newInput.name = input.name;
+                        newInput.value = input.value;
+                        redirectForm.appendChild(newInput);
+                    });
+                    document.body.appendChild(redirectForm);
+                    redirectForm.submit();
+                }
+                else {
+                    document.open();
+                    document.write(challengeHtml);
+                    document.close();
+                }
+            }
+            else {
+                // Frictionless — complete immediately
+                if (threeDSData.paymentId) {
+                    const resumed = await this.paymentsResource.completePaymentAfterAction(threeDSData.paymentId);
+                    await this.handleResumedPayment(resumed);
+                }
+            }
+            const cleanup = document.getElementById(containerId);
+            if (cleanup)
+                cleanup.remove();
+        }
+        catch (error) {
+            this.callbacks.onError?.(error instanceof Error ? error.message : 'MasterCard 3DS failed');
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Script loader utility
+    // --------------------------------------------------------------------------
+    async loadScript(src, isReady) {
+        if (typeof window === 'undefined')
+            return;
+        if (isReady())
+            return;
+        const existing = document.querySelector(`script[src="${src}"]`);
+        if (existing) {
+            await this.waitFor(isReady, 10000);
+            return;
+        }
+        const script = document.createElement('script');
+        script.src = src;
+        script.async = true;
+        await new Promise((resolve, reject) => {
+            script.onload = () => resolve();
+            script.onerror = () => reject(new Error(`Failed to load script: ${src}`));
+            document.head.appendChild(script);
+        });
+    }
+    waitFor(predicate, timeout) {
+        return new Promise((resolve, reject) => {
+            if (predicate()) {
+                resolve();
+                return;
+            }
+            const t = setTimeout(() => reject(new Error('Timeout')), timeout);
+            const check = () => {
+                if (predicate()) {
+                    clearTimeout(t);
+                    resolve();
+                }
+                else
+                    setTimeout(check, 100);
+            };
+            check();
+        });
+    }
+    // ==========================================================================
+    // REDIRECT RETURN DETECTION
+    // ==========================================================================
+    /**
+     * Detect ALL redirect return types and resume.
+     * Handles both generic returns and Airwallex-specific 3DS returns.
+     * Call once during initialization. Returns true if a return was detected.
+     */
+    detectRedirectReturn() {
+        if (typeof window === 'undefined')
+            return false;
+        if (this.redirectReturnProcessed)
+            return false;
+        // Try Airwallex 3DS return first
+        if (this.detectAirwallex3dsReturn())
+            return true;
+        // Then generic return
+        return this.detectGenericRedirectReturn();
+    }
+    detectGenericRedirectReturn() {
+        const url = new URLSearchParams(window.location.search);
+        const paymentAction = url.get('paymentAction');
+        const paymentActionStatus = url.get('paymentActionStatus');
+        const paymentId = url.get('paymentId');
+        const mode = url.get('mode');
+        if (mode === 'retrieve')
+            return false;
+        if (paymentAction !== 'requireAction' || paymentActionStatus !== 'completed' || !paymentId)
+            return false;
+        console.log('[PaymentService] Generic redirect return detected:', paymentId);
+        this.redirectReturnProcessed = true;
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onCurrentPaymentId?.(paymentId);
+        this.callbacks.onRedirectReturn?.(paymentId);
+        this.startPolling(paymentId, {
+            onSuccess: (payment) => {
+                this.callbacks.onProcessing?.(false);
+                this.cleanPaymentUrlParams();
+                this.callbacks.onSuccess?.(payment);
+            },
+            onFailure: (error) => {
+                this.callbacks.onError?.(error);
+                this.callbacks.onProcessing?.(false);
+                this.cleanPaymentUrlParams();
+            },
+            onRequireAction: (payment) => { void this.handlePaymentAction(payment); },
+        });
+        return true;
+    }
+    detectAirwallex3dsReturn() {
+        const url = new URLSearchParams(window.location.search);
+        const paymentIdFromUrl = url.get('paymentId');
+        const paymentIntentId = url.get('payment_intent_id');
+        const succeeded = url.get('succeeded');
+        const processorType = url.get('processorType');
+        const hasAirwallexParams = paymentIntentId || succeeded !== null;
+        if (!hasAirwallexParams || processorType !== 'airwallex' || !paymentIdFromUrl)
+            return false;
+        console.log('[PaymentService] Airwallex 3DS return detected:', paymentIdFromUrl);
+        this.redirectReturnProcessed = true;
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onCurrentPaymentId?.(paymentIdFromUrl);
+        void this.handleAirwallex3dsRedirectReturn(paymentIdFromUrl, paymentIntentId, succeeded);
+        return true;
+    }
+    async handleAirwallex3dsRedirectReturn(paymentId, paymentIntentId, succeeded) {
+        const cleanParams = () => {
+            const url = new URLSearchParams(window.location.search);
+            ['payment_intent_id', 'succeeded', 'processorType', 'paymentId', 'paymentAction', 'paymentActionStatus', 'error_code', 'error_message', 'mode'].forEach(p => url.delete(p));
+            const newUrl = url.toString() ? `${window.location.pathname}?${url.toString()}` : window.location.pathname;
+            window.history.replaceState({}, document.title, newUrl);
+        };
+        if (succeeded === 'true') {
+            try {
+                await this.paymentsResource.updateThreedsStatus({
+                    paymentId,
+                    status: 'succeeded',
+                    paymentIntentId: paymentIntentId || '',
+                });
+                cleanParams();
+                const retrieveResult = await this.paymentsResource.retrievePayment(paymentId);
+                const retrieveStatus = retrieveResult?.retrieveResult?.status || retrieveResult?.status;
+                if (retrieveResult?.retrieveResult?.success && retrieveStatus === 'succeeded') {
+                    const payment = await this.paymentsResource.getPaymentStatus(paymentId);
+                    this.callbacks.onProcessing?.(false);
+                    this.callbacks.onSuccess?.(payment);
+                }
+                else if (retrieveStatus === 'declined' || retrieveStatus === 'error') {
+                    const msg = retrieveResult?.retrieveResult?.message || retrieveResult?.message || 'Payment failed';
+                    this.callbacks.onError?.(msg);
+                    this.callbacks.onProcessing?.(false);
+                }
+                else {
+                    const payment = await this.paymentsResource.getPaymentStatus(paymentId);
+                    if (payment.status === 'declined' || payment.status === 'failed') {
+                        const msg = payment.error?.message || payment.error?.processorMessage || 'Payment declined';
+                        this.callbacks.onError?.(msg);
+                        this.callbacks.onProcessing?.(false);
+                    }
+                    else if (payment.status === 'succeeded' || (payment.status === 'pending' && payment.subStatus === 'authorized')) {
+                        this.callbacks.onProcessing?.(false);
+                        this.callbacks.onSuccess?.(payment);
+                    }
+                    else if (payment.requireAction !== 'none' && payment.requireActionData && !payment.requireActionData.processed) {
+                        void this.handlePaymentAction(payment);
+                    }
+                    else {
+                        this.startPolling(paymentId, {
+                            onSuccess: (p) => { this.callbacks.onProcessing?.(false); this.callbacks.onSuccess?.(p); },
+                            onFailure: (e) => { this.callbacks.onError?.(e); this.callbacks.onProcessing?.(false); },
+                            onRequireAction: (p) => { void this.handlePaymentAction(p); },
+                        });
+                    }
+                }
+            }
+            catch (error) {
+                this.callbacks.onError?.(error instanceof Error ? error.message : 'Failed to process Airwallex 3DS');
+                this.callbacks.onProcessing?.(false);
+            }
+        }
+        else {
+            const errorMsg = new URLSearchParams(window.location.search).get('error_message') || 'Authentication failed';
+            this.callbacks.onError?.(errorMsg);
+            this.callbacks.onProcessing?.(false);
+            cleanParams();
+        }
+    }
+    cleanPaymentUrlParams() {
+        if (typeof window === 'undefined')
+            return;
+        const url = new URLSearchParams(window.location.search);
+        ['paymentAction', 'paymentActionStatus', 'paymentId', 'payment_intent', 'payment_intent_client_secret', 'source_type', 'redirect_status'].forEach(p => url.delete(p));
+        const newUrl = url.toString() ? `${window.location.pathname}?${url.toString()}` : window.location.pathname;
+        window.history.replaceState({}, document.title, newUrl);
+    }
+    // ==========================================================================
+    // PAYMENT INSTRUMENT MANAGEMENT
+    // ==========================================================================
+    async createCardPaymentInstrument(cardData) {
+        const bt = await this.initBasisTheory();
+        return this.paymentsResource.createCardPaymentInstrument(bt ?? undefined, cardData);
+    }
+    async createApplePayPaymentInstrument(token) {
+        const bt = await this.initBasisTheory();
+        return this.paymentsResource.createApplePayPaymentInstrument(bt ?? undefined, token);
+    }
+    async createGooglePayPaymentInstrument(token) {
+        const bt = await this.initBasisTheory();
+        return this.paymentsResource.createGooglePayPaymentInstrument(bt ?? undefined, token);
+    }
+    async getCardPaymentInstruments() {
+        return this.paymentsResource.getCardPaymentInstruments();
+    }
+    // ==========================================================================
+    // 3DS SESSION + CHALLENGE (mirrors useThreeds)
+    // ==========================================================================
+    async createThreedsSession(paymentInstrument) {
+        const BasisTheory3ds = await this.initBt3ds();
+        if (!BasisTheory3ds)
+            throw new Error('BasisTheory 3DS not loaded');
+        const bt3ds = BasisTheory3ds(this.getBtApiKey());
+        const session = await bt3ds.createSession({ tokenId: paymentInstrument.token });
+        return this.threedsResource.createSession({
+            provider: 'basis_theory',
+            sessionData: session,
+            paymentInstrumentId: paymentInstrument.id,
+        });
+    }
+    // ==========================================================================
+    // PAYMENT PROCESSING (all methods)
+    // ==========================================================================
+    async processCardPayment(checkoutSessionId, cardData) {
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onError?.(null);
+        try {
+            const instrument = await this.createCardPaymentInstrument({
+                cardNumber: cardData.cardNumber,
+                expiryDate: cardData.expiryDate,
+                cvc: cardData.cvc,
+            });
+            if (!instrument?.id)
+                throw new Error('Failed to create payment instrument');
+            // Auto-detect 3DS from store config
+            let threedsSessionId;
+            const config = await this.fetchStoreConfig();
+            if (config?.computed?.threedsEnabled) {
+                try {
+                    const session = await this.createThreedsSession(instrument);
+                    threedsSessionId = session.id;
+                }
+                catch {
+                    // Continue without 3DS
+                }
+            }
+            return await this.processAndHandle(checkoutSessionId, instrument.id, threedsSessionId);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+            return { success: false, error: msg };
+        }
+    }
+    async processApplePayPayment(checkoutSessionId, applePayToken) {
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onError?.(null);
+        try {
+            const instrument = await this.createApplePayPaymentInstrument(applePayToken);
+            return await this.processAndHandle(checkoutSessionId, instrument.id);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+            return { success: false, error: msg };
+        }
+    }
+    async processGooglePayPayment(checkoutSessionId, googlePayToken) {
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onError?.(null);
+        try {
+            const instrument = await this.createGooglePayPaymentInstrument(googlePayToken);
+            return await this.processAndHandle(checkoutSessionId, instrument.id);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+            return { success: false, error: msg };
+        }
+    }
+    async processPaymentWithInstrument(checkoutSessionId, paymentInstrumentId) {
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onError?.(null);
+        try {
+            return await this.processAndHandle(checkoutSessionId, paymentInstrumentId);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+            return { success: false, error: msg };
+        }
+    }
+    async processApmPayment(checkoutSessionId, apmData) {
+        this.callbacks.onProcessing?.(true);
+        this.callbacks.onError?.(null);
+        try {
+            return await this.processAndHandle(checkoutSessionId, '', undefined, {
+                processorId: apmData.processorId,
+                paymentMethod: apmData.paymentMethod,
+                initiatedBy: apmData.initiatedBy,
+                source: apmData.source,
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+            return { success: false, error: msg };
+        }
+    }
+}