@tagadapay/plugin-sdk 3.1.24 → 4.0.0

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

@@ -1,16 +1,21 @@
 import { useMemo, useEffect, useState, useCallback } from 'react';
-import { getCountries, getStatesForCountry, ensureGeoDataLoaded, importLanguage, isLanguageRegistered, getRegisteredLanguages } from '../../../data/iso3166';
+import { getCountries, getStatesForCountry, ensureGeoDataLoaded, AVAILABLE_LANGUAGES, importLanguage, isLanguageRegistered, getRegisteredLanguages } from '../../../data/iso3166';
 /**
  * React hook for accessing ISO3166 countries and regions data.
  * Fetches slim JSON from CDN on first use, then caches in memory.
  */
 export function useISOData(language = 'en', autoImport = true, disputeSetting = 'UN') {
-    const [isLanguageLoaded, setIsLanguageLoaded] = useState(isLanguageRegistered(language));
+    // Normalize: if the caller passed an unsupported locale (e.g. 'nl'),
+    // silently fall back to English so the country dropdown still renders.
+    // The CDN only hosts languages listed in AVAILABLE_LANGUAGES; any other
+    // value would 404 and leave `isLanguageLoaded` stuck on false.
+    const effectiveLanguage = AVAILABLE_LANGUAGES.includes(language) ? language : 'en';
+    const [isLanguageLoaded, setIsLanguageLoaded] = useState(isLanguageRegistered(effectiveLanguage));
     const [registeredLanguages, setRegisteredLanguages] = useState(getRegisteredLanguages);
     // Fetch geodata from CDN (countries + regions) for the requested language
     useEffect(() => {
         let cancelled = false;
-        ensureGeoDataLoaded(language)
+        ensureGeoDataLoaded(effectiveLanguage)
             .then(() => {
             if (!cancelled) {
                 setIsLanguageLoaded(true);
@@ -19,9 +24,22 @@ export function useISOData(language = 'en', autoImport = true, disputeSetting =
         })
             .catch((err) => {
             console.error('[SDK] Failed to load geodata from CDN:', err);
+            if (cancelled)
+                return;
+            // English is prefetched on module load (iso3166.ts). If it
+            // landed, unblock the UI — getCountriesCached() falls back to 'en'.
+            if (isLanguageRegistered('en')) {
+                setIsLanguageLoaded(true);
+                return;
+            }
+            // Otherwise try one last English fetch as ultimate fallback.
+            ensureGeoDataLoaded('en')
+                .then(() => { if (!cancelled)
+                setIsLanguageLoaded(true); })
+                .catch(() => { });
         });
         return () => { cancelled = true; };
-    }, [language, autoImport]);
+    }, [effectiveLanguage, autoImport]);
     const data = useMemo(() => {
         if (!isLanguageLoaded) {
             return {
@@ -34,7 +52,7 @@ export function useISOData(language = 'en', autoImport = true, disputeSetting =
             };
         }
         try {
-            const countriesArray = getCountries(language);
+            const countriesArray = getCountries(effectiveLanguage);
             const countries = {};
             countriesArray.forEach((country) => {
                 countries[country.code] = {
@@ -46,7 +64,7 @@ export function useISOData(language = 'en', autoImport = true, disputeSetting =
             });
             const getRegions = (countryCode) => {
                 try {
-                    const states = getStatesForCountry(countryCode, language);
+                    const states = getStatesForCountry(countryCode, effectiveLanguage);
                     return states.map((state) => ({
                         iso: state.code,
                         name: state.name,
@@ -97,7 +115,7 @@ export function useISOData(language = 'en', autoImport = true, disputeSetting =
                 registeredLanguages,
             };
         }
-    }, [language, disputeSetting, isLanguageLoaded, registeredLanguages]);
+    }, [effectiveLanguage, disputeSetting, isLanguageLoaded, registeredLanguages]);
     return data;
 }
 /**

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

@@ -4,7 +4,7 @@ export interface Payment {
     subStatus: string;
     requireAction: 'none' | 'redirect' | 'redirect_to_payment' | 'error' | 'radar' | 'stripe_express_checkout';
     requireActionData?: {
-        type: 'redirect' | 'redirect_to_payment' | 'threeds_auth' | 'processor_auth' | 'error' | 'stripe_radar' | 'finix_radar' | 'radar' | 'kesspay_auth' | 'trustflow_auth' | 'mastercard_auth' | 'stripe_express_checkout';
+        type: 'redirect' | 'redirect_to_payment' | 'threeds_auth' | 'processor_auth' | 'error' | 'stripe_radar' | 'finix_radar' | 'radar' | 'kesspay_auth' | 'trustflow_auth' | 'mastercard_auth' | 'ngenius_3ds' | 'stripe_express_checkout';
         url?: string;
         processed: boolean;
         processorId?: string;

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

@@ -12,7 +12,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react';
 import { OffersResource } from '../../core/resources/offers';
 import { getGlobalApiClient } from './useApiQuery';
 export function usePreviewOffer(options) {
-    const { offerId, currency: requestedCurrency = 'USD', initialSelections = {} } = options;
+    const { offerId, currency: requestedCurrency = '', initialSelections = {} } = options;
     const queryParamsCurrency = typeof window !== 'undefined'
         ? new URLSearchParams(window.location.search).get('currency') || undefined
         : undefined;

package/dist/v2/react/providers/ExpressPaymentMethodsProvider.d.ts

@@ -1,9 +1,14 @@
 /**
  * Express Payment Methods Context Provider using v2 Architecture
  * Manages express payment methods (Apple Pay, Google Pay, PayPal, Klarna)
+ *
+ * Payment methods are resolved from:
+ *   1. paymentSetupConfig prop (from __TGD_STEP_CONFIG__ or useStepConfig)
+ *   2. API fallback (GET /api/v1/payment-methods) for legacy integrations
  */
 import React, { ReactNode } from 'react';
 import { TagadaError } from '../../core/errors';
+import type { PaymentSetupConfig } from '../../core/funnelClient';
 import { CheckoutData } from '../../core/resources/checkout';
 import { Address, PaymentMethod } from '../../core/resources/expressPaymentMethods';
 type ExpressOrderLineItem = {
@@ -56,6 +61,8 @@ interface ExpressPaymentMethodsProviderProps {
     children: ReactNode;
     customerId?: string;
     checkout?: CheckoutData;
+    /** Step-level payment config from __TGD_STEP_CONFIG__ / useStepConfig(). */
+    paymentSetupConfig?: PaymentSetupConfig;
 }
 export declare const ExpressPaymentMethodsContext: React.Context<ExpressPaymentMethodsContextType | undefined>;
 export declare const ExpressPaymentMethodsProvider: React.FC<ExpressPaymentMethodsProviderProps>;

package/dist/v2/react/providers/ExpressPaymentMethodsProvider.js

@@ -2,19 +2,74 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 /**
  * Express Payment Methods Context Provider using v2 Architecture
  * Manages express payment methods (Apple Pay, Google Pay, PayPal, Klarna)
+ *
+ * Payment methods are resolved from:
+ *   1. paymentSetupConfig prop (from __TGD_STEP_CONFIG__ or useStepConfig)
+ *   2. API fallback (GET /api/v1/payment-methods) for legacy integrations
  */
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
-import { createContext, useCallback, useMemo, useState } from 'react';
+import { createContext, useCallback, useEffect, useMemo, useState } from 'react';
 import { TagadaError, TagadaErrorCode } from '../../core/errors';
 import { ExpressPaymentMethodsResource, } from '../../core/resources/expressPaymentMethods';
 import { getGlobalApiClient } from '../hooks/useApiQuery';
 import { useShippingRatesQuery } from '../hooks/useShippingRatesQuery';
 export const ExpressPaymentMethodsContext = createContext(undefined);
-export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout, }) => {
+/**
+ * Synthesize PaymentMethod[] from paymentSetupConfig entries.
+ * Converts express_checkout:processorId entries into the shape the provider expects.
+ */
+function paymentMethodsFromSetupConfig(config) {
+    const methods = [];
+    for (const [key, entry] of Object.entries(config)) {
+        if (!entry.enabled)
+            continue;
+        // express_checkout:processorId entries → synthesize a stripe_apm-style method
+        if (key.startsWith('express_checkout:') && entry.methods) {
+            methods.push({
+                id: key,
+                type: 'stripe_apm',
+                title: entry.label || 'Express Checkout',
+                iconUrl: entry.logoUrl || '',
+                default: false,
+                settings: {
+                    publishableKey: entry.publishableKey,
+                    processors: [{
+                            processorId: entry.processorId,
+                            methods: entry.methods,
+                        }],
+                },
+            });
+            continue;
+        }
+        // Individual express methods (apple_pay, google_pay, etc.)
+        // Match by: explicit express flag, type, method, provider, or key name
+        const resolvedMethod = entry.method || entry.provider || key;
+        const isExpressMethod = entry.express
+            || entry.type === 'apple_pay' || entry.type === 'google_pay'
+            || resolvedMethod === 'apple_pay' || resolvedMethod === 'google_pay';
+        if (isExpressMethod) {
+            methods.push({
+                id: key,
+                type: entry.type === 'apple_pay' || entry.type === 'google_pay' ? entry.type : resolvedMethod,
+                title: entry.label || key,
+                iconUrl: entry.logoUrl || '',
+                default: false,
+                settings: { processorId: entry.processorId, publishableKey: entry.publishableKey },
+            });
+        }
+    }
+    return methods;
+}
+export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout, paymentSetupConfig, }) => {
     const queryClient = useQueryClient();
     const [availableExpressPaymentMethodIds, setAvailableExpressPaymentMethodIds] = useState([]);
     const [error, setError] = useState(null);
     const checkoutSessionId = checkout?.checkoutSession?.id;
+    // If paymentSetupConfig is provided AND contains at least one enabled method, derive from it.
+    // Missing, empty `{}`, or all-disabled configs fall through to the API fallback.
+    const configDerivedMethods = useMemo(() => (paymentSetupConfig && Object.values(paymentSetupConfig).some((v) => v?.enabled === true))
+        ? paymentMethodsFromSetupConfig(paymentSetupConfig)
+        : undefined, [paymentSetupConfig]);
     // Create express payment methods resource client
     const expressPaymentResource = useMemo(() => {
         try {
@@ -25,14 +80,15 @@ export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout,
                 (error instanceof Error ? error.message : 'Unknown error'));
         }
     }, []);
-    // Fetch payment methods using TanStack Query
-    const { data: paymentMethods, isLoading: isLoadingPaymentMethods } = useQuery({
+    // Only fetch from API when paymentSetupConfig is NOT provided
+    const { data: apiPaymentMethods, isLoading: isLoadingPaymentMethods } = useQuery({
         queryKey: ['payment-methods', checkoutSessionId],
         queryFn: () => expressPaymentResource.getPaymentMethods(checkoutSessionId),
-        enabled: !!checkoutSessionId,
-        staleTime: 60000, // 1 minute
+        enabled: !!checkoutSessionId && !configDerivedMethods,
+        staleTime: 60000,
         refetchOnWindowFocus: false,
     });
+    const paymentMethods = configDerivedMethods ?? apiPaymentMethods;
     // Use v2 shipping rates hook
     const { shippingRates, refetch: refetchRates } = useShippingRatesQuery({ checkout });
     // Get order summary from checkout data
@@ -161,8 +217,48 @@ export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout,
             return;
         await updateEmailMutation.mutateAsync(input.data);
     }, [customerId, updateEmailMutation]);
-    // Check if Apple Pay is available (window.ApplePaySession only exists on Apple devices)
-    const isApplePayAvailable = typeof window !== 'undefined' && typeof window.ApplePaySession !== 'undefined';
+    // Check if Apple Pay is available — load SDK on demand then re-check reactively
+    const [isApplePayAvailable, setIsApplePayAvailable] = useState(() => typeof window !== 'undefined' && typeof window.ApplePaySession !== 'undefined');
+    const [isApplePaySdkLoading, setIsApplePaySdkLoading] = useState(false);
+    const hasApplePayConfig = paymentMethods?.some((p) => p.type === 'apple_pay');
+    useEffect(() => {
+        if (isApplePayAvailable || !hasApplePayConfig)
+            return;
+        const APPLE_PAY_SDK_URL = 'https://applepay.cdn-apple.com/jsapi/1.latest/apple-pay-sdk.js';
+        const onSdkReady = () => {
+            if (typeof window.ApplePaySession !== 'undefined') {
+                setIsApplePayAvailable(true);
+            }
+            setIsApplePaySdkLoading(false);
+        };
+        // Check if script is already in DOM (may still be loading)
+        const existing = document.querySelector(`script[src="${APPLE_PAY_SDK_URL}"]`);
+        if (existing) {
+            setIsApplePaySdkLoading(true);
+            // Script may already be loaded or still loading
+            if (typeof window.ApplePaySession !== 'undefined') {
+                onSdkReady();
+            }
+            else {
+                existing.addEventListener('load', onSdkReady);
+                // Fallback timeout in case we missed the load event
+                const timer = setTimeout(onSdkReady, 2000);
+                return () => {
+                    existing.removeEventListener('load', onSdkReady);
+                    clearTimeout(timer);
+                };
+            }
+            return;
+        }
+        setIsApplePaySdkLoading(true);
+        const script = document.createElement('script');
+        script.src = APPLE_PAY_SDK_URL;
+        script.crossOrigin = 'anonymous';
+        script.async = true;
+        script.onload = onSdkReady;
+        script.onerror = () => setIsApplePaySdkLoading(false);
+        document.head.appendChild(script);
+    }, [isApplePayAvailable, hasApplePayConfig]);
     // Identify specific payment method types
     const applePayPaymentMethod = useMemo(() => {
         return isApplePayAvailable ? paymentMethods?.find((p) => p.type === 'apple_pay') : undefined;
@@ -177,7 +273,7 @@ export const ExpressPaymentMethodsProvider = ({ children, customerId, checkout,
         return paymentMethods?.find((p) => (p.type === 'stripe_apm' || p.type === 'tagadapay_apm') &&
             p.settings?.processors?.some((g) => EXPRESS_METHOD_KEYS.some((key) => g?.methods?.[key]?.enabled === true)));
     }, [paymentMethods]);
-    const loading = !paymentMethods || isLoadingPaymentMethods;
+    const loading = !paymentMethods || (!configDerivedMethods && isLoadingPaymentMethods) || isApplePaySdkLoading;
     const tagadaError = useMemo(() => error ? new TagadaError(error, { code: TagadaErrorCode.PAYMENT_FAILED }) : null, [error]);
     const contextValue = {
         paymentMethods,

package/dist/v2/react/providers/TagadaProvider.js

@@ -38,11 +38,11 @@ const InitializationLoader = () => (_jsxs("div", { style: {
                 borderTop: '1.5px solid #9ca3af',
                 borderRadius: '50%',
                 animation: 'tagada-spin 1s linear infinite',
-            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
-        @keyframes tagada-spin {
-          0% { transform: rotate(0deg); }
-          100% { transform: rotate(360deg); }
-        }
+            } }), _jsx("span", { children: "Loading..." }), _jsx("style", { children: `
+        @keyframes tagada-spin {
+          0% { transform: rotate(0deg); }
+          100% { transform: rotate(360deg); }
+        }
       ` })] }));
 const TagadaContext = createContext(null);
 export function TagadaProvider({ children, environment, customApiConfig, debugMode, localConfig, blockUntilSessionReady = false, rawPluginConfig, features, funnelId, autoInitializeFunnel = true, onNavigate, onFunnelError, debugScripts = [], }) {
@@ -315,7 +315,7 @@ export function TagadaProvider({ children, environment, customApiConfig, debugMo
                 console.log('🚀 [TagadaProvider] Auto-redirecting to:', result.url);
                 // Set pending redirect flag BEFORE navigation to prevent renders
                 setPendingRedirect(true);
-                window.location.href = result.url;
+                window.location.replace(result.url);
             }
         };
         const next = async (event, options) => {

package/dist/v2/standalone/apple-pay-service.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Apple Pay Service (Standalone) — re-export shim.
+ *
+ * The canonical implementation lives in `@tagadapay/core-js` so partner
+ * code, the studio, the native checkout, and the plugin-sdk all share a
+ * single source of truth for the native Apple Pay primitive (BasisTheory
+ * tokenization, no checkout session). This file preserves the historical
+ * import path `@tagadapay/plugin-sdk/v2/standalone` so existing consumers
+ * (studio-app, vanilla-checkout templates, …) keep working without
+ * code changes.
+ */
+export { isApplePayAvailable, startApplePaySession, type ApplePayServiceConfig, type ApplePayPaymentRequest, type ApplePayTokenResult, type ApplePayShippingContact, type ApplePayCallbacks, } from '@tagadapay/core-js';

package/dist/v2/standalone/apple-pay-service.js

@@ -0,0 +1,12 @@
+/**
+ * Apple Pay Service (Standalone) — re-export shim.
+ *
+ * The canonical implementation lives in `@tagadapay/core-js` so partner
+ * code, the studio, the native checkout, and the plugin-sdk all share a
+ * single source of truth for the native Apple Pay primitive (BasisTheory
+ * tokenization, no checkout session). This file preserves the historical
+ * import path `@tagadapay/plugin-sdk/v2/standalone` so existing consumers
+ * (studio-app, vanilla-checkout templates, …) keep working without
+ * code changes.
+ */
+export { isApplePayAvailable, startApplePaySession, } from '@tagadapay/core-js';

package/dist/v2/standalone/external-tracker.d.ts

@@ -36,7 +36,7 @@ export interface TagadaTrackerConfig {
     stepName?: string;
     /** Step type (optional — e.g., 'landing', 'offer', 'external') */
     stepType?: string;
-    /** API base URL (defaults to https://app.tagadapay.com) */
+    /** API base URL (defaults to https://api.tagada.io) */
     apiBaseUrl?: string;
     /** Enable debug logging */
     debug?: boolean;

package/dist/v2/standalone/google-pay-service.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Google Pay Service (Standalone) — re-export shim.
+ *
+ * The canonical implementation lives in `@tagadapay/core-js`. This file
+ * preserves the historical import path `@tagadapay/plugin-sdk/v2/standalone`
+ * for downstream consumers (studio-app, vanilla-checkout templates,
+ * payment-error-dashboard) — they keep working unchanged.
+ */
+export { isGooglePayAvailable, startGooglePaySession, type GooglePayServiceConfig, type GooglePayPaymentRequest, type GooglePayTokenResult, type GooglePayAddress, type GooglePayCallbacks, } from '@tagadapay/core-js';

package/dist/v2/standalone/google-pay-service.js

@@ -0,0 +1,9 @@
+/**
+ * Google Pay Service (Standalone) — re-export shim.
+ *
+ * The canonical implementation lives in `@tagadapay/core-js`. This file
+ * preserves the historical import path `@tagadapay/plugin-sdk/v2/standalone`
+ * for downstream consumers (studio-app, vanilla-checkout templates,
+ * payment-error-dashboard) — they keep working unchanged.
+ */
+export { isGooglePayAvailable, startGooglePaySession, } from '@tagadapay/core-js';

package/dist/v2/standalone/index.d.ts

@@ -25,12 +25,15 @@ export { TagadaClient, ApiClient, CheckoutResource };
 export { ShippingRatesResource } from '../core/resources/shippingRates';
 export { PaymentsResource } from '../core/resources/payments';
 export { OrdersResource } from '../core/resources/orders';
+export { OffersResource } from '../core/resources/offers';
 export { ExpressPaymentMethodsResource } from '../core/resources/expressPaymentMethods';
 export type { PaymentMethod as ExpressPaymentMethod } from '../core/resources/expressPaymentMethods';
 export type { ShippingRate, ShippingRatesResponse, ShippingRatesPreviewParams } from '../core/resources/shippingRates';
-export type { Payment, PaymentResponse, CardPaymentMethod, BasisTheoryInstance, GooglePayToken, ApplePayToken, PaymentInstrumentInput, PaymentInstrumentResponse, PaymentInstrumentCustomerResponse, } from '../core/resources/payments';
+export type { Payment, PaymentResponse, PaymentOptions, CardPaymentMethod, BasisTheoryInstance, GooglePayToken, ApplePayToken, PaymentInstrumentInput, PaymentInstrumentResponse, PaymentInstrumentCustomerResponse, } from '../core/resources/payments';
 export { StoreConfigResource } from '../core/resources/storeConfig';
 export type { StoreConfig } from '../core/resources/storeConfig';
+export { GeoResource } from '../core/resources/geo';
+export type { GeoLocationData } from '../core/resources/geo';
 export { ThreedsResource } from '../core/resources/threeds';
 export { ISODataCore } from '../core/isoData';
 export type { ISOCountry, ISORegion } from '../core/isoData';
@@ -50,6 +53,10 @@ export { getAssignedStepConfig } from '../core/funnelClient';
 export type { RuntimeStepConfig } from '../core/funnelClient';
 export { PaymentService } from './payment-service';
 export type { PaymentServiceConfig, PaymentResult, PaymentCallbacks, CardData, ApmData, } from './payment-service';
+export { isApplePayAvailable, startApplePaySession } from './apple-pay-service';
+export type { ApplePayServiceConfig, ApplePayPaymentRequest, ApplePayTokenResult, ApplePayShippingContact, ApplePayCallbacks, } from './apple-pay-service';
+export { isGooglePayAvailable, startGooglePaySession } from './google-pay-service';
+export type { GooglePayServiceConfig, GooglePayPaymentRequest, GooglePayTokenResult, GooglePayAddress, GooglePayCallbacks, } from './google-pay-service';
 /**
  * Get BasisTheory public API key based on hostname detection.
  * Delegates to the centralized isProductionBasisTheory() logic.

package/dist/v2/standalone/index.js

@@ -134,9 +134,12 @@ export { TagadaClient, ApiClient, CheckoutResource };
 export { ShippingRatesResource } from '../core/resources/shippingRates';
 export { PaymentsResource } from '../core/resources/payments';
 export { OrdersResource } from '../core/resources/orders';
+export { OffersResource } from '../core/resources/offers';
 export { ExpressPaymentMethodsResource } from '../core/resources/expressPaymentMethods';
 // Re-export Store Config (for standalone resolvers / builders)
 export { StoreConfigResource } from '../core/resources/storeConfig';
+// Re-export Geo Resource (for standalone geolocation / country detection)
+export { GeoResource } from '../core/resources/geo';
 // Re-export 3DS Resource (for standalone resolvers / builders)
 export { ThreedsResource } from '../core/resources/threeds';
 // Re-export ISO Data Core (for standalone address form / resolvers)
@@ -155,6 +158,10 @@ export { getAssignedPaymentFlowId };
 export { getAssignedStepConfig } from '../core/funnelClient';
 // Re-export Payment Service (standalone payment processing — no React)
 export { PaymentService } from './payment-service';
+// Re-export Apple Pay Service (standalone native Apple Pay — no React)
+export { isApplePayAvailable, startApplePaySession } from './apple-pay-service';
+// Re-export Google Pay Service (standalone native Google Pay — no React)
+export { isGooglePayAvailable, startGooglePaySession } from './google-pay-service';
 /**
  * Get BasisTheory public API key based on hostname detection.
  * Delegates to the centralized isProductionBasisTheory() logic.

package/dist/v2/standalone/payment-service.d.ts

@@ -51,6 +51,8 @@ export interface PaymentCallbacks {
     onSuccess?: (payment: Payment) => void;
     onFailure?: (error: string) => void;
     onRedirectReturn?: (paymentId: string) => void;
+    /** Called before a browser redirect, allows caller to await async work (e.g. funnel navigate) */
+    onBeforeRedirect?: (payment: Payment, redirectUrl: string) => Promise<void>;
 }
 export interface PollingCallbacks {
     onSuccess: (payment: Payment) => void;
@@ -101,6 +103,7 @@ export declare class PaymentService {
     private handleTrustFlowAuth;
     private handleFinixRadar;
     private handleStripeRadar;
+    private handleNgeniusThreeds;
     private handleAirwallexRadar;
     private handleMasterCardAuth;
     private loadScript;
@@ -126,9 +129,19 @@ export declare class PaymentService {
         id: string;
         sessionId: string;
     }>;
-    processCardPayment(checkoutSessionId: string, cardData: CardData): Promise<PaymentResult>;
-    processApplePayPayment(checkoutSessionId: string, applePayToken: ApplePayToken): Promise<PaymentResult>;
-    processGooglePayPayment(checkoutSessionId: string, googlePayToken: GooglePayToken): Promise<PaymentResult>;
-    processPaymentWithInstrument(checkoutSessionId: string, paymentInstrumentId: string): Promise<PaymentResult>;
-    processApmPayment(checkoutSessionId: string, apmData: ApmData): Promise<PaymentResult>;
+    processCardPayment(checkoutSessionId: string, cardData: CardData, options?: {
+        shippingRateId?: string;
+    }): Promise<PaymentResult>;
+    processApplePayPayment(checkoutSessionId: string, applePayToken: ApplePayToken, options?: {
+        shippingRateId?: string;
+    }): Promise<PaymentResult>;
+    processGooglePayPayment(checkoutSessionId: string, googlePayToken: GooglePayToken, options?: {
+        shippingRateId?: string;
+    }): Promise<PaymentResult>;
+    processPaymentWithInstrument(checkoutSessionId: string, paymentInstrumentId: string, options?: {
+        shippingRateId?: string;
+    }): Promise<PaymentResult>;
+    processApmPayment(checkoutSessionId: string, apmData: ApmData, options?: {
+        shippingRateId?: string;
+    }): Promise<PaymentResult>;
 }

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

@@ -212,6 +212,7 @@ export class PaymentService {
             paymentFlowId,
             processorId: extra?.processorId,
             paymentMethod: extra?.paymentMethod,
+            shippingRateId: extra?.shippingRateId,
         });
         console.log('[PaymentService] Payment response:', {
             paymentId: response.payment?.id,
@@ -301,6 +302,9 @@ export class PaymentService {
                 const redirectUrl = actionData.metadata?.redirect?.redirectUrl || actionData.redirectUrl || actionData.url;
                 if (redirectUrl) {
                     console.log('[PaymentService] Redirecting:', redirectUrl);
+                    if (this.callbacks.onBeforeRedirect) {
+                        await this.callbacks.onBeforeRedirect(payment, redirectUrl);
+                    }
                     window.location.href = redirectUrl;
                 }
                 else if (payment.status === 'succeeded') {
@@ -343,6 +347,9 @@ export class PaymentService {
             case 'mastercard_auth':
                 await this.handleMasterCardAuth(payment, actionData);
                 break;
+            case 'ngenius_3ds':
+                await this.handleNgeniusThreeds(payment, actionData);
+                break;
             default: {
                 console.log('[PaymentService] Unhandled action, starting polling:', actionData.type);
                 this.startPolling(payment.id, {
@@ -501,6 +508,51 @@ export class PaymentService {
         }
     }
     // --------------------------------------------------------------------------
+    // N-Genius 3DS (WebSDK)
+    // --------------------------------------------------------------------------
+    async handleNgeniusThreeds(payment, actionData) {
+        const sdk = actionData.metadata?.sdk;
+        if (!sdk?.paymentResponse || !sdk.orderReference || !sdk.paymentReference) {
+            this.callbacks.onError?.('N-Genius 3DS: missing SDK metadata');
+            this.callbacks.onProcessing?.(false);
+            return;
+        }
+        try {
+            const sdkUrl = sdk.isSandboxed
+                ? 'https://paypage.sandbox.ngenius-payments.com/hosted-sessions/sdk.js'
+                : 'https://paypage.ngenius-payments.com/hosted-sessions/sdk.js';
+            if (!document.getElementById('ngenius-websdk')) {
+                await new Promise((resolve, reject) => {
+                    const script = document.createElement('script');
+                    script.id = 'ngenius-websdk';
+                    script.src = sdkUrl;
+                    script.onload = () => resolve();
+                    script.onerror = () => reject(new Error('Failed to load N-Genius WebSDK'));
+                    document.head.appendChild(script);
+                });
+            }
+            const NI = window.NI;
+            if (!NI?.handlePaymentResponse) {
+                throw new Error('N-Genius WebSDK did not expose window.NI.handlePaymentResponse');
+            }
+            console.log('[N-Genius 3DS] Starting WebSDK challenge');
+            const outcome = await NI.handlePaymentResponse(sdk.paymentResponse, { mountId: 'ngenius-3ds-container', style: { width: '100%', height: 500 } });
+            console.log('[N-Genius 3DS] WebSDK outcome:', outcome.status);
+            const completedPayment = await this.paymentsResource.ngeniusThreedsComplete({
+                paymentId: payment.id,
+                orderReference: sdk.orderReference,
+                paymentReference: sdk.paymentReference,
+            });
+            await this.handleResumedPayment(completedPayment);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'N-Genius 3DS failed';
+            console.error('[N-Genius 3DS] Error:', error);
+            this.callbacks.onError?.(msg);
+            this.callbacks.onProcessing?.(false);
+        }
+    }
+    // --------------------------------------------------------------------------
     // Airwallex Radar
     // --------------------------------------------------------------------------
     async handleAirwallexRadar(payment, actionData) {
@@ -533,6 +585,7 @@ export class PaymentService {
                 existingScript.setAttribute('data-order-session-id', sessionId);
             }
             await this.paymentsResource.saveRadarSession({
+                paymentId: payment.id,
                 checkoutSessionId,
                 orderId,
                 airwallexRadarSessionId: sessionId,
@@ -834,7 +887,7 @@ export class PaymentService {
     // ==========================================================================
     // PAYMENT PROCESSING (all methods)
     // ==========================================================================
-    async processCardPayment(checkoutSessionId, cardData) {
+    async processCardPayment(checkoutSessionId, cardData, options) {
         this.callbacks.onProcessing?.(true);
         this.callbacks.onError?.(null);
         try {
@@ -857,7 +910,7 @@ export class PaymentService {
                     // Continue without 3DS
                 }
             }
-            return await this.processAndHandle(checkoutSessionId, instrument.id, threedsSessionId);
+            return await this.processAndHandle(checkoutSessionId, instrument.id, threedsSessionId, { shippingRateId: options?.shippingRateId });
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -866,12 +919,12 @@ export class PaymentService {
             return { success: false, error: msg };
         }
     }
-    async processApplePayPayment(checkoutSessionId, applePayToken) {
+    async processApplePayPayment(checkoutSessionId, applePayToken, options) {
         this.callbacks.onProcessing?.(true);
         this.callbacks.onError?.(null);
         try {
             const instrument = await this.createApplePayPaymentInstrument(applePayToken);
-            return await this.processAndHandle(checkoutSessionId, instrument.id);
+            return await this.processAndHandle(checkoutSessionId, instrument.id, undefined, { shippingRateId: options?.shippingRateId });
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -880,12 +933,12 @@ export class PaymentService {
             return { success: false, error: msg };
         }
     }
-    async processGooglePayPayment(checkoutSessionId, googlePayToken) {
+    async processGooglePayPayment(checkoutSessionId, googlePayToken, options) {
         this.callbacks.onProcessing?.(true);
         this.callbacks.onError?.(null);
         try {
             const instrument = await this.createGooglePayPaymentInstrument(googlePayToken);
-            return await this.processAndHandle(checkoutSessionId, instrument.id);
+            return await this.processAndHandle(checkoutSessionId, instrument.id, undefined, { shippingRateId: options?.shippingRateId });
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -894,11 +947,11 @@ export class PaymentService {
             return { success: false, error: msg };
         }
     }
-    async processPaymentWithInstrument(checkoutSessionId, paymentInstrumentId) {
+    async processPaymentWithInstrument(checkoutSessionId, paymentInstrumentId, options) {
         this.callbacks.onProcessing?.(true);
         this.callbacks.onError?.(null);
         try {
-            return await this.processAndHandle(checkoutSessionId, paymentInstrumentId);
+            return await this.processAndHandle(checkoutSessionId, paymentInstrumentId, undefined, { shippingRateId: options?.shippingRateId });
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -907,7 +960,7 @@ export class PaymentService {
             return { success: false, error: msg };
         }
     }
-    async processApmPayment(checkoutSessionId, apmData) {
+    async processApmPayment(checkoutSessionId, apmData, options) {
         this.callbacks.onProcessing?.(true);
         this.callbacks.onError?.(null);
         try {
@@ -916,6 +969,7 @@ export class PaymentService {
                 paymentMethod: apmData.paymentMethod,
                 initiatedBy: apmData.initiatedBy,
                 source: apmData.source,
+                shippingRateId: options?.shippingRateId,
             });
         }
         catch (error) {