The Checkout Widget Redirect Problem: Popups, Polling, and postMessage

typescript// widget/src/redirect-handler.ts
class RedirectHandler {
    private popup: Window | null = null;
    private pollInterval: number | null = null;

    async handleRedirect(redirectUrl: string, transactionId: string): Promise<PaymentResult> {
        return new Promise((resolve, reject) => {
            // Try to open popup
            this.popup = window.open(
                redirectUrl,
                '0fee-payment',
                'width=500,height=700,scrollbars=yes,resizable=yes'
            );

            if (this.popup && !this.popup.closed) {
                // Popup opened successfully
                this.waitForPopupResult(transactionId, resolve, reject);
            } else {
                // Popup blocked -- fallback to new tab
                this.handlePopupBlocked(redirectUrl, transactionId, resolve, reject);
            }
        });
    }

    private waitForPopupResult(
        transactionId: string,
        resolve: (result: PaymentResult) => void,
        reject: (error: Error) => void,
    ): void {
        // Listen for postMessage from the callback page
        const messageHandler = (event: MessageEvent) => {
            if (event.data?.type === '0fee-payment-result' &&
                event.data?.transactionId === transactionId) {
                window.removeEventListener('message', messageHandler);
                this.cleanup();

                if (event.data.status === 'completed') {
                    resolve(event.data);
                } else {
                    reject(new Error(event.data.error || 'Payment failed'));
                }
            }
        };

        window.addEventListener('message', messageHandler);

        // Also poll for popup closure (user closed it manually)
        this.pollInterval = window.setInterval(() => {
            if (this.popup?.closed) {
                window.removeEventListener('message', messageHandler);
                this.cleanup();
                reject(new Error('Payment window was closed'));
            }
        }, 500);

        // Timeout after 10 minutes
        setTimeout(() => {
            window.removeEventListener('message', messageHandler);
            this.cleanup();
            reject(new Error('Payment timed out'));
        }, 600_000);
    }

    private cleanup(): void {
        if (this.pollInterval) {
            clearInterval(this.pollInterval);
            this.pollInterval = null;
        }
        if (this.popup && !this.popup.closed) {
            this.popup.close();
        }
        this.popup = null;
    }
}

html<!-- frontend/src/routes/widget-callback/+page.svelte -->
<!-- This is the page that Stripe/PayPal redirects to after payment -->
<script>
    import { onMount } from 'svelte';
    import { page } from '$app/stores';

    let status = 'processing';
    let message = 'Completing your payment...';

    onMount(async () => {
        const params = new URLSearchParams($page.url.search);
        const transactionId = params.get('transaction_id');
        const paymentStatus = params.get('status');

        // Verify payment status with backend
        const response = await fetch(
            `${API_URL}/transactions/${transactionId}/status`
        );
        const result = await response.json();

        // Send result to parent window (the merchant's page with the widget)
        if (window.opener) {
            window.opener.postMessage({
                type: '0fee-payment-result',
                transactionId: transactionId,
                status: result.status,
                amount: result.source_amount,
                currency: result.source_currency,
            }, '*');

            status = 'complete';
            message = 'Payment complete. This window will close automatically.';

            // Auto-close after 2 seconds
            setTimeout(() => window.close(), 2000);
        } else {
            // No opener (direct navigation) -- show result and redirect
            status = result.status;
            message = result.status === 'completed'
                ? 'Payment successful! You can close this tab.'
                : 'Payment was not completed.';
        }
    });
</script>

<div class="callback-page">
    <div class="status-card">
        {#if status === 'processing'}
            <div class="spinner"></div>
        {:else if status === 'completed'}
            <div class="checkmark">&#10003;</div>
        {:else}
            <div class="cross">&#10007;</div>
        {/if}
        <p>{message}</p>
    </div>
</div>

typescript// widget/src/redirect-handler.ts (continued)
private handlePopupBlocked(
    redirectUrl: string,
    transactionId: string,
    resolve: (result: PaymentResult) => void,
    reject: (error: Error) => void,
): void {
    // Update widget state to show instructions
    this.updateWidgetState('redirect_blocked');

    // Open in new tab (less likely to be blocked)
    window.open(redirectUrl, '_blank');

    // Poll backend for status every 2 seconds
    this.pollInterval = window.setInterval(async () => {
        try {
            const response = await fetch(
                `${API_URL}/transactions/${transactionId}/status`
            );
            const result = await response.json();

            if (result.status === 'completed') {
                this.cleanup();
                resolve(result);
            } else if (result.status === 'failed' || result.status === 'expired') {
                this.cleanup();
                reject(new Error(`Payment ${result.status}`));
            }
            // 'pending' status: keep polling
        } catch (error) {
            // Network error: keep polling (might be temporary)
            console.warn('Status poll failed, retrying...', error);
        }
    }, 2000);

    // Timeout after 10 minutes
    setTimeout(() => {
        this.cleanup();
        reject(new Error('Payment timed out'));
    }, 600_000);
}

typescript// widget/src/states.ts
type WidgetState =
    | 'idle'              // Initial state, showing payment form
    | 'processing'        // Sending request to backend
    | 'redirect_waiting'  // Popup opened, waiting for result
    | 'redirect_blocked'  // Popup blocked, polling for result
    | 'completed'         // Payment successful
    | 'failed'            // Payment failed
    | 'expired';          // Payment timed out

typescript// Widget-side validation
const messageHandler = (event: MessageEvent) => {
    // Validate message structure
    if (event.data?.type !== '0fee-payment-result') return;

    // Validate transaction ID matches what we're waiting for
    if (event.data?.transactionId !== pendingTransactionId) return;

    // IMPORTANT: Do NOT trust the status from postMessage alone
    // Verify with backend before showing success
    verifyWithBackend(event.data.transactionId).then(result => {
        if (result.status === 'completed') {
            resolve(result);
        }
    });
};