@tagadapay/plugin-sdk 3.1.5 → 3.1.9

package/dist/v2/react/hooks/usePaymentQuery.js

@@ -10,8 +10,12 @@ import { PaymentsResource } from '../../core/resources/payments';
 import { usePaymentPolling } from './usePaymentPolling';
 import { useThreeds } from './useThreeds';
 import { getGlobalApiClient } from './useApiQuery';
-export function usePaymentQuery() {
+import { useStoreConfigQuery } from './useStoreConfigQuery';
+import { getAssignedPaymentFlowId } from '../../core/funnelClient';
+export function usePaymentQuery(hookOptions) {
     const { environment } = useTagadaContext();
+    // Get store config to auto-detect 3DS setting from payment flow
+    const { storeConfig } = useStoreConfigQuery();
     // Create payments resource client
     const paymentsResource = useMemo(() => {
         try {
@@ -24,10 +28,17 @@ export function usePaymentQuery() {
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const [currentPaymentId, setCurrentPaymentId] = useState(null);
+    // Store hook-level callbacks in ref to avoid re-renders
+    const hookOptionsRef = useRef(hookOptions);
+    useEffect(() => {
+        hookOptionsRef.current = hookOptions;
+    }, [hookOptions]);
     const { startPolling, stopPolling } = usePaymentPolling();
     const { createSession, startChallenge } = useThreeds();
     // Track challenge in progress to prevent multiple challenges
     const challengeInProgressRef = useRef(false);
+    // Track if we've already processed a redirect return (prevents double-processing)
+    const redirectReturnProcessedRef = useRef(false);
     // Get API key from embedded configuration with proper environment detection
     const apiKey = useMemo(() => getBasisTheoryApiKey(), []); // Auto-detects environment
     // Initialize BasisTheory using React wrapper
@@ -83,7 +94,7 @@ export function usePaymentQuery() {
                                 onRequireAction: (updatedPayment) => {
                                     void handlePaymentAction(updatedPayment, options);
                                 },
-                                onSuccess: (successPayment) => {
+                                onSuccess: async (successPayment) => {
                                     setIsLoading(false);
                                     const response = {
                                         paymentId: successPayment.id,
@@ -91,14 +102,27 @@ export function usePaymentQuery() {
                                         // Extract order from payment if available (for funnel path resolution)
                                         order: successPayment.order,
                                     };
+                                    // Hook-level callback (universal handler)
+                                    if (hookOptionsRef.current?.onPaymentCompleted) {
+                                        await hookOptionsRef.current.onPaymentCompleted(successPayment, {
+                                            isRedirectReturn: false,
+                                            order: response.order,
+                                        });
+                                    }
                                     // Legacy callback (backwards compatibility)
                                     options.onSuccess?.(response);
                                     // Funnel-aligned callback (recommended)
                                     options.onPaymentSuccess?.(response);
                                 },
-                                onFailure: (errorMsg) => {
+                                onFailure: async (errorMsg) => {
                                     setError(errorMsg);
                                     setIsLoading(false);
+                                    // Hook-level callback (universal handler)
+                                    if (hookOptionsRef.current?.onPaymentFailed) {
+                                        await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                            isRedirectReturn: false,
+                                        });
+                                    }
                                     // Legacy callback (backwards compatibility)
                                     options.onFailure?.(errorMsg);
                                     // Funnel-aligned callback (recommended)
@@ -150,6 +174,13 @@ export function usePaymentQuery() {
                         // Extract order from payment if available (for funnel path resolution)
                         order: payment.order,
                     };
+                    // Hook-level callback (universal handler)
+                    if (hookOptionsRef.current?.onPaymentCompleted) {
+                        await hookOptionsRef.current.onPaymentCompleted(payment, {
+                            isRedirectReturn: false,
+                            order: response.order,
+                        });
+                    }
                     // Legacy callback (backwards compatibility)
                     options.onSuccess?.(response);
                     // Funnel-aligned callback (recommended)
@@ -172,9 +203,646 @@ export function usePaymentQuery() {
                 });
                 break;
             }
+            case 'finix_radar': {
+                // Handle Finix fraud detection - collect device fingerprint
+                const radarConfig = actionData.metadata?.radar;
+                if (!radarConfig) {
+                    console.error('Finix radar config missing from payment action');
+                    break;
+                }
+                try {
+                    // Dynamically load Finix SDK if not already loaded
+                    if (typeof window !== 'undefined' && typeof window.Finix?.Auth !== 'function') {
+                        const existingScript = document.querySelector('script[src="https://js.finix.com/v/1/finix.js"]');
+                        if (!existingScript) {
+                            const script = document.createElement('script');
+                            script.src = 'https://js.finix.com/v/1/finix.js';
+                            script.async = true;
+                            document.head.appendChild(script);
+                            await new Promise((resolve, reject) => {
+                                script.onload = () => {
+                                    console.log('Finix SDK loaded successfully');
+                                    resolve();
+                                };
+                                script.onerror = () => reject(new Error('Failed to load Finix SDK'));
+                            });
+                        }
+                        else {
+                            // Wait for existing script to load
+                            await new Promise((resolve, reject) => {
+                                const checkFinix = () => {
+                                    if (typeof window.Finix?.Auth === 'function') {
+                                        resolve();
+                                    }
+                                    else {
+                                        setTimeout(checkFinix, 100);
+                                    }
+                                };
+                                checkFinix();
+                                setTimeout(() => reject(new Error('Timeout waiting for Finix SDK')), 10000);
+                            });
+                        }
+                    }
+                    // Get session key from Finix using callback to ensure initialization is complete
+                    const sessionKey = await new Promise((resolve, reject) => {
+                        const timeoutId = setTimeout(() => {
+                            reject(new Error('Timeout waiting for Finix Auth initialization'));
+                        }, 10000);
+                        // Initialize Finix Auth with callback
+                        const FinixAuth = window.Finix.Auth(radarConfig.environment, radarConfig.merchantId, () => {
+                            // Callback fired when Finix Auth is ready
+                            clearTimeout(timeoutId);
+                            const key = FinixAuth.getSessionKey();
+                            console.log('Finix Auth initialized, session key:', key);
+                            if (key) {
+                                resolve(key);
+                            }
+                            else {
+                                reject(new Error('No session key returned from Finix after initialization'));
+                            }
+                        });
+                        // Also try getting session key immediately in case it's already ready
+                        const immediateKey = FinixAuth.getSessionKey();
+                        if (immediateKey) {
+                            clearTimeout(timeoutId);
+                            console.log('Finix session key obtained immediately:', immediateKey);
+                            resolve(immediateKey);
+                        }
+                    });
+                    console.log('Finix fraud session key obtained:', sessionKey);
+                    // Save radar session to database
+                    await paymentsResource.saveRadarSession({
+                        orderId: radarConfig.orderId,
+                        finixRadarSessionId: sessionKey,
+                        finixRadarSessionData: {
+                            sessionKey,
+                            merchantId: radarConfig.merchantId,
+                            environment: radarConfig.environment,
+                            createdAt: new Date().toISOString(),
+                        },
+                    });
+                    console.log('Finix radar session saved to database');
+                    // Resume payment by calling completePaymentAfterAction
+                    const resumedPayment = await paymentsResource.completePaymentAfterAction(payment.id);
+                    console.log('Payment resumed after Finix radar:', resumedPayment);
+                    // Handle the resumed payment response
+                    // This is because a failed 3DS can return with status=declined but still have requireAction set
+                    if (resumedPayment.status === 'declined' || resumedPayment.status === 'failed') {
+                        // Payment declined or failed - extract error message from response
+                        const errorMsg = resumedPayment.error?.message
+                            || resumedPayment.error?.processorMessage
+                            || 'Payment declined';
+                        console.error('❌ [usePayment] Payment declined after Finix radar:', errorMsg);
+                        setError(errorMsg);
+                        setIsLoading(false);
+                        options.onFailure?.(errorMsg);
+                        options.onPaymentFailed?.({
+                            code: resumedPayment.error?.code || 'PAYMENT_DECLINED',
+                            message: errorMsg,
+                            payment: resumedPayment,
+                        });
+                        // Hook-level callback (universal handler)
+                        if (hookOptionsRef.current?.onPaymentFailed) {
+                            hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                isRedirectReturn: false,
+                            });
+                        }
+                    }
+                    else if (resumedPayment.status === 'succeeded') {
+                        // Payment succeeded
+                        setIsLoading(false);
+                        const response = {
+                            paymentId: resumedPayment.id,
+                            payment: resumedPayment,
+                            order: resumedPayment.order,
+                        };
+                        options.onSuccess?.(response);
+                        options.onPaymentSuccess?.(response);
+                    }
+                    else if (resumedPayment.requireAction !== 'none' && resumedPayment.requireActionData) {
+                        // Payment requires another action (e.g., 3DS)
+                        await handlePaymentAction(resumedPayment, options);
+                    }
+                    else {
+                        // Start polling for final status
+                        startPolling(resumedPayment.id, {
+                            onRequireAction: (updatedPayment) => {
+                                void handlePaymentAction(updatedPayment, options);
+                            },
+                            onSuccess: (successPayment) => {
+                                setIsLoading(false);
+                                const response = {
+                                    paymentId: successPayment.id,
+                                    payment: successPayment,
+                                    order: successPayment.order,
+                                };
+                                options.onSuccess?.(response);
+                                options.onPaymentSuccess?.(response);
+                            },
+                            onFailure: (errorMsg) => {
+                                setError(errorMsg);
+                                setIsLoading(false);
+                                options.onFailure?.(errorMsg);
+                                options.onPaymentFailed?.({
+                                    code: 'PAYMENT_FAILED',
+                                    message: errorMsg,
+                                    payment,
+                                });
+                            },
+                        });
+                    }
+                }
+                catch (radarError) {
+                    const errorMsg = radarError instanceof Error ? radarError.message : 'Finix fraud detection failed';
+                    console.error('Finix radar error:', radarError);
+                    setError(errorMsg);
+                    setIsLoading(false);
+                    options.onFailure?.(errorMsg);
+                    options.onPaymentFailed?.({
+                        code: 'FINIX_RADAR_FAILED',
+                        message: errorMsg,
+                        payment,
+                    });
+                }
+                break;
+            }
+            case 'radar': {
+                // Handle generic radar - check provider for specific implementation
+                if (actionData.metadata?.provider === 'airwallex') {
+                    // Handle Airwallex fraud detection - collect device fingerprint
+                    const isTest = actionData.metadata?.isTest || false;
+                    const orderId = payment.order?.id;
+                    const checkoutSessionId = payment.order?.checkoutSessionId;
+                    if (!orderId || !checkoutSessionId) {
+                        console.error('Airwallex radar: missing order or checkoutSessionId');
+                        setError('Missing order information for fraud detection');
+                        setIsLoading(false);
+                        options.onFailure?.('Missing order information for fraud detection');
+                        options.onPaymentFailed?.({
+                            code: 'AIRWALLEX_RADAR_MISSING_ORDER',
+                            message: 'Missing order information for fraud detection',
+                            payment,
+                        });
+                        break;
+                    }
+                    try {
+                        // Generate a unique session ID for Airwallex device fingerprinting
+                        const generateAirwallexSessionId = () => {
+                            return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+                                const r = (Math.random() * 16) | 0;
+                                const v = c === 'x' ? r : (r & 0x3) | 0x8;
+                                return v.toString(16);
+                            });
+                        };
+                        const sessionId = generateAirwallexSessionId();
+                        // Load Airwallex fraud API script if not already loaded
+                        const existingScript = document.getElementById('airwallex-fraud-api');
+                        if (!existingScript) {
+                            const script = document.createElement('script');
+                            script.type = 'text/javascript';
+                            script.async = true;
+                            script.id = 'airwallex-fraud-api';
+                            script.setAttribute('data-order-session-id', sessionId);
+                            // Use demo URL for testing, production URL for live
+                            const baseUrl = isTest ? 'https://static-demo.airwallex.com' : 'https://static.airwallex.com';
+                            script.src = `${baseUrl}/webapp/fraud/device-fingerprint/index.js`;
+                            // Wait for script to load
+                            await new Promise((resolve, reject) => {
+                                script.onload = () => {
+                                    console.log('Airwallex fraud API script loaded successfully');
+                                    resolve();
+                                };
+                                script.onerror = () => {
+                                    reject(new Error('Failed to load Airwallex fraud API script'));
+                                };
+                                // Append script to body
+                                document.body.appendChild(script);
+                            });
+                        }
+                        else {
+                            // Update existing script with new session ID
+                            existingScript.setAttribute('data-order-session-id', sessionId);
+                            console.log('Updated existing Airwallex script with new session ID');
+                        }
+                        console.log('Airwallex device fingerprint session created:', sessionId);
+                        // Save radar session to database
+                        await paymentsResource.saveRadarSession({
+                            checkoutSessionId,
+                            orderId,
+                            airwallexRadarSessionId: sessionId,
+                        });
+                        console.log('Airwallex radar session saved to database');
+                        // Resume payment by calling completePaymentAfterAction
+                        const resumedPayment = await paymentsResource.completePaymentAfterAction(payment.id);
+                        console.log('Payment resumed after Airwallex radar:', resumedPayment);
+                        console.log('📊 [usePayment] Resumed payment details:', {
+                            status: resumedPayment.status,
+                            requireAction: resumedPayment.requireAction,
+                            hasRequireActionData: !!resumedPayment.requireActionData,
+                            error: resumedPayment.error,
+                        });
+                        // Handle the resumed payment response
+                        // IMPORTANT: Check for declined/failed status FIRST, before checking requireAction
+                        // This is because a failed 3DS can return with status=declined but still have requireAction set
+                        if (resumedPayment.status === 'declined' || resumedPayment.status === 'failed') {
+                            // Payment declined or failed - extract error message from response
+                            const errorMsg = resumedPayment.error?.message
+                                || resumedPayment.error?.processorMessage
+                                || 'Payment declined';
+                            console.error('❌ [usePayment] Payment declined after Airwallex radar:', errorMsg);
+                            setError(errorMsg);
+                            setIsLoading(false);
+                            options.onFailure?.(errorMsg);
+                            options.onPaymentFailed?.({
+                                code: resumedPayment.error?.code || 'PAYMENT_DECLINED',
+                                message: errorMsg,
+                                payment: resumedPayment,
+                            });
+                            // Hook-level callback (universal handler)
+                            if (hookOptionsRef.current?.onPaymentFailed) {
+                                hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                    isRedirectReturn: false,
+                                });
+                            }
+                        }
+                        else if (resumedPayment.status === 'succeeded') {
+                            // Payment succeeded
+                            setIsLoading(false);
+                            const response = {
+                                paymentId: resumedPayment.id,
+                                payment: resumedPayment,
+                                order: resumedPayment.order,
+                            };
+                            options.onSuccess?.(response);
+                            options.onPaymentSuccess?.(response);
+                        }
+                        else if (resumedPayment.requireAction !== 'none' && resumedPayment.requireActionData) {
+                            // Payment requires another action (e.g., 3DS)
+                            await handlePaymentAction(resumedPayment, options);
+                        }
+                        else {
+                            // Start polling for final status
+                            startPolling(resumedPayment.id, {
+                                onRequireAction: (updatedPayment) => {
+                                    void handlePaymentAction(updatedPayment, options);
+                                },
+                                onSuccess: (successPayment) => {
+                                    setIsLoading(false);
+                                    const response = {
+                                        paymentId: successPayment.id,
+                                        payment: successPayment,
+                                        order: successPayment.order,
+                                    };
+                                    options.onSuccess?.(response);
+                                    options.onPaymentSuccess?.(response);
+                                },
+                                onFailure: (errorMsg) => {
+                                    setError(errorMsg);
+                                    setIsLoading(false);
+                                    options.onFailure?.(errorMsg);
+                                    options.onPaymentFailed?.({
+                                        code: 'PAYMENT_FAILED',
+                                        message: errorMsg,
+                                        payment,
+                                    });
+                                },
+                            });
+                        }
+                    }
+                    catch (radarError) {
+                        const errorMsg = radarError instanceof Error ? radarError.message : 'Airwallex fraud detection failed';
+                        console.error('Airwallex radar error:', radarError);
+                        setError(errorMsg);
+                        setIsLoading(false);
+                        options.onFailure?.(errorMsg);
+                        options.onPaymentFailed?.({
+                            code: 'AIRWALLEX_RADAR_FAILED',
+                            message: errorMsg,
+                            payment,
+                        });
+                    }
+                }
+                break;
+            }
         }
         options.onRequireAction?.(payment);
     }, [paymentsResource, startPolling, startChallenge]);
+    // Auto-detect payment action from URL parameters (after redirect from Stripe, PayPal, Airwallex, etc.)
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        // Prevent double-processing of redirect returns
+        if (redirectReturnProcessedRef.current) {
+            console.log('⏭️ [usePayment] Redirect return already processed, skipping');
+            return;
+        }
+        const urlParams = new URLSearchParams(window.location.search);
+        const paymentAction = urlParams.get('paymentAction');
+        const paymentActionStatus = urlParams.get('paymentActionStatus');
+        const paymentIdFromUrl = urlParams.get('paymentId');
+        const paymentMode = urlParams.get('mode');
+        // Airwallex 3DS return parameters
+        const paymentIntentId = urlParams.get('payment_intent_id');
+        const succeeded = urlParams.get('succeeded');
+        const processorType = urlParams.get('processorType');
+        console.log('🔍 [usePayment] Checking for payment redirect return...', {
+            paymentAction,
+            paymentActionStatus,
+            paymentId: paymentIdFromUrl,
+            mode: paymentMode,
+            paymentIntentId,
+            succeeded,
+            processorType,
+            url: window.location.href,
+        });
+        // Handle Airwallex 3DS return (payment_intent_id + succeeded + processorType=airwallex)
+        // This must be checked BEFORE the generic retrieve mode check, because Airwallex 3DS returns
+        // include mode=retrieve but also need special handling for updating the 3DS status first
+        const hasAirwallexParams = paymentIntentId || succeeded !== null;
+        if (hasAirwallexParams && processorType === 'airwallex' && paymentIdFromUrl) {
+            console.log('✅ [usePayment] Airwallex 3DS return detected!', {
+                paymentIntentId,
+                succeeded,
+                paymentId: paymentIdFromUrl,
+            });
+            // Mark as processed immediately to prevent double-processing
+            redirectReturnProcessedRef.current = true;
+            const handleAirwallex3dsReturn = async () => {
+                setIsLoading(true);
+                setCurrentPaymentId(paymentIdFromUrl);
+                if (succeeded === 'true') {
+                    try {
+                        // Update 3DS session status
+                        await paymentsResource.updateThreedsStatus({
+                            paymentId: paymentIdFromUrl,
+                            status: 'succeeded',
+                            paymentIntentId: paymentIntentId || '',
+                        });
+                        console.log('✅ [usePayment] Airwallex 3DS status updated successfully');
+                        // Clean up URL parameters
+                        const cleanParams = new URLSearchParams(window.location.search);
+                        const airwallexParams = ['payment_intent_id', 'succeeded', 'processorType', 'paymentId', 'paymentAction', 'paymentActionStatus', 'error_code', 'error_message', 'mode'];
+                        airwallexParams.forEach(param => cleanParams.delete(param));
+                        const newUrl = cleanParams.toString()
+                            ? `${window.location.pathname}?${cleanParams.toString()}`
+                            : window.location.pathname;
+                        window.history.replaceState({}, document.title, newUrl);
+                        // Retrieve payment to trigger server-side check with Airwallex and finalize
+                        console.log('🔄 [usePayment] Retrieving payment to finalize after Airwallex 3DS...');
+                        const retrieveResult = await paymentsResource.retrievePayment(paymentIdFromUrl);
+                        console.log('📊 [usePayment] Retrieve result:', retrieveResult);
+                        // Check retrieve result
+                        const retrieveStatus = retrieveResult?.retrieveResult?.status || retrieveResult?.status;
+                        if (retrieveResult?.retrieveResult?.success && retrieveStatus === 'succeeded') {
+                            // Payment succeeded - get full payment details
+                            const payment = await paymentsResource.getPaymentStatus(paymentIdFromUrl);
+                            console.log('✅ [usePayment] Payment succeeded after Airwallex 3DS!', payment);
+                            setIsLoading(false);
+                            if (hookOptionsRef.current?.onPaymentCompleted) {
+                                try {
+                                    await hookOptionsRef.current.onPaymentCompleted(payment, {
+                                        isRedirectReturn: true,
+                                        order: payment.order,
+                                    });
+                                }
+                                catch (error) {
+                                    console.error('❌ [usePayment] Error in onPaymentCompleted callback:', error);
+                                }
+                            }
+                        }
+                        else if (retrieveStatus === 'declined' || retrieveStatus === 'error') {
+                            // Payment failed
+                            const errorMsg = retrieveResult?.retrieveResult?.message || retrieveResult?.message || 'Payment failed';
+                            console.error('❌ [usePayment] Payment failed after Airwallex 3DS:', errorMsg);
+                            setError(errorMsg);
+                            setIsLoading(false);
+                            if (hookOptionsRef.current?.onPaymentFailed) {
+                                try {
+                                    await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                        isRedirectReturn: true,
+                                    });
+                                }
+                                catch (error) {
+                                    console.error('❌ [usePayment] Error in onPaymentFailed callback:', error);
+                                }
+                            }
+                        }
+                        else {
+                            // Payment still pending or other status - check payment details
+                            const payment = await paymentsResource.getPaymentStatus(paymentIdFromUrl);
+                            console.log('📊 [usePayment] Payment status after retrieve:', payment);
+                            if (payment.status === 'declined' || payment.status === 'failed') {
+                                // Payment was declined
+                                const errorMsg = payment.error?.message || payment.error?.processorMessage || 'Payment declined';
+                                console.error('❌ [usePayment] Payment declined after Airwallex 3DS:', errorMsg);
+                                setError(errorMsg);
+                                setIsLoading(false);
+                                if (hookOptionsRef.current?.onPaymentFailed) {
+                                    try {
+                                        await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                            isRedirectReturn: true,
+                                        });
+                                    }
+                                    catch (error) {
+                                        console.error('❌ [usePayment] Error in onPaymentFailed callback:', error);
+                                    }
+                                }
+                            }
+                            else if (payment.requireAction !== 'none' && payment.requireActionData && !payment.requireActionData.processed) {
+                                console.log('⚠️ [usePayment] Payment requires new action after Airwallex 3DS', payment);
+                                void handlePaymentAction(payment, {});
+                            }
+                            else if (payment.status === 'succeeded' || (payment.status === 'pending' && payment.subStatus === 'authorized')) {
+                                console.log('✅ [usePayment] Payment succeeded after Airwallex 3DS!', payment);
+                                setIsLoading(false);
+                                if (hookOptionsRef.current?.onPaymentCompleted) {
+                                    try {
+                                        await hookOptionsRef.current.onPaymentCompleted(payment, {
+                                            isRedirectReturn: true,
+                                            order: payment.order,
+                                        });
+                                    }
+                                    catch (error) {
+                                        console.error('❌ [usePayment] Error in onPaymentCompleted callback:', error);
+                                    }
+                                }
+                            }
+                            else {
+                                // Still pending, start polling
+                                console.log('⏳ [usePayment] Payment still pending, starting polling...');
+                                startPolling(paymentIdFromUrl, {
+                                    onRequireAction: (polledPayment) => {
+                                        console.log('⚠️ [usePayment] Payment requires new action after Airwallex 3DS', polledPayment);
+                                        void handlePaymentAction(polledPayment, {});
+                                    },
+                                    onSuccess: async (polledPayment) => {
+                                        console.log('✅ [usePayment] Payment succeeded after Airwallex 3DS polling!', polledPayment);
+                                        setIsLoading(false);
+                                        if (hookOptionsRef.current?.onPaymentCompleted) {
+                                            try {
+                                                await hookOptionsRef.current.onPaymentCompleted(polledPayment, {
+                                                    isRedirectReturn: true,
+                                                    order: polledPayment.order,
+                                                });
+                                            }
+                                            catch (error) {
+                                                console.error('❌ [usePayment] Error in onPaymentCompleted callback:', error);
+                                            }
+                                        }
+                                    },
+                                    onFailure: async (errorMsg) => {
+                                        console.error('❌ [usePayment] Payment failed after Airwallex 3DS polling:', errorMsg);
+                                        setError(errorMsg);
+                                        setIsLoading(false);
+                                        if (hookOptionsRef.current?.onPaymentFailed) {
+                                            try {
+                                                await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                                    isRedirectReturn: true,
+                                                });
+                                            }
+                                            catch (error) {
+                                                console.error('❌ [usePayment] Error in onPaymentFailed callback:', error);
+                                            }
+                                        }
+                                    },
+                                });
+                            }
+                        }
+                    }
+                    catch (error) {
+                        console.error('❌ [usePayment] Failed to update Airwallex 3DS status:', error);
+                        setError('Failed to process 3DS authentication');
+                        setIsLoading(false);
+                        if (hookOptionsRef.current?.onPaymentFailed) {
+                            try {
+                                await hookOptionsRef.current.onPaymentFailed('Failed to process 3DS authentication', {
+                                    isRedirectReturn: true,
+                                });
+                            }
+                            catch (cbError) {
+                                console.error('❌ [usePayment] Error in onPaymentFailed callback:', cbError);
+                            }
+                        }
+                    }
+                }
+                else {
+                    // 3DS authentication failed
+                    console.error('❌ [usePayment] Airwallex 3DS authentication failed');
+                    const errorMsg = urlParams.get('error_message') || 'Authentication failed';
+                    setError(errorMsg);
+                    setIsLoading(false);
+                    // Clean up URL parameters
+                    const cleanParams = new URLSearchParams(window.location.search);
+                    const airwallexParams = ['payment_intent_id', 'succeeded', 'processorType', 'paymentId', 'paymentAction', 'paymentActionStatus', 'error_code', 'error_message', 'mode'];
+                    airwallexParams.forEach(param => cleanParams.delete(param));
+                    const newUrl = cleanParams.toString()
+                        ? `${window.location.pathname}?${cleanParams.toString()}`
+                        : window.location.pathname;
+                    window.history.replaceState({}, document.title, newUrl);
+                    if (hookOptionsRef.current?.onPaymentFailed) {
+                        try {
+                            await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                isRedirectReturn: true,
+                            });
+                        }
+                        catch (error) {
+                            console.error('❌ [usePayment] Error in onPaymentFailed callback:', error);
+                        }
+                    }
+                }
+            };
+            void handleAirwallex3dsReturn();
+            return;
+        }
+        // Skip if in retrieve mode (handled by usePaymentRetrieve hook)
+        // This check is AFTER the Airwallex handling because Airwallex 3DS returns include mode=retrieve
+        // but need special handling that usePaymentRetrieve doesn't provide
+        if (paymentMode === 'retrieve') {
+            console.log('⏭️ [usePayment] Skipping - retrieve mode detected (handled by usePaymentRetrieve)');
+            return;
+        }
+        // Check if returning from a payment redirect (generic handling)
+        if (paymentAction === 'requireAction' && paymentActionStatus === 'completed' && paymentIdFromUrl) {
+            console.log('✅ [usePayment] Payment redirect return detected! Starting auto-polling...', {
+                paymentId: paymentIdFromUrl,
+            });
+            // Mark as processed immediately to prevent double-processing
+            redirectReturnProcessedRef.current = true;
+            setIsLoading(true);
+            setCurrentPaymentId(paymentIdFromUrl);
+            // Start polling for the payment status
+            startPolling(paymentIdFromUrl, {
+                onRequireAction: (payment) => {
+                    console.log('⚠️ [usePayment] Payment requires new action', payment);
+                    void handlePaymentAction(payment, {});
+                },
+                onSuccess: async (payment) => {
+                    console.log('✅ [usePayment] Payment succeeded after redirect!', {
+                        paymentId: payment.id,
+                        status: payment.status,
+                        hasOrder: !!payment.order,
+                    });
+                    setIsLoading(false);
+                    // Clean up ONLY payment-related query parameters (preserve funnel/checkout params)
+                    const urlParams = new URLSearchParams(window.location.search);
+                    const paymentParams = ['paymentAction', 'paymentActionStatus', 'paymentId', 'payment_intent', 'payment_intent_client_secret', 'source_type', 'redirect_status'];
+                    paymentParams.forEach(param => urlParams.delete(param));
+                    const newUrl = urlParams.toString()
+                        ? `${window.location.pathname}?${urlParams.toString()}`
+                        : window.location.pathname;
+                    window.history.replaceState({}, document.title, newUrl);
+                    console.log('🧹 [usePayment] Payment URL parameters cleaned up (preserved funnel/checkout params)');
+                    // Call hook-level onPaymentCompleted callback (if provided)
+                    if (hookOptionsRef.current?.onPaymentCompleted) {
+                        console.log('📞 [usePayment] Calling onPaymentCompleted callback...', {
+                            isRedirectReturn: true,
+                        });
+                        try {
+                            await hookOptionsRef.current.onPaymentCompleted(payment, {
+                                isRedirectReturn: true,
+                                order: payment.order,
+                            });
+                            console.log('✅ [usePayment] onPaymentCompleted callback completed successfully');
+                        }
+                        catch (error) {
+                            console.error('❌ [usePayment] Error in onPaymentCompleted callback:', error);
+                        }
+                    }
+                    else {
+                        console.warn('⚠️ [usePayment] No onPaymentCompleted callback provided');
+                    }
+                },
+                onFailure: async (errorMsg) => {
+                    console.error('❌ [usePayment] Payment failed after redirect:', errorMsg);
+                    setError(errorMsg);
+                    setIsLoading(false);
+                    // Clean up ONLY payment-related query parameters (preserve funnel/checkout params)
+                    const urlParams = new URLSearchParams(window.location.search);
+                    const paymentParams = ['paymentAction', 'paymentActionStatus', 'paymentId', 'payment_intent', 'payment_intent_client_secret', 'source_type', 'redirect_status'];
+                    paymentParams.forEach(param => urlParams.delete(param));
+                    const newUrl = urlParams.toString()
+                        ? `${window.location.pathname}?${urlParams.toString()}`
+                        : window.location.pathname;
+                    window.history.replaceState({}, document.title, newUrl);
+                    // Call hook-level onPaymentFailed callback (if provided)
+                    if (hookOptionsRef.current?.onPaymentFailed) {
+                        console.log('📞 [usePayment] Calling onPaymentFailed callback...');
+                        try {
+                            await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                isRedirectReturn: true,
+                            });
+                        }
+                        catch (error) {
+                            console.error('❌ [usePayment] Error in onPaymentFailed callback:', error);
+                        }
+                    }
+                },
+            });
+        }
+        else {
+            console.log('⏭️ [usePayment] No payment redirect detected - normal page load');
+        }
+    }, [paymentsResource, startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId]);
     // Create card payment instrument - matches old implementation
     const createCardPaymentInstrument = useCallback((cardData) => {
         return paymentsResource.createCardPaymentInstrument(basisTheory, cardData);
@@ -183,12 +851,19 @@ export function usePaymentQuery() {
     const createApplePayPaymentInstrument = useCallback((applePayToken) => {
         return paymentsResource.createApplePayPaymentInstrument(basisTheory, applePayToken);
     }, [basisTheory, paymentsResource]);
+    // Create Google Pay payment instrument - matches express payment pattern
+    const createGooglePayPaymentInstrument = useCallback((googlePayToken) => {
+        return paymentsResource.createGooglePayPaymentInstrument(basisTheory, googlePayToken);
+    }, [basisTheory, paymentsResource]);
     // Process payment directly with checkout session - matches old implementation
     const processPaymentDirect = useCallback(async (checkoutSessionId, paymentInstrumentId, threedsSessionId, options = {}) => {
         try {
+            // Get paymentFlowId: priority is options > stepConfig > undefined (uses store default)
+            const paymentFlowId = options.paymentFlowId || getAssignedPaymentFlowId();
             const response = await paymentsResource.processPaymentDirect(checkoutSessionId, paymentInstrumentId, threedsSessionId, {
                 initiatedBy: options.initiatedBy,
                 source: options.source,
+                paymentFlowId,
             });
             setCurrentPaymentId(response.payment?.id);
             if (response.payment.requireAction !== 'none') {
@@ -201,6 +876,14 @@ export function usePaymentQuery() {
                     ...response,
                     order: response.order || response.payment.order,
                 };
+                // Hook-level callback (universal handler)
+                if (hookOptionsRef.current?.onPaymentCompleted) {
+                    await hookOptionsRef.current.onPaymentCompleted(response.payment, {
+                        isRedirectReturn: false,
+                        order: successResponse.order,
+                        checkoutSessionId,
+                    });
+                }
                 // Legacy callback (backwards compatibility)
                 options.onSuccess?.(successResponse);
                 // Funnel-aligned callback (recommended)
@@ -212,7 +895,7 @@ export function usePaymentQuery() {
                     onRequireAction: (payment) => {
                         void handlePaymentAction(payment, options);
                     },
-                    onSuccess: (payment) => {
+                    onSuccess: async (payment) => {
                         setIsLoading(false);
                         const successResponse = {
                             paymentId: payment.id,
@@ -220,14 +903,28 @@ export function usePaymentQuery() {
                             // Extract order from payment if available (for funnel path resolution)
                             order: payment.order,
                         };
+                        // Hook-level callback (universal handler)
+                        if (hookOptionsRef.current?.onPaymentCompleted) {
+                            await hookOptionsRef.current.onPaymentCompleted(payment, {
+                                isRedirectReturn: false,
+                                order: successResponse.order,
+                                checkoutSessionId,
+                            });
+                        }
                         // Legacy callback (backwards compatibility)
                         options.onSuccess?.(successResponse);
                         // Funnel-aligned callback (recommended)
                         options.onPaymentSuccess?.(successResponse);
                     },
-                    onFailure: (errorMsg) => {
+                    onFailure: async (errorMsg) => {
                         setError(errorMsg);
                         setIsLoading(false);
+                        // Hook-level callback (universal handler)
+                        if (hookOptionsRef.current?.onPaymentFailed) {
+                            await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                isRedirectReturn: false,
+                            });
+                        }
                         // Legacy callback (backwards compatibility)
                         options.onFailure?.(errorMsg);
                         // Funnel-aligned callback (recommended)
@@ -262,9 +959,10 @@ export function usePaymentQuery() {
         try {
             // 1. Create payment instrument
             const paymentInstrument = await createCardPaymentInstrument(cardData);
-            // 2. Create 3DS session if enabled
+            // 2. Create 3DS session if enabled (use payment flow setting if not explicitly provided)
+            const shouldCreateThreedsSession = storeConfig?.computed?.threedsEnabled;
             let threedsSessionId;
-            if (options.enableThreeds !== false) {
+            if (shouldCreateThreedsSession) {
                 try {
                     const threedsSession = await createSession(paymentInstrument, {
                         provider: options.threedsProvider || 'basis_theory',
@@ -315,6 +1013,30 @@ export function usePaymentQuery() {
             throw _error;
         }
     }, [createApplePayPaymentInstrument, processPaymentDirect]);
+    // Process Google Pay payment - matches express payment pattern
+    const processGooglePayPayment = useCallback(async (checkoutSessionId, googlePayToken, options = {}) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            // 1. Create payment instrument
+            const paymentInstrument = await createGooglePayPaymentInstrument(googlePayToken);
+            // 2. Process payment directly (Google Pay typically doesn't require 3DS)
+            return await processPaymentDirect(checkoutSessionId, paymentInstrument.id, undefined, options);
+        }
+        catch (_error) {
+            setIsLoading(false);
+            const errorMsg = _error instanceof Error ? _error.message : 'Google Pay payment failed';
+            setError(errorMsg);
+            // Legacy callback (backwards compatibility)
+            options.onFailure?.(errorMsg);
+            // Funnel-aligned callback (recommended)
+            options.onPaymentFailed?.({
+                code: 'GOOGLE_PAY_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [createGooglePayPaymentInstrument, processPaymentDirect]);
     // Process payment with existing instrument - matches old implementation
     const processPaymentWithInstrument = useCallback(async (checkoutSessionId, paymentInstrumentId, options = {}) => {
         setIsLoading(true);
@@ -354,9 +1076,11 @@ export function usePaymentQuery() {
     return {
         processCardPayment,
         processApplePayPayment,
+        processGooglePayPayment,
         processPaymentWithInstrument,
         createCardPaymentInstrument,
         createApplePayPaymentInstrument,
+        createGooglePayPaymentInstrument,
         getCardPaymentInstruments,
         isLoading: isLoading || !basisTheory, // Indicate loading if BasisTheory is not initialized
         error,