@tagadapay/plugin-sdk 3.1.12 → 3.1.22

package/dist/v2/react/hooks/payment-processing/usePaymentProcessors.d.ts

@@ -0,0 +1,31 @@
+import type { CardPaymentMethod, ApplePayToken, GooglePayToken, PaymentOptions, PaymentResponse, PaymentInstrumentResponse } from '../../../core/resources/payments';
+import type { PaymentsResource } from '../../../core/resources/payments';
+import type { UsePaymentOptions } from '../usePaymentQuery';
+interface UsePaymentProcessorsParams {
+    paymentsResource: PaymentsResource;
+    createCardPaymentInstrument: (cardData: CardPaymentMethod) => Promise<PaymentInstrumentResponse>;
+    createApplePayPaymentInstrument: (applePayToken: ApplePayToken) => Promise<PaymentInstrumentResponse>;
+    createGooglePayPaymentInstrument: (googlePayToken: GooglePayToken) => Promise<PaymentInstrumentResponse>;
+    createSession: any;
+    handlePaymentAction: any;
+    startPolling: any;
+    setIsLoading: (loading: boolean) => void;
+    setError: (error: string | null) => void;
+    setCurrentPaymentId: (id: string | null) => void;
+    hookOptionsRef: React.MutableRefObject<UsePaymentOptions | undefined>;
+    storeConfig: any;
+}
+export declare function usePaymentProcessors({ paymentsResource, createCardPaymentInstrument, createApplePayPaymentInstrument, createGooglePayPaymentInstrument, createSession, handlePaymentAction, startPolling, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, storeConfig, }: UsePaymentProcessorsParams): {
+    processCardPayment: (checkoutSessionId: string, cardData: CardPaymentMethod, options?: PaymentOptions) => Promise<PaymentResponse>;
+    processApplePayPayment: (checkoutSessionId: string, applePayToken: ApplePayToken, options?: PaymentOptions) => Promise<PaymentResponse>;
+    processGooglePayPayment: (checkoutSessionId: string, googlePayToken: GooglePayToken, options?: PaymentOptions) => Promise<PaymentResponse>;
+    processPaymentWithInstrument: (checkoutSessionId: string, paymentInstrumentId: string, options?: PaymentOptions) => Promise<PaymentResponse>;
+    processApmPayment: (checkoutSessionId: string, options: {
+        processorId: string;
+        paymentMethod: string;
+        initiatedBy?: "customer" | "merchant";
+        source?: "upsell" | "checkout" | "offer" | "missing_club" | "forced";
+        paymentFlowId?: string;
+    } & Pick<PaymentOptions, "onFailure" | "onPaymentFailed" | "onSuccess" | "onPaymentSuccess">) => Promise<PaymentResponse>;
+};
+export {};

package/dist/v2/react/hooks/payment-processing/usePaymentProcessors.js

@@ -0,0 +1,212 @@
+/**
+ * Hook for payment processing methods
+ */
+import { useCallback } from 'react';
+import { getAssignedPaymentFlowId } from '../../../core/funnelClient';
+export function usePaymentProcessors({ paymentsResource, createCardPaymentInstrument, createApplePayPaymentInstrument, createGooglePayPaymentInstrument, createSession, handlePaymentAction, startPolling, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, storeConfig, }) {
+    // Process payment directly with checkout session
+    const processPaymentDirect = useCallback(async (checkoutSessionId, paymentInstrumentId, threedsSessionId, options = {}) => {
+        try {
+            const paymentFlowId = options.paymentFlowId || getAssignedPaymentFlowId();
+            const response = await paymentsResource.processPaymentDirect(checkoutSessionId, paymentInstrumentId, threedsSessionId, {
+                initiatedBy: options.initiatedBy,
+                source: options.source,
+                paymentFlowId,
+                processorId: options.processorId,
+                paymentMethod: options.paymentMethod,
+            });
+            setCurrentPaymentId(response.payment?.id);
+            if (response.payment.requireAction !== 'none') {
+                await handlePaymentAction(response.payment, options);
+            }
+            else if (response.payment.status === 'succeeded') {
+                setIsLoading(false);
+                const successResponse = {
+                    ...response,
+                    order: response.order || response.payment.order,
+                };
+                if (hookOptionsRef.current?.onPaymentCompleted) {
+                    await hookOptionsRef.current.onPaymentCompleted(response.payment, {
+                        isRedirectReturn: false,
+                        order: successResponse.order,
+                        checkoutSessionId,
+                    });
+                }
+                options.onSuccess?.(successResponse);
+                options.onPaymentSuccess?.(successResponse);
+            }
+            else {
+                startPolling(response.payment?.id, {
+                    onRequireAction: (payment) => {
+                        void handlePaymentAction(payment, options);
+                    },
+                    onSuccess: async (payment) => {
+                        setIsLoading(false);
+                        const successResponse = {
+                            paymentId: payment.id,
+                            payment,
+                            order: payment.order,
+                        };
+                        if (hookOptionsRef.current?.onPaymentCompleted) {
+                            await hookOptionsRef.current.onPaymentCompleted(payment, {
+                                isRedirectReturn: false,
+                                order: successResponse.order,
+                                checkoutSessionId,
+                            });
+                        }
+                        options.onSuccess?.(successResponse);
+                        options.onPaymentSuccess?.(successResponse);
+                    },
+                    onFailure: async (errorMsg) => {
+                        setError(errorMsg);
+                        setIsLoading(false);
+                        if (hookOptionsRef.current?.onPaymentFailed) {
+                            await hookOptionsRef.current.onPaymentFailed(errorMsg, {
+                                isRedirectReturn: false,
+                            });
+                        }
+                        options.onFailure?.(errorMsg);
+                        options.onPaymentFailed?.({
+                            code: 'PAYMENT_FAILED',
+                            message: errorMsg,
+                            payment: response.payment,
+                        });
+                    },
+                });
+            }
+            return response;
+        }
+        catch (_error) {
+            const errorMsg = _error instanceof Error ? _error.message : 'Payment failed';
+            setError(errorMsg);
+            setIsLoading(false);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'PAYMENT_PROCESSING_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [paymentsResource, handlePaymentAction, startPolling, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef]);
+    // Process APM payment (Alternative Payment Methods)
+    const processApmPayment = useCallback(async (checkoutSessionId, options) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            console.log('[processApmPayment] Processing APM payment directly:', options);
+            // For APM payments, pass empty paymentInstrumentId and let backend handle it with processorId/paymentMethod
+            return await processPaymentDirect(checkoutSessionId, '', undefined, options);
+        }
+        catch (_error) {
+            setIsLoading(false);
+            const errorMsg = _error instanceof Error ? _error.message : 'APM payment failed';
+            setError(errorMsg);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'APM_PAYMENT_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [processPaymentDirect, setIsLoading, setError]);
+    // Process card payment
+    const processCardPayment = useCallback(async (checkoutSessionId, cardData, options = {}) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            // Create payment instrument and handle 3DS for card payments
+            const paymentInstrument = await createCardPaymentInstrument(cardData);
+            const shouldCreateThreedsSession = storeConfig?.computed?.threedsEnabled;
+            let threedsSessionId;
+            if (shouldCreateThreedsSession) {
+                try {
+                    const threedsSession = await createSession(paymentInstrument, {
+                        provider: options.threedsProvider || 'basis_theory',
+                    });
+                    threedsSessionId = threedsSession.id;
+                }
+                catch (_error) {
+                    // Continue without 3DS session
+                }
+            }
+            return await processPaymentDirect(checkoutSessionId, paymentInstrument.id, threedsSessionId, options);
+        }
+        catch (_error) {
+            setIsLoading(false);
+            const errorMsg = _error instanceof Error ? _error.message : 'Payment failed';
+            setError(errorMsg);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'CARD_PAYMENT_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [createCardPaymentInstrument, createSession, processPaymentDirect, storeConfig, setIsLoading, setError]);
+    // Process Apple Pay payment
+    const processApplePayPayment = useCallback(async (checkoutSessionId, applePayToken, options = {}) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const paymentInstrument = await createApplePayPaymentInstrument(applePayToken);
+            return await processPaymentDirect(checkoutSessionId, paymentInstrument.id, undefined, options);
+        }
+        catch (_error) {
+            setIsLoading(false);
+            const errorMsg = _error instanceof Error ? _error.message : 'Apple Pay payment failed';
+            setError(errorMsg);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'APPLE_PAY_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [createApplePayPaymentInstrument, processPaymentDirect, setIsLoading, setError]);
+    // Process Google Pay payment
+    const processGooglePayPayment = useCallback(async (checkoutSessionId, googlePayToken, options = {}) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const paymentInstrument = await createGooglePayPaymentInstrument(googlePayToken);
+            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);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'GOOGLE_PAY_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [createGooglePayPaymentInstrument, processPaymentDirect, setIsLoading, setError]);
+    // Process payment with existing instrument
+    const processPaymentWithInstrument = useCallback(async (checkoutSessionId, paymentInstrumentId, options = {}) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            return await processPaymentDirect(checkoutSessionId, paymentInstrumentId, undefined, options);
+        }
+        catch (_error) {
+            setIsLoading(false);
+            const errorMsg = _error instanceof Error ? _error.message : 'Payment failed';
+            setError(errorMsg);
+            options.onFailure?.(errorMsg);
+            options.onPaymentFailed?.({
+                code: 'PAYMENT_INSTRUMENT_ERROR',
+                message: errorMsg,
+            });
+            throw _error;
+        }
+    }, [processPaymentDirect, setIsLoading, setError]);
+    return {
+        processCardPayment,
+        processApplePayPayment,
+        processGooglePayPayment,
+        processPaymentWithInstrument,
+        processApmPayment,
+    };
+}

package/dist/v2/react/hooks/payment-redirect/useAirwallex3dsReturn.d.ts

@@ -0,0 +1,14 @@
+import type { PaymentsResource } from '../../../core/resources/payments';
+import type { UsePaymentOptions } from '../usePaymentQuery';
+interface UseAirwallex3dsReturnParams {
+    paymentsResource: PaymentsResource;
+    startPolling: any;
+    handlePaymentAction: any;
+    setIsLoading: (loading: boolean) => void;
+    setError: (error: string | null) => void;
+    setCurrentPaymentId: (id: string | null) => void;
+    hookOptionsRef: React.MutableRefObject<UsePaymentOptions | undefined>;
+    redirectReturnProcessedRef: React.MutableRefObject<boolean>;
+}
+export declare function useAirwallex3dsReturn({ paymentsResource, startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef, }: UseAirwallex3dsReturnParams): void;
+export {};

package/dist/v2/react/hooks/payment-redirect/useAirwallex3dsReturn.js

@@ -0,0 +1,207 @@
+/**
+ * Hook for handling Airwallex 3DS redirect returns
+ */
+import { useEffect } from 'react';
+export function useAirwallex3dsReturn({ paymentsResource, startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef, }) {
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        if (redirectReturnProcessedRef.current)
+            return;
+        const urlParams = new URLSearchParams(window.location.search);
+        const paymentIdFromUrl = urlParams.get('paymentId');
+        const paymentIntentId = urlParams.get('payment_intent_id');
+        const succeeded = urlParams.get('succeeded');
+        const processorType = urlParams.get('processorType');
+        // Check for Airwallex 3DS return
+        const hasAirwallexParams = paymentIntentId || succeeded !== null;
+        if (!hasAirwallexParams || processorType !== 'airwallex' || !paymentIdFromUrl) {
+            return;
+        }
+        console.log('✅ [usePayment] Airwallex 3DS return detected!', {
+            paymentIntentId,
+            succeeded,
+            paymentId: paymentIdFromUrl,
+        });
+        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);
+                    const retrieveStatus = retrieveResult?.retrieveResult?.status || retrieveResult?.status;
+                    if (retrieveResult?.retrieveResult?.success && retrieveStatus === 'succeeded') {
+                        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') {
+                        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 {
+                        const payment = await paymentsResource.getPaymentStatus(paymentIdFromUrl);
+                        console.log('📊 [usePayment] Payment status after retrieve:', payment);
+                        if (payment.status === 'declined' || payment.status === 'failed') {
+                            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 {
+                            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();
+    }, [paymentsResource, startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef]);
+}

package/dist/v2/react/hooks/payment-redirect/useGenericPaymentReturn.d.ts

@@ -0,0 +1,12 @@
+import type { UsePaymentOptions } from '../usePaymentQuery';
+interface UseGenericPaymentReturnParams {
+    startPolling: any;
+    handlePaymentAction: any;
+    setIsLoading: (loading: boolean) => void;
+    setError: (error: string | null) => void;
+    setCurrentPaymentId: (id: string | null) => void;
+    hookOptionsRef: React.MutableRefObject<UsePaymentOptions | undefined>;
+    redirectReturnProcessedRef: React.MutableRefObject<boolean>;
+}
+export declare function useGenericPaymentReturn({ startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef, }: UseGenericPaymentReturnParams): void;
+export {};

package/dist/v2/react/hooks/payment-redirect/useGenericPaymentReturn.js

@@ -0,0 +1,101 @@
+/**
+ * Hook for handling generic payment redirect returns
+ */
+import { useEffect } from 'react';
+export function useGenericPaymentReturn({ startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef, }) {
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        if (redirectReturnProcessedRef.current)
+            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');
+        // Skip if in retrieve mode
+        if (paymentMode === 'retrieve') {
+            console.log('⏭️ [usePayment] Skipping - retrieve mode detected (handled by usePaymentRetrieve)');
+            return;
+        }
+        // Check if returning from a payment redirect
+        if (paymentAction !== 'requireAction' || paymentActionStatus !== 'completed' || !paymentIdFromUrl) {
+            console.log('⏭️ [usePayment] No payment redirect detected - normal page load');
+            return;
+        }
+        console.log('✅ [usePayment] Payment redirect return detected! Starting auto-polling...', {
+            paymentId: paymentIdFromUrl,
+        });
+        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);
+                    }
+                }
+            },
+        });
+    }, [startPolling, handlePaymentAction, setIsLoading, setError, setCurrentPaymentId, hookOptionsRef, redirectReturnProcessedRef]);
+}

package/dist/v2/react/hooks/useCheckoutQuery.d.ts

@@ -17,8 +17,14 @@ export interface UseCheckoutQueryResult {
         checkoutToken: string;
     }>;
     refresh: () => Promise<void>;
+    replaceSessionLineItems: (lineItems: CheckoutLineItem[]) => Promise<any>;
     updateLineItems: (lineItems: CheckoutLineItem[]) => Promise<any>;
     updateLineItemsOptimistic: (lineItems: CheckoutLineItem[]) => void;
+    addLineItems: (lineItems: CheckoutLineItem[]) => Promise<any>;
+    removeLineItems: (lineItems: {
+        variantId: string;
+        quantity?: number;
+    }[]) => Promise<any>;
     setItemQuantity: (variantId: string, quantity: number, priceId?: string) => Promise<any>;
     updateCustomer: (data: {
         email: string;

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

@@ -121,6 +121,20 @@ export function useCheckoutQuery(options = {}) {
         },
     });
     // Order bump functionality removed - use useOrderBumpQuery instead
+    // Replace session line items mutation (full rewrite)
+    const replaceSessionLineItemsMutation = useMutation({
+        mutationFn: ({ lineItems }) => {
+            if (!checkout?.checkoutSession?.id) {
+                throw new Error('No checkout session available');
+            }
+            return checkoutResource.replaceSessionLineItems(checkout.checkoutSession.id, lineItems);
+        },
+        onSuccess: () => {
+            if (checkoutToken) {
+                void queryClient.invalidateQueries({ queryKey: ['checkout', checkoutToken] });
+            }
+        },
+    });
     // Line items mutation with optimistic updates
     const lineItemsMutation = useMutation({
         mutationFn: ({ lineItems }) => {
@@ -166,6 +180,34 @@ export function useCheckoutQuery(options = {}) {
             }
         },
     });
+    // Add line items mutation
+    const addLineItemsMutation = useMutation({
+        mutationFn: ({ lineItems }) => {
+            if (!checkout?.checkoutSession?.id) {
+                throw new Error('No checkout session available');
+            }
+            return checkoutResource.addLineItems(checkout.checkoutSession.id, lineItems);
+        },
+        onSuccess: () => {
+            if (checkoutToken) {
+                void queryClient.invalidateQueries({ queryKey: ['checkout', checkoutToken] });
+            }
+        },
+    });
+    // Remove line items mutation
+    const removeLineItemsMutation = useMutation({
+        mutationFn: ({ lineItems }) => {
+            if (!checkout?.checkoutSession?.id) {
+                throw new Error('No checkout session available');
+            }
+            return checkoutResource.removeLineItems(checkout.checkoutSession.id, lineItems);
+        },
+        onSuccess: () => {
+            if (checkoutToken) {
+                void queryClient.invalidateQueries({ queryKey: ['checkout', checkoutToken] });
+            }
+        },
+    });
     // Item quantity mutation
     const quantityMutation = useMutation({
         mutationFn: ({ variantId, quantity, priceId }) => {
@@ -274,8 +316,11 @@ export function useCheckoutQuery(options = {}) {
         },
         refresh,
         // Checkout operations
+        replaceSessionLineItems: (lineItems) => replaceSessionLineItemsMutation.mutateAsync({ lineItems }),
         updateLineItems: (lineItems) => lineItemsMutation.mutateAsync({ lineItems }),
         updateLineItemsOptimistic: (lineItems) => lineItemsMutation.mutate({ lineItems }),
+        addLineItems: (lineItems) => addLineItemsMutation.mutateAsync({ lineItems }),
+        removeLineItems: (lineItems) => removeLineItemsMutation.mutateAsync({ lineItems }),
         setItemQuantity: (variantId, quantity, priceId) => quantityMutation.mutateAsync({ variantId, quantity, priceId }),
         updateCustomer: (data) => customerMutation.mutateAsync(data),
         updateCustomerAndSessionInfo: (data) => customerAndSessionMutation.mutateAsync(data),