@flopay/react 0.3.5 → 0.3.12

package/dist/index.cjs

@@ -118,7 +118,7 @@ function FloPayProvider({
 // src/flopay-checkout.tsx
 var import_react7 = __toESM(require("react"), 1);
 var import_js = require("@flopay/js");
-var import_shared5 = require("@flopay/shared");
+var import_shared6 = require("@flopay/shared");
 
 // src/card-button-content.tsx
 var import_react3 = require("react");
@@ -162,10 +162,29 @@ function DefaultCardButtonContent() {
     )
   ] });
 }
+function DefaultBackButtonContent() {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: "Go back" });
+}
+function DefaultTitleContent() {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: "Secure card checkout" });
+}
+function isEmptySlotContent(content) {
+  return content !== void 0 && (content === "" || content === null || content === false);
+}
 function CardButtonContentSlot({
   content
 }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: content ?? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(DefaultCardButtonContent, {}) });
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: content === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(DefaultCardButtonContent, {}) : content });
+}
+function BackButtonContentSlot({
+  content
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: content === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(DefaultBackButtonContent, {}) : content });
+}
+function TitleContentSlot({
+  content
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: content === void 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(DefaultTitleContent, {}) : content });
 }
 
 // src/elements.tsx
@@ -230,7 +249,7 @@ var AddressElement = createElementComponent("address", "AddressElement");
 
 // src/split-card-form.tsx
 var import_react_stripe_js = require("@stripe/react-stripe-js");
-var import_shared3 = require("@flopay/shared");
+var import_shared4 = require("@flopay/shared");
 var import_react6 = require("react");
 
 // src/hooks.ts
@@ -252,8 +271,116 @@ function useBillingApiUrl() {
   return ctx.billingApiUrl || (0, import_shared2.resolveBillingApiUrl)();
 }
 
+// src/checkout-utils.ts
+var import_shared3 = require("@flopay/shared");
+function mergeInlineSessionPatches(base, patch) {
+  if (!patch) return base;
+  if (!base) return patch;
+  return {
+    account: { ...base.account ?? {}, ...patch.account ?? {} },
+    couponCodes: patch.couponCodes ?? base.couponCodes,
+    tagsData: {
+      ...base.tagsData ?? {},
+      ...patch.tagsData ?? {}
+    },
+    utmMetadata: patch.utmMetadata ?? base.utmMetadata
+  };
+}
+function mergeInlineSessionPatch(params, patch) {
+  if (!patch) return params;
+  return {
+    ...params,
+    account: {
+      ...params.account,
+      ...patch.account ?? {}
+    },
+    couponCodes: patch.couponCodes ?? params.couponCodes,
+    tagsData: {
+      ...params.tagsData ?? {},
+      ...patch.tagsData ?? {}
+    },
+    utmMetadata: patch.utmMetadata ?? params.utmMetadata
+  };
+}
+function buildSyntheticSession(params, checkoutModeOverride) {
+  const totalAmount = [
+    ...(params.items ?? []).map((item) => item.overrideAmount ?? item.totalAmount ?? 0),
+    ...(params.subscriptions ?? []).map((subscription) => subscription.overrideAmount ?? subscription.totalAmount ?? 0)
+  ].reduce((sum, value) => sum + value, 0);
+  const currency = params.items?.[0]?.currency ?? params.subscriptions?.[0]?.currency ?? "USD";
+  return {
+    id: "",
+    clientSecret: "",
+    mode: "payment",
+    amount: Math.round(totalAmount * 100),
+    currency,
+    status: "open",
+    customer: {
+      id: params.account.userId,
+      email: params.account.email ?? "",
+      firstName: params.account.firstName,
+      lastName: params.account.lastName,
+      gender: params.account.gender ?? void 0,
+      city: params.account.city ?? void 0,
+      state: params.account.state ?? void 0,
+      country: params.account.country ?? void 0,
+      zip: params.account.zip ?? void 0
+    },
+    successUrl: params.successUrl,
+    cancelUrl: params.cancelUrl,
+    checkoutMode: params.checkoutMode ?? checkoutModeOverride ?? "full",
+    items: (params.items ?? []).map((item, idx) => ({
+      uuid: `synthetic-item-${idx}`,
+      checkoutSessionId: "",
+      providerItemId: item.providerItemId,
+      providerItemName: item.providerItemName ?? item.providerItemId,
+      quantity: item.quantity ?? 1,
+      totalAmount: item.totalAmount,
+      overrideAmount: item.overrideAmount ?? null,
+      currency: item.currency ?? currency
+    })),
+    subscriptions: (params.subscriptions ?? []).map((subscription, idx) => ({
+      uuid: `synthetic-sub-${idx}`,
+      checkoutSessionId: "",
+      providerPlanId: subscription.providerPlanId,
+      providerPlanName: subscription.providerPlanName ?? subscription.providerPlanId,
+      quantity: subscription.quantity ?? 1,
+      totalAmount: subscription.totalAmount,
+      overrideAmount: subscription.overrideAmount ?? null,
+      currency: subscription.currency ?? currency
+    }))
+  };
+}
+function ensureInlineSessionReady(params) {
+  if (!params.account.email?.trim()) {
+    throw new import_shared3.FloPayError(
+      "Email is required before continuing with card checkout.",
+      "validation_error",
+      { param: "createSession.account.email" }
+    );
+  }
+}
+function mergeAccountPatch(base, patch) {
+  if (!patch) return base;
+  return {
+    ...base,
+    ...patch
+  };
+}
+function buildDeclineEvent(method, input, overrides) {
+  const message = typeof input === "string" ? input : input.message;
+  const code = typeof input === "string" ? overrides?.code : overrides?.code ?? input.code;
+  const declineCode = typeof input === "string" ? overrides?.declineCode : overrides?.declineCode ?? input.declineCode;
+  return {
+    method,
+    message,
+    ...code ? { code } : {},
+    ...declineCode ? { declineCode } : {}
+  };
+}
+
 // src/split-card-form.tsx
-var import_shared4 = require("@flopay/shared");
+var import_shared5 = require("@flopay/shared");
 var import_jsx_runtime4 = require("react/jsx-runtime");
 var WALLET_RESUME_KEY = "flopay_wallet_resume";
 var FLOPAY_KEYFRAMES = `
@@ -391,7 +518,8 @@ function PayPalButtonInner({
   onTokenizedBody,
   onErrorChange,
   isProcessing = false,
-  onButtonClick
+  onButtonClick,
+  onDecline
 }) {
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
@@ -411,7 +539,9 @@ function PayPalButtonInner({
       try {
         setSubmitting(true);
         if (redirectStatus === "failed") {
-          onErrorChange?.("PayPal payment was declined. Please try again.");
+          const message = "PayPal payment was declined. Please try again.";
+          onErrorChange?.(message);
+          onDecline?.(buildDeclineEvent("paypal", message));
           return;
         }
         const { paymentIntent, error } = await stripe.retrievePaymentIntent(clientSecret);
@@ -433,7 +563,9 @@ function PayPalButtonInner({
           url.searchParams.delete("redirect_status");
           window.history.replaceState({}, "", url.toString());
         } else {
-          onErrorChange?.("PayPal payment was not completed. Please try again.");
+          const message = "PayPal payment was not completed. Please try again.";
+          onErrorChange?.(message);
+          onDecline?.(buildDeclineEvent("paypal", message));
         }
       } catch (err) {
         onErrorChange?.(err instanceof Error ? err.message : "Failed to complete PayPal payment.");
@@ -441,7 +573,7 @@ function PayPalButtonInner({
         setSubmitting(false);
       }
     })();
-  }, [stripe, onTokenizedBody, onErrorChange]);
+  }, [stripe, onTokenizedBody, onErrorChange, onDecline]);
   const handlePayPalConfirm = (0, import_react6.useCallback)(async (_event) => {
     if (!stripe || !elements) return;
     onButtonClick?.("paypal");
@@ -482,7 +614,11 @@ function PayPalButtonInner({
         redirect: "if_required"
       });
       if (confirmError) {
-        onErrorChange?.(confirmError.message ?? "PayPal payment failed.");
+        const message = confirmError.message ?? "PayPal payment failed.";
+        onErrorChange?.(message);
+        onDecline?.(buildDeclineEvent("paypal", message, {
+          code: confirmError.code
+        }));
         return;
       }
       const confirmedPmId = typeof paymentIntent?.payment_method === "string" ? paymentIntent.payment_method : paymentIntent?.payment_method?.id;
@@ -497,7 +633,7 @@ function PayPalButtonInner({
     } finally {
       setSubmitting(false);
     }
-  }, [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange]);
+  }, [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]);
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       import_react_stripe_js.ExpressCheckoutElement,
@@ -506,6 +642,9 @@ function PayPalButtonInner({
         onLoadError: () => {
         },
         onConfirm: handlePayPalConfirm,
+        onCancel: () => {
+          onDecline?.(buildDeclineEvent("paypal", "PayPal checkout was cancelled."));
+        },
         options: {
           buttonType: { paypal: "paypal" },
           paymentMethods: {
@@ -528,13 +667,15 @@ function WalletButtonInner({
   showGooglePay = true,
   onTokenizedBody,
   onErrorChange,
-  onButtonClick
+  onButtonClick,
+  onDecline
 }) {
   const stripe = (0, import_react_stripe_js.useStripe)();
   const elements = (0, import_react_stripe_js.useElements)();
   const [ready, setReady] = (0, import_react6.useState)(false);
   const [submitting, setSubmitting] = (0, import_react6.useState)(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
+  const lastWalletMethodRef = (0, import_react6.useRef)("card");
   const handleWalletConfirm = (0, import_react6.useCallback)(
     async (_event) => {
       if (!stripe || !elements) return;
@@ -575,7 +716,12 @@ function WalletButtonInner({
           { payment_method: paymentMethod.id }
         );
         if (confirmError) {
-          onErrorChange?.(confirmError.message ?? "Wallet payment failed.");
+          const method = walletType === "apple_pay" ? "apple_pay" : "google_pay";
+          const message = confirmError.message ?? "Wallet payment failed.";
+          onErrorChange?.(message);
+          onDecline?.(buildDeclineEvent(method, message, {
+            code: confirmError.code
+          }));
           return;
         }
         onTokenizedBody({
@@ -589,7 +735,7 @@ function WalletButtonInner({
         setSubmitting(false);
       }
     },
-    [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange]
+    [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(import_jsx_runtime4.Fragment, { children: [
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
@@ -598,7 +744,14 @@ function WalletButtonInner({
         onReady: () => setReady(true),
         onLoadError: () => {
         },
+        onClick: (event) => {
+          lastWalletMethodRef.current = event.expressPaymentType === "apple_pay" ? "apple_pay" : "google_pay";
+          event.resolve();
+        },
         onConfirm: handleWalletConfirm,
+        onCancel: () => {
+          onDecline?.(buildDeclineEvent(lastWalletMethodRef.current, "Wallet checkout was cancelled."));
+        },
         options: {
           buttonType: { applePay: "plain", googlePay: "plain" },
           paymentMethods: {
@@ -623,6 +776,7 @@ function SplitCardFormInner({
   userId,
   onComplete,
   onError,
+  onDecline,
   onTokenizedBody,
   firstName,
   lastName,
@@ -642,7 +796,10 @@ function SplitCardFormInner({
   buttonsTheme,
   buttonsStyles: buttonsStylesOverride,
   cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent,
   onButtonClick,
+  onBeforeButtonClick,
   enableAVS = false,
   avsLayout: avsLayoutProp = "row",
   country: countryProp,
@@ -651,6 +808,7 @@ function SplitCardFormInner({
   onZipChange,
   totalAmount = 0,
   currency = "usd",
+  initialCardOpen = false,
   innerRef
 }) {
   const flopay = useFloPay();
@@ -661,9 +819,10 @@ function SplitCardFormInner({
   const [is3DSActive, setIs3DSActive] = (0, import_react6.useState)(false);
   const [selectedCountry, setSelectedCountry] = (0, import_react6.useState)(countryProp ?? "US");
   const [zipCode, setZipCode] = (0, import_react6.useState)(zipProp ?? "");
+  const [accountPatch, setAccountPatch] = (0, import_react6.useState)({});
   const zipCodeRef = (0, import_react6.useRef)(zipProp ?? "");
   const selectedCountryRef = (0, import_react6.useRef)(countryProp ?? "US");
-  const [viewState, setViewState] = (0, import_react6.useState)("buttons");
+  const [viewState, setViewState] = (0, import_react6.useState)(initialCardOpen ? "card" : "buttons");
   const showCardForm = viewState === "expanding" || viewState === "card";
   const TRANSITION_MS = 280;
   const expandToCard = (0, import_react6.useCallback)(() => {
@@ -674,6 +833,11 @@ function SplitCardFormInner({
     setViewState("collapsing");
     setTimeout(() => setViewState("buttons"), TRANSITION_MS);
   }, []);
+  (0, import_react6.useEffect)(() => {
+    if (layout === "buttons" && initialCardOpen) {
+      setViewState("card");
+    }
+  }, [layout, initialCardOpen]);
   const [fullName, setFullName] = (0, import_react6.useState)("");
   const [formReady, setFormReady] = (0, import_react6.useState)(false);
   const [overlayStatus, setOverlayStatus] = (0, import_react6.useState)(null);
@@ -681,7 +845,7 @@ function SplitCardFormInner({
   const resolvedBillingApiUrl = billingApiUrl || contextBillingUrl;
   const displayError = externalError ?? error;
   const bStyles = (0, import_react6.useMemo)(() => {
-    const base = (0, import_shared3.resolveButtonsLayoutTheme)(buttonsTheme);
+    const base = (0, import_shared4.resolveButtonsLayoutTheme)(buttonsTheme);
     if (!buttonsStylesOverride) return base;
     return {
       ...base,
@@ -697,6 +861,14 @@ function SplitCardFormInner({
   const isSubmitting = externalProcessing ?? processing;
   const isSelfContained = !onTokenizedBody;
   const baseUrl = resolvedBillingApiUrl.replace(/\/+$/, "");
+  const resolvedAccount = (0, import_react6.useMemo)(() => mergeAccountPatch({
+    userId,
+    email,
+    firstName,
+    lastName,
+    country: countryProp,
+    zip: zipProp
+  }, accountPatch), [userId, email, firstName, lastName, countryProp, zipProp, accountPatch]);
   const stripeInstance = (0, import_react6.useMemo)(() => {
     if (!flopay) return null;
     return flopay.getRawProvider();
@@ -722,6 +894,12 @@ function SplitCardFormInner({
     },
     [onErrorChange]
   );
+  const emitDecline = (0, import_react6.useCallback)(
+    (method, input, overrides) => {
+      onDecline?.(buildDeclineEvent(method, input, overrides));
+    },
+    [onDecline]
+  );
   const showWallets = showApplePay || showGooglePay;
   const handleNameChange = (0, import_react6.useCallback)((value) => {
     setFullName(value);
@@ -729,6 +907,30 @@ function SplitCardFormInner({
     onFirstNameChange?.(parts[0] ?? "");
     onLastNameChange?.(parts.length > 1 ? parts.slice(1).join(" ") : "");
   }, [onFirstNameChange, onLastNameChange]);
+  const runBeforeCardButtonClick = (0, import_react6.useCallback)(async () => {
+    if (!onBeforeButtonClick) return true;
+    try {
+      const result = await onBeforeButtonClick({
+        method: "card",
+        sessionId: sessionId || void 0
+      });
+      if (result === false) {
+        return false;
+      }
+      if (result?.account) {
+        setAccountPatch((prev) => ({ ...prev ?? {}, ...result.account }));
+      }
+      return true;
+    } catch (err) {
+      const floPayErr = err instanceof import_shared5.FloPayError ? err : new import_shared5.FloPayError(
+        err instanceof Error ? err.message : "Card before-click hook failed.",
+        "validation_error"
+      );
+      updateError(floPayErr.message);
+      onError?.(floPayErr);
+      return false;
+    }
+  }, [onBeforeButtonClick, sessionId, updateError, onError]);
   const processPaymentInternal = (0, import_react6.useCallback)(
     async (tokenizedBody) => {
       if (processingRef.current) return;
@@ -741,16 +943,16 @@ function SplitCardFormInner({
           method: "POST",
           headers: {
             "Content-Type": "application/json",
-            "x-user-id": userId ?? ""
+            "x-user-id": resolvedAccount.userId ?? ""
           },
           body: JSON.stringify({
             sessionId,
             tokenizedData: tokenizedBody,
             accountData: {
-              userId: userId ?? "",
-              email: email ?? "",
-              firstName: firstName ?? fullName.trim().split(/\s+/)[0] ?? "",
-              lastName: lastName ?? fullName.trim().split(/\s+/).slice(1).join(" ") ?? "",
+              userId: resolvedAccount.userId ?? "",
+              email: resolvedAccount.email ?? "",
+              firstName: resolvedAccount.firstName ?? fullName.trim().split(/\s+/)[0] ?? "",
+              lastName: resolvedAccount.lastName ?? fullName.trim().split(/\s+/).slice(1).join(" ") ?? "",
               ...enableAVS ? { zip: zipCodeRef.current, country: selectedCountryRef.current } : {}
             },
             chv
@@ -783,6 +985,7 @@ function SplitCardFormInner({
               setOverlayStatus("error");
               updateError(result.error.message);
               onError?.(result.error);
+              emitDecline("card", result.error);
               return;
             }
             if (result.status === "succeeded" || result.status === "processing") {
@@ -825,7 +1028,11 @@ function SplitCardFormInner({
             });
             if (confirmError) {
               setOverlayStatus("error");
-              updateError(confirmError.message ?? "PayPal payment failed.");
+              const message2 = confirmError.message ?? "PayPal payment failed.";
+              updateError(message2);
+              emitDecline("paypal", message2, {
+                code: confirmError.code
+              });
             }
           } catch (err) {
             setOverlayStatus("error");
@@ -834,7 +1041,12 @@ function SplitCardFormInner({
           return;
         }
         setOverlayStatus("error");
-        updateError(json?.message ?? "Payment failed. Please try again.");
+        const message = json?.message ?? "Payment failed. Please try again.";
+        updateError(message);
+        emitDecline(tokenizedBody.isPaypal ? "paypal" : "card", message, {
+          code: json?.code ?? json?.gatewayErrorCode,
+          declineCode: json?.declineCode ?? json?.gatewayDeclineReason
+        });
         await new Promise((r) => setTimeout(r, 1500));
       } catch (err) {
         setOverlayStatus("error");
@@ -846,7 +1058,7 @@ function SplitCardFormInner({
         processingRef.current = false;
       }
     },
-    [baseUrl, sessionId, userId, email, firstName, lastName, fullName, chv, flopay, onComplete, onError, updateError]
+    [baseUrl, sessionId, resolvedAccount, fullName, chv, flopay, onComplete, onError, updateError, emitDecline]
   );
   const dispatchTokenizedBody = (0, import_react6.useCallback)(
     (tokenizedBody) => {
@@ -870,6 +1082,7 @@ function SplitCardFormInner({
         if (result.error) {
           updateError(result.error.message);
           onError?.(result.error);
+          emitDecline("card", result.error);
         } else if (result.status === "succeeded" || result.status === "processing") {
           dispatchTokenizedBody({
             id: result.paymentIntentId,
@@ -883,7 +1096,7 @@ function SplitCardFormInner({
         setIs3DSActive(false);
       }
     }
-  }), [flopay, dispatchTokenizedBody, onError, updateError]);
+  }), [flopay, dispatchTokenizedBody, onError, updateError, emitDecline]);
   (0, import_react6.useEffect)(() => {
     if (typeof window === "undefined") return;
     const stored = localStorage.getItem(WALLET_RESUME_KEY);
@@ -906,14 +1119,16 @@ function SplitCardFormInner({
     async (e) => {
       e.preventDefault();
       if (!flopay || !elements || isSubmitting || processingRef.current) return;
-      onButtonClick?.("card");
+      if (layout !== "buttons") {
+        onButtonClick?.("card");
+      }
       setProcessing(true);
       setOverlayStatus("processing");
       updateError(null);
       let handedOff = false;
       try {
         if (enableAVS && !zipCodeRef.current.trim()) {
-          updateError((0, import_shared3.getPostalCodeLabel)(selectedCountryRef.current) + " is required");
+          updateError((0, import_shared4.getPostalCodeLabel)(selectedCountryRef.current) + " is required");
           return;
         }
         const submitResult = await flopay.submitElements();
@@ -934,23 +1149,23 @@ function SplitCardFormInner({
           updateError(pmResult.error?.message ?? "Failed to create payment method.");
           return;
         }
-        if (!sessionId || !email) {
-          throw new import_shared4.FloPayError("Missing sessionId or email", "validation_error");
+        if (!sessionId || !resolvedAccount.email) {
+          throw new import_shared5.FloPayError("Missing sessionId or email", "validation_error");
         }
         const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({
             sessionId,
-            email,
+            email: resolvedAccount.email,
             paymentMethodType: pmResult.paymentMethodId,
             isPaypal: false
           })
         });
-        if (!intentResponse.ok) throw new import_shared4.FloPayError("Failed to create payment intent", "api_error");
+        if (!intentResponse.ok) throw new import_shared5.FloPayError("Failed to create payment intent", "api_error");
         const intentJson = await intentResponse.json();
         const intentClientSecret = intentJson.data?.id;
-        if (!intentClientSecret) throw new import_shared4.FloPayError("No client_secret in payment intent response", "api_error");
+        if (!intentClientSecret) throw new import_shared5.FloPayError("No client_secret in payment intent response", "api_error");
         const confirmResult = await flopay.confirmCardPayment({
           clientSecret: intentClientSecret,
           paymentMethodId: pmResult.paymentMethodId
@@ -958,6 +1173,8 @@ function SplitCardFormInner({
         if (confirmResult.error) {
           setOverlayStatus("error");
           updateError(confirmResult.error.message);
+          onError?.(confirmResult.error);
+          emitDecline("card", confirmResult.error);
           await new Promise((r) => setTimeout(r, 1500));
           return;
         }
@@ -978,7 +1195,7 @@ function SplitCardFormInner({
         }
       }
     },
-    [flopay, elements, isSubmitting, sessionId, email, baseUrl, isSelfContained, dispatchTokenizedBody, onError, updateError]
+    [flopay, elements, isSubmitting, sessionId, resolvedAccount.email, baseUrl, isSelfContained, dispatchTokenizedBody, onButtonClick, onError, updateError, emitDecline, layout]
   );
   const isReady = flopay !== null && elements !== null;
   if (!isReady) {
@@ -988,6 +1205,8 @@ function SplitCardFormInner({
   const resolvedBorder = isButtons ? bStyles.cardInputBorder ?? "#e5e7eb" : "#A4A4FF";
   const cardBg = isButtons ? bStyles.cardFormContainer?.backgroundColor ?? "white" : "#EDEDFF";
   const cardInputBg = isButtons ? bStyles.cardInputBackground ?? "white" : "white";
+  const hideBackButtonLabel = isEmptySlotContent(cardBackButtonContent);
+  const hideTitle = isEmptySlotContent(cardTitleContent);
   const stripeElementStyle = isButtons && (bStyles.cardInputColor || bStyles.cardInputPlaceholderColor || bStyles.cardInputFontSize) ? {
     style: {
       base: {
@@ -1018,7 +1237,7 @@ function SplitCardFormInner({
           style: {
             display: "inline-flex",
             alignItems: "center",
-            gap: "0.5rem",
+            gap: hideBackButtonLabel ? 0 : "0.5rem",
             background: "none",
             border: "none",
             cursor: "pointer",
@@ -1043,11 +1262,11 @@ function SplitCardFormInner({
               transition: "background-color 0.15s",
               ...bStyles.backButtonIcon
             }, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("path", { d: "M15 18l-6-6 6-6" }) }) }),
-            "Go back"
+            /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(BackButtonContentSlot, { content: cardBackButtonContent })
           ]
         }
       ),
-      /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: {
+      hideTitle ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { flex: 1 } }) : /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: {
         flex: 1,
         textAlign: "center",
         fontWeight: 600,
@@ -1055,9 +1274,9 @@ function SplitCardFormInner({
         color: "#262833",
         paddingRight: 80,
         ...bStyles.title
-      }, children: "Secure card checkout" })
+      }, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(TitleContentSlot, { content: cardTitleContent }) })
     ] }),
-    !isButtons && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { textAlign: "center", fontWeight: 600, fontSize: "1.1rem", padding: "0.5rem 0", color: "#262833" }, children: "Secure card checkout" }),
+    !isButtons && !hideTitle && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { textAlign: "center", fontWeight: 600, fontSize: "1.1rem", padding: "0.5rem 0", color: "#262833" }, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(TitleContentSlot, { content: cardTitleContent }) }),
     /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: {
       backgroundColor: cardInputBg,
       border: `1px solid ${resolvedBorder}`,
@@ -1147,7 +1366,7 @@ function SplitCardFormInner({
             cursor: "pointer",
             ...isButtons && bStyles.nameInput ? bStyles.nameInput : {}
           },
-          children: import_shared3.COUNTRY_OPTIONS.map((c) => /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("option", { value: c.code, children: [
+          children: import_shared4.COUNTRY_OPTIONS.map((c) => /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("option", { value: c.code, children: [
             c.flag,
             " ",
             c.name
@@ -1164,7 +1383,7 @@ function SplitCardFormInner({
       }, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
         "input",
         {
-          placeholder: (0, import_shared3.getPostalCodeLabel)(selectedCountry),
+          placeholder: (0, import_shared4.getPostalCodeLabel)(selectedCountry),
           autoComplete: "postal-code",
           value: zipCode,
           onChange: (e) => {
@@ -1261,32 +1480,36 @@ function SplitCardFormInner({
             PayPalButtonInner,
             {
               sessionId,
-              email,
+              email: resolvedAccount.email,
               billingApiUrl: resolvedBillingApiUrl,
               onTokenizedBody: dispatchTokenizedBody,
               onErrorChange: updateError,
               isProcessing: isSubmitting,
-              onButtonClick
+              onButtonClick,
+              onDecline
             }
           ) }) : showPayPal ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { height: 44, borderRadius: 8, background: "#e5e7eb", animation: "flopay-pulse 1.5s ease-in-out infinite" } }) : null,
           showWallets && stripeInstance ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react_stripe_js.Elements, { stripe: stripeInstance, options: walletOptions, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
             WalletButtonInner,
             {
               sessionId,
-              email,
+              email: resolvedAccount.email,
               billingApiUrl: resolvedBillingApiUrl,
               showApplePay,
               showGooglePay,
               onTokenizedBody: dispatchTokenizedBody,
               onErrorChange: updateError,
-              onButtonClick
+              onButtonClick,
+              onDecline
             }
           ) }) : showWallets ? /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { style: { height: 44, borderRadius: 8, background: "#e5e7eb", animation: "flopay-pulse 1.5s ease-in-out infinite" } }) : null,
           /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
             "button",
             {
               type: "button",
-              onClick: () => {
+              onClick: async () => {
+                const shouldContinue = await runBeforeCardButtonClick();
+                if (!shouldContinue) return;
                 onButtonClick?.("card");
                 expandToCard();
               },
@@ -1351,23 +1574,25 @@ function SplitCardFormInner({
       WalletButtonInner,
       {
         sessionId,
-        email,
+        email: resolvedAccount.email,
         billingApiUrl: resolvedBillingApiUrl,
         showApplePay,
         showGooglePay,
         onTokenizedBody: dispatchTokenizedBody,
-        onErrorChange: updateError
+        onErrorChange: updateError,
+        onDecline
       }
     ) }),
     showPayPal && stripeInstance && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(import_react_stripe_js.Elements, { stripe: stripeInstance, options: paypalOptions, children: /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
       PayPalButtonInner,
       {
         sessionId,
-        email,
+        email: resolvedAccount.email,
         billingApiUrl: resolvedBillingApiUrl,
         onTokenizedBody: dispatchTokenizedBody,
         onErrorChange: updateError,
-        isProcessing: isSubmitting
+        isProcessing: isSubmitting,
+        onDecline
       }
     ) }),
     (showWallets && stripeInstance || showPayPal && stripeInstance) && /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)("div", { style: {
@@ -1399,6 +1624,7 @@ function FloPayCheckout({
   error: errorNode,
   onComplete,
   onError,
+  onDecline,
   showPayPal = true,
   showApplePay = true,
   showGooglePay = true,
@@ -1406,7 +1632,10 @@ function FloPayCheckout({
   buttonsTheme,
   buttonsStyles,
   cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent,
   onButtonClick,
+  onBeforeButtonClick,
   enableAVS,
   avsLayout,
   submitLabel,
@@ -1417,7 +1646,7 @@ function FloPayCheckout({
   renderConfirmButton,
   onSessionCompleted
 }) {
-  const resolvedBillingUrl = (0, import_shared5.resolveBillingApiUrl)(billingApiUrl);
+  const resolvedBillingUrl = (0, import_shared6.resolveBillingApiUrl)(billingApiUrl);
   const [unified, setUnified] = (0, import_react7.useState)(null);
   const [flopay, setFloPay] = (0, import_react7.useState)(null);
   const flopayRef = (0, import_react7.useRef)(null);
@@ -1428,13 +1657,28 @@ function FloPayCheckout({
   const [currentMode, setCurrentMode] = (0, import_react7.useState)("full");
   const [confirmProcessing, setConfirmProcessing] = (0, import_react7.useState)(false);
   const [modeError, setModeError] = (0, import_react7.useState)(null);
+  const [createSessionPatch, setCreateSessionPatch] = (0, import_react7.useState)(void 0);
+  const [cardBootstrapPending, setCardBootstrapPending] = (0, import_react7.useState)(false);
+  const [deferredCardOpen, setDeferredCardOpen] = (0, import_react7.useState)(false);
   const autoCheckoutAttempted = (0, import_react7.useRef)(false);
   const onCompleteRef = (0, import_react7.useRef)(onComplete);
   onCompleteRef.current = onComplete;
   const onErrorRef = (0, import_react7.useRef)(onError);
   onErrorRef.current = onError;
+  const onDeclineRef = (0, import_react7.useRef)(onDecline);
+  onDeclineRef.current = onDecline;
   const onSessionCompletedRef = (0, import_react7.useRef)(onSessionCompleted);
   onSessionCompletedRef.current = onSessionCompleted;
+  const effectiveCreateSession = (0, import_react7.useMemo)(
+    () => createSessionParams ? mergeInlineSessionPatch(createSessionParams, createSessionPatch) : void 0,
+    [createSessionParams, createSessionPatch]
+  );
+  const emitDecline = (0, import_react7.useCallback)(
+    (method, input, overrides) => {
+      onDeclineRef.current?.(buildDeclineEvent(method, input, overrides));
+    },
+    []
+  );
   const processPaymentForMode = (0, import_react7.useCallback)(
     async (sess) => {
       const baseUrl = resolvedBillingUrl.replace(/\/+$/, "");
@@ -1474,9 +1718,13 @@ function FloPayCheckout({
           // No client secret available
         };
       }
-      throw new import_shared5.FloPayError(
+      throw new import_shared6.FloPayError(
         json?.message ?? "Payment failed. Please try again.",
-        "api_error"
+        "api_error",
+        {
+          code: json?.code ?? json?.gatewayErrorCode,
+          declineCode: json?.declineCode ?? json?.gatewayDeclineReason
+        }
       );
     },
     [resolvedBillingUrl, resolvedSessionId]
@@ -1495,6 +1743,9 @@ function FloPayCheckout({
         });
         if (nextActionError) {
           setModeError(nextActionError.message ?? "3DS authentication failed.");
+          emitDecline("card", nextActionError.message ?? "3DS authentication failed.", {
+            code: nextActionError.code
+          });
           return false;
         }
         if (paymentIntent && (paymentIntent.status === "requires_capture" || paymentIntent.status === "succeeded")) {
@@ -1517,6 +1768,9 @@ function FloPayCheckout({
         });
         if (error) {
           setModeError(error.message ?? "PayPal authorization failed.");
+          emitDecline("paypal", error.message ?? "PayPal authorization failed.", {
+            code: error.code
+          });
           return false;
         }
         onCompleteRef.current?.({ status: "succeeded" });
@@ -1524,16 +1778,24 @@ function FloPayCheckout({
       }
       return false;
     },
-    [resolvedBillingUrl, resolvedSessionId]
+    [resolvedBillingUrl, resolvedSessionId, emitDecline]
   );
   const inflightRef = (0, import_react7.useRef)(/* @__PURE__ */ new Map());
   const initializedHashRef = (0, import_react7.useRef)(null);
+  const deferInlineSessionUntilCardClick = Boolean(
+    effectiveCreateSession && !children && layout === "buttons" && onBeforeButtonClick && (effectiveCreateSession.checkoutMode ?? checkoutModeProp ?? "full") === "full"
+  );
   function hashCreateParams(params) {
     const key = JSON.stringify({
       c: params?.clientId,
+      successUrl: params?.successUrl,
+      cancelUrl: params?.cancelUrl,
       i: params?.items?.map((x) => `${x.providerItemId}:${x.totalAmount}:${x.overrideAmount ?? ""}:${x.quantity ?? 1}`).sort(),
       s: params?.subscriptions?.map((x) => `${x.providerPlanId}:${x.totalAmount}:${x.overrideAmount ?? ""}:${x.quantity ?? 1}`).sort(),
-      e: params?.account.email,
+      account: params?.account,
+      couponCodes: params?.couponCodes,
+      tagsData: params?.tagsData,
+      utmMetadata: params?.utmMetadata,
       m: params?.checkoutMode ?? "full"
     });
     let h = 0;
@@ -1543,138 +1805,167 @@ function FloPayCheckout({
     return `flopay_session_${Math.abs(h).toString(36)}`;
   }
   const createSessionHash = (0, import_react7.useMemo)(
-    () => createSessionParams ? hashCreateParams(createSessionParams) : "",
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      createSessionParams?.clientId,
-      createSessionParams?.account?.email,
-      createSessionParams?.checkoutMode,
-      JSON.stringify(createSessionParams?.items),
-      JSON.stringify(createSessionParams?.subscriptions)
-    ]
+    () => effectiveCreateSession ? hashCreateParams(effectiveCreateSession) : "",
+    [effectiveCreateSession]
+  );
+  const createSessionParamsRef = (0, import_react7.useRef)(effectiveCreateSession);
+  createSessionParamsRef.current = effectiveCreateSession;
+  (0, import_react7.useEffect)(() => {
+    setResolvedSessionId(sessionIdProp ?? "");
+  }, [sessionIdProp]);
+  async function resolveInlineSession(params, cacheKey) {
+    ensureInlineSessionReady(params);
+    const api = new import_js.PaymentAPI(resolvedBillingUrl);
+    let sid = typeof window !== "undefined" ? window.sessionStorage.getItem(cacheKey) : null;
+    let realResult = null;
+    if (sid) {
+      try {
+        realResult = await api.getUnifiedCheckoutSession(sid);
+        if (realResult.data.session?.status === "complete") {
+          if (typeof window !== "undefined") window.sessionStorage.removeItem(cacheKey);
+          sid = null;
+          realResult = null;
+        }
+      } catch {
+        if (typeof window !== "undefined") window.sessionStorage.removeItem(cacheKey);
+        sid = null;
+      }
+    }
+    if (!sid) {
+      realResult = await api.createAndFetchSession(params);
+      sid = realResult.data.session?.id ?? "";
+      if (sid && typeof window !== "undefined") {
+        window.sessionStorage.setItem(cacheKey, sid);
+      }
+    }
+    return { sid: sid ?? "", result: realResult };
+  }
+  const bootstrapInlineSession = (0, import_react7.useCallback)(
+    async (patch) => {
+      const baseParams = createSessionParamsRef.current;
+      if (!baseParams) {
+        throw new import_shared6.FloPayError("createSession is required to bootstrap checkout.", "validation_error");
+      }
+      const mergedParams = mergeInlineSessionPatch(baseParams, patch);
+      const cacheKey = hashCreateParams(mergedParams);
+      let promise = inflightRef.current.get(cacheKey);
+      if (!promise) {
+        promise = resolveInlineSession(mergedParams, cacheKey);
+        inflightRef.current.set(cacheKey, promise);
+      }
+      let resolved;
+      try {
+        resolved = await promise;
+      } finally {
+        inflightRef.current.delete(cacheKey);
+      }
+      if (patch) {
+        setCreateSessionPatch((prev) => mergeInlineSessionPatches(prev, patch));
+      }
+      const { sid, result: realResult } = resolved;
+      setUnified(realResult);
+      if (realResult.data.session) {
+        setSession(realResult.data.session);
+      }
+      if (sid) {
+        setResolvedSessionId(sid);
+      }
+      let publishableKey;
+      if (realResult.provider === "stripe") {
+        publishableKey = realResult.data.stripe?.publishableKey;
+      }
+      if (!publishableKey) publishableKey = fallbackPublishableKey;
+      if (!publishableKey) {
+        throw new import_shared6.FloPayError(
+          "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
+          "validation_error"
+        );
+      }
+      const instance = await (0, import_js.loadFloPay)(publishableKey, {
+        billingApiUrl: resolvedBillingUrl,
+        locale
+      });
+      flopayRef.current = instance;
+      setFloPay(instance);
+      initializedHashRef.current = cacheKey;
+      setIsLoading(false);
+      return resolved;
+    },
+    [fallbackPublishableKey, locale, resolvedBillingUrl]
   );
-  const createSessionParamsRef = (0, import_react7.useRef)(createSessionParams);
-  createSessionParamsRef.current = createSessionParams;
+  const handleDeferredCardButtonClick = (0, import_react7.useCallback)(async () => {
+    if (cardBootstrapPending) return;
+    setLoadError(null);
+    setCardBootstrapPending(true);
+    try {
+      const beforeClickResult = await onBeforeButtonClick?.({
+        method: "card",
+        createSession: effectiveCreateSession
+      });
+      if (beforeClickResult === false) {
+        setDeferredCardOpen(false);
+        return;
+      }
+      const patch = beforeClickResult && typeof beforeClickResult === "object" ? beforeClickResult : void 0;
+      const baseParams = createSessionParamsRef.current;
+      if (!baseParams) {
+        throw new import_shared6.FloPayError(
+          "createSession is required to bootstrap checkout.",
+          "validation_error"
+        );
+      }
+      ensureInlineSessionReady(mergeInlineSessionPatch(baseParams, patch));
+      setDeferredCardOpen(true);
+      onButtonClick?.("card");
+      await bootstrapInlineSession(patch);
+    } catch (err) {
+      setDeferredCardOpen(false);
+      const floPayErr = err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(
+        err instanceof Error ? err.message : "Failed to start card checkout.",
+        "api_error"
+      );
+      setLoadError(floPayErr);
+      onErrorRef.current?.(floPayErr);
+    } finally {
+      setCardBootstrapPending(false);
+    }
+  }, [
+    bootstrapInlineSession,
+    cardBootstrapPending,
+    effectiveCreateSession,
+    onButtonClick,
+    onBeforeButtonClick
+  ]);
   (0, import_react7.useEffect)(() => {
     let cancelled = false;
     setLoadError(null);
     if (createSessionHash) {
+      if (deferInlineSessionUntilCardClick) {
+        if (initializedHashRef.current !== createSessionHash) {
+          setSession(null);
+          setUnified(null);
+          setFloPay(null);
+          setResolvedSessionId("");
+          setDeferredCardOpen(false);
+          flopayRef.current = null;
+        }
+        setCurrentMode(createSessionParamsRef.current?.checkoutMode ?? checkoutModeProp ?? "full");
+        setIsLoading(false);
+        return () => {
+          cancelled = true;
+        };
+      }
       if (initializedHashRef.current === createSessionHash) return;
       const params = createSessionParamsRef.current;
-      const totalAmount = [
-        ...(params.items ?? []).map((i) => i.overrideAmount ?? i.totalAmount ?? 0),
-        ...(params.subscriptions ?? []).map((s) => s.overrideAmount ?? s.totalAmount ?? 0)
-      ].reduce((sum, v) => sum + v, 0);
-      const currency = params.items?.[0]?.currency ?? params.subscriptions?.[0]?.currency ?? "USD";
-      const syntheticSession = {
-        id: "",
-        clientSecret: "",
-        mode: "payment",
-        amount: Math.round(totalAmount * 100),
-        currency,
-        status: "open",
-        customer: {
-          id: params.account.userId,
-          email: params.account.email,
-          firstName: params.account.firstName,
-          lastName: params.account.lastName
-        },
-        successUrl: params.successUrl,
-        cancelUrl: params.cancelUrl,
-        checkoutMode: params.checkoutMode ?? "full",
-        items: (params.items ?? []).map((i, idx) => ({
-          uuid: `synthetic-item-${idx}`,
-          checkoutSessionId: "",
-          providerItemId: i.providerItemId,
-          providerItemName: i.providerItemName ?? i.providerItemId,
-          quantity: i.quantity ?? 1,
-          totalAmount: i.totalAmount,
-          overrideAmount: i.overrideAmount ?? null,
-          currency: i.currency ?? currency
-        })),
-        subscriptions: (params.subscriptions ?? []).map((s, idx) => ({
-          uuid: `synthetic-sub-${idx}`,
-          checkoutSessionId: "",
-          providerPlanId: s.providerPlanId,
-          providerPlanName: s.providerPlanName ?? s.providerPlanId,
-          quantity: s.quantity ?? 1,
-          totalAmount: s.totalAmount,
-          overrideAmount: s.overrideAmount ?? null,
-          currency: s.currency ?? currency
-        }))
-      };
-      setSession(syntheticSession);
+      setSession(buildSyntheticSession(params, checkoutModeProp));
       setCurrentMode(params.checkoutMode ?? checkoutModeProp ?? "full");
       setIsLoading(false);
-      const cacheKey = createSessionHash;
-      async function resolveSession() {
-        const api = new import_js.PaymentAPI(resolvedBillingUrl);
-        let sid = typeof window !== "undefined" ? window.sessionStorage.getItem(cacheKey) : null;
-        let realResult = null;
-        if (sid) {
-          try {
-            realResult = await api.getUnifiedCheckoutSession(sid);
-            if (realResult.data.session?.status === "complete") {
-              if (typeof window !== "undefined") window.sessionStorage.removeItem(cacheKey);
-              sid = null;
-              realResult = null;
-            }
-          } catch {
-            if (typeof window !== "undefined") window.sessionStorage.removeItem(cacheKey);
-            sid = null;
-          }
-        }
-        if (!sid) {
-          realResult = await api.createAndFetchSession(createSessionParamsRef.current);
-          sid = realResult.data.session?.id ?? "";
-          if (sid && typeof window !== "undefined") {
-            window.sessionStorage.setItem(cacheKey, sid);
-          }
-        }
-        return { sid: sid ?? "", result: realResult };
-      }
       (async () => {
         try {
-          let promise = inflightRef.current.get(cacheKey);
-          if (!promise) {
-            promise = resolveSession();
-            inflightRef.current.set(cacheKey, promise);
-          }
-          let resolved;
-          try {
-            resolved = await promise;
-          } finally {
-            inflightRef.current.delete(cacheKey);
-          }
-          if (cancelled) return;
-          const { sid, result: realResult } = resolved;
-          if (realResult) {
-            setUnified(realResult);
-            if (realResult.data.session) setSession(realResult.data.session);
-          }
-          if (sid) {
-            setResolvedSessionId(sid);
-          }
-          let pk;
-          if (realResult?.provider === "stripe") {
-            pk = realResult.data.stripe?.publishableKey;
-          }
-          if (!pk) pk = fallbackPublishableKey;
-          if (!pk) {
-            throw new import_shared5.FloPayError(
-              "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
-              "validation_error"
-            );
-          }
-          const instance = await (0, import_js.loadFloPay)(pk, { billingApiUrl: resolvedBillingUrl, locale });
-          if (!cancelled) {
-            flopayRef.current = instance;
-            setFloPay(instance);
-            initializedHashRef.current = cacheKey;
-          }
+          await bootstrapInlineSession();
         } catch (err) {
           if (cancelled) return;
-          const floPayErr = err instanceof import_shared5.FloPayError ? err : new import_shared5.FloPayError(err instanceof Error ? err.message : "Failed to create session", "api_error");
+          const floPayErr = err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(err instanceof Error ? err.message : "Failed to create session", "api_error");
           setLoadError(floPayErr);
         }
       })();
@@ -1692,7 +1983,7 @@ function FloPayCheckout({
         const sess = result.data.session ?? null;
         setSession(sess);
         if (!sess) {
-          throw new import_shared5.FloPayError("No session data returned", "api_error");
+          throw new import_shared6.FloPayError("No session data returned", "api_error");
         }
         if (sess.status === "complete") {
           setIsLoading(false);
@@ -1731,7 +2022,7 @@ function FloPayCheckout({
         if (!cancelled) setIsLoading(false);
       } catch (err) {
         if (cancelled) return;
-        const floPayErr = err instanceof import_shared5.FloPayError ? err : new import_shared5.FloPayError(err instanceof Error ? err.message : "Failed to initialize checkout", "api_error");
+        const floPayErr = err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(err instanceof Error ? err.message : "Failed to initialize checkout", "api_error");
         setLoadError(floPayErr);
         setIsLoading(false);
       }
@@ -1743,7 +2034,7 @@ function FloPayCheckout({
       }
       if (!publishableKey) publishableKey = fallbackPublishableKey;
       if (!publishableKey) {
-        throw new import_shared5.FloPayError(
+        throw new import_shared6.FloPayError(
           "No publishable key found in session response. Provide a fallbackPublishableKey prop or ensure the session includes gatewayData.publishableKey.",
           "validation_error"
         );
@@ -1759,7 +2050,7 @@ function FloPayCheckout({
     return () => {
       cancelled = true;
     };
-  }, [resolvedSessionId, createSessionHash, resolvedBillingUrl, fallbackPublishableKey, locale, checkoutModeProp]);
+  }, [resolvedSessionId, createSessionHash, checkoutModeProp, deferInlineSessionUntilCardClick, bootstrapInlineSession]);
   const handleConfirmCheckout = (0, import_react7.useCallback)(async () => {
     if (confirmProcessing || !session) return;
     setConfirmProcessing(true);
@@ -1774,17 +2065,18 @@ function FloPayCheckout({
         setCurrentMode("full");
       }
     } catch (err) {
-      const floPayErr = err instanceof import_shared5.FloPayError ? err : new import_shared5.FloPayError(
+      const floPayErr = err instanceof import_shared6.FloPayError ? err : new import_shared6.FloPayError(
         err instanceof Error ? err.message : "Payment failed",
         "api_error"
       );
       setModeError(floPayErr.message);
       onError?.(floPayErr);
+      emitDecline("card", floPayErr);
       setCurrentMode("full");
     } finally {
       setConfirmProcessing(false);
     }
-  }, [confirmProcessing, session, processPaymentForMode, handleRedirectResult, onError]);
+  }, [confirmProcessing, session, processPaymentForMode, handleRedirectResult, onError, emitDecline]);
   const providerOptions = (0, import_react7.useMemo)(() => {
     if (!unified || !session) return void 0;
     const opts = {
@@ -1795,7 +2087,7 @@ function FloPayCheckout({
     if (unified.provider === "stripe" && unified.data.stripe?.clientSecret) {
       opts.clientSecret = unified.data.stripe.clientSecret;
     } else {
-      const displayTotal = (0, import_shared5.buildCheckoutDisplayData)(session).total;
+      const displayTotal = (0, import_shared6.buildCheckoutDisplayData)(session).total;
       opts.amount = Math.round(displayTotal * 100) || session.amount;
       opts.currency = session.currency?.toLowerCase();
     }
@@ -1810,6 +2102,8 @@ function FloPayCheckout({
     }),
     [session, isLoading, loadError, currentMode]
   );
+  const shouldShowInterimButtons = Boolean(createSessionParams) && layout === "buttons" && (!flopay || !providerOptions);
+  const shouldKeepDeferredInterimVisible = shouldShowInterimButtons && deferInlineSessionUntilCardClick;
   if (isLoading) {
     if (loadingNode) return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: loadingNode });
     if (layout === "buttons") {
@@ -1838,7 +2132,7 @@ function FloPayCheckout({
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("style", { children: `@keyframes spin { to { transform: rotate(360deg); } }` })
     ] });
   }
-  if (loadError) {
+  if (loadError && !shouldKeepDeferredInterimVisible) {
     if (errorNode) return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(import_jsx_runtime5.Fragment, { children: errorNode(loadError) });
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
       "div",
@@ -1853,17 +2147,23 @@ function FloPayCheckout({
       }
     );
   }
-  if ((!flopay || !providerOptions) && createSessionParams && layout === "buttons") {
+  if (shouldShowInterimButtons) {
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(CheckoutContext.Provider, { value: checkoutValue, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(
       InterimButtonsView,
       {
         onButtonClick,
-        showPayPal,
-        showApplePay,
-        showGooglePay,
+        onCardButtonClick: deferInlineSessionUntilCardClick ? handleDeferredCardButtonClick : void 0,
+        cardLoading: cardBootstrapPending,
+        cardOpen: deferInlineSessionUntilCardClick ? deferredCardOpen : void 0,
+        errorMessage: shouldKeepDeferredInterimVisible ? loadError?.message ?? null : null,
+        showPayPal: deferInlineSessionUntilCardClick ? false : showPayPal,
+        showApplePay: deferInlineSessionUntilCardClick ? false : showApplePay,
+        showGooglePay: deferInlineSessionUntilCardClick ? false : showGooglePay,
         buttonsTheme,
         buttonsStyles,
-        cardButtonContent
+        cardButtonContent,
+        cardBackButtonContent,
+        cardTitleContent
       }
     ) });
   }
@@ -1940,10 +2240,11 @@ function FloPayCheckout({
         userId: session?.customer?.id,
         firstName: session?.customer?.firstName,
         lastName: session?.customer?.lastName,
-        totalAmount: session ? Math.round((0, import_shared5.buildCheckoutDisplayData)(session).total * 100) : 0,
+        totalAmount: session ? Math.round((0, import_shared6.buildCheckoutDisplayData)(session).total * 100) : 0,
         currency: session?.currency?.toLowerCase() ?? "usd",
         onComplete,
         onError,
+        onDecline,
         showPayPal,
         showApplePay,
         showGooglePay,
@@ -1951,11 +2252,15 @@ function FloPayCheckout({
         buttonsTheme,
         buttonsStyles,
         cardButtonContent,
+        cardBackButtonContent,
+        cardTitleContent,
         onButtonClick,
+        onBeforeButtonClick,
         enableAVS,
         avsLayout,
         country: session?.customer?.country,
         zip: session?.customer?.zip,
+        initialCardOpen: deferredCardOpen,
         submitLabel,
         className
       }
@@ -1988,22 +2293,36 @@ function SessionInjector({
 }
 function InterimButtonsView({
   onButtonClick,
+  onCardButtonClick,
+  cardLoading = false,
+  cardOpen,
+  errorMessage,
   showPayPal,
   showApplePay,
   showGooglePay,
   buttonsTheme,
   buttonsStyles: stylesOverride,
-  cardButtonContent
+  cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent
 }) {
   const [showCardForm, setShowCardForm] = (0, import_react7.useState)(false);
+  const isCardOpenControlled = typeof cardOpen === "boolean";
+  (0, import_react7.useEffect)(() => {
+    if (isCardOpenControlled) {
+      setShowCardForm(cardOpen);
+    }
+  }, [cardOpen, isCardOpenControlled]);
   const bStyles = (0, import_react7.useMemo)(() => {
-    const base = (0, import_shared5.resolveButtonsLayoutTheme)(buttonsTheme);
+    const base = (0, import_shared6.resolveButtonsLayoutTheme)(buttonsTheme);
     if (!stylesOverride) return base;
     return {
       ...base,
       ...stylesOverride,
       cardButton: { ...base.cardButton, ...stylesOverride.cardButton },
       cardFormContainer: { ...base.cardFormContainer, ...stylesOverride.cardFormContainer },
+      backButton: { ...base.backButton, ...stylesOverride.backButton },
+      backButtonIcon: { ...base.backButtonIcon, ...stylesOverride.backButtonIcon },
       submitButton: { ...base.submitButton, ...stylesOverride.submitButton },
       title: { ...base.title, ...stylesOverride.title }
     };
@@ -2017,6 +2336,8 @@ function InterimButtonsView({
   if (showCardForm) {
     const inputBorder = bStyles.cardInputBorder ?? "#e5e7eb";
     const inputBg = bStyles.cardInputBackground ?? "white";
+    const hideBackButtonLabel = isEmptySlotContent(cardBackButtonContent);
+    const hideTitle = isEmptySlotContent(cardTitleContent);
     return /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: {
       backgroundColor: bStyles.cardFormContainer?.backgroundColor ?? "white",
       borderRadius: "8px",
@@ -2029,19 +2350,26 @@ function InterimButtonsView({
           "button",
           {
             type: "button",
-            onClick: () => setShowCardForm(false),
+            onClick: () => {
+              if (!isCardOpenControlled) {
+                setShowCardForm(false);
+              }
+            },
+            "aria-label": "Back to payment methods",
+            disabled: isCardOpenControlled || cardLoading,
             style: {
               display: "inline-flex",
               alignItems: "center",
-              gap: "0.5rem",
+              gap: hideBackButtonLabel ? 0 : "0.5rem",
               background: "none",
               border: "none",
-              cursor: "pointer",
               color: "#4b5563",
               fontSize: "0.85rem",
               fontWeight: 500,
               padding: 0,
               flexShrink: 0,
+              opacity: isCardOpenControlled || cardLoading ? 0.6 : 1,
+              cursor: isCardOpenControlled || cardLoading ? "not-allowed" : "pointer",
               ...bStyles.backButton
             },
             children: [
@@ -2055,11 +2383,11 @@ function InterimButtonsView({
                 backgroundColor: "#f3f4f6",
                 ...bStyles.backButtonIcon
               }, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M15 18l-6-6 6-6" }) }) }),
-              "Go back"
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(BackButtonContentSlot, { content: cardBackButtonContent })
             ]
           }
         ),
-        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: {
+        hideTitle ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { flex: 1 } }) : /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: {
           flex: 1,
           textAlign: "center",
           fontWeight: 600,
@@ -2067,7 +2395,7 @@ function InterimButtonsView({
           color: "#262833",
           paddingRight: 80,
           ...bStyles.title
-        }, children: "Secure card checkout" })
+        }, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(TitleContentSlot, { content: cardTitleContent }) })
       ] }),
       /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { backgroundColor: inputBg, border: `1px solid ${inputBorder}`, borderTopLeftRadius: 8, borderTopRightRadius: 8, padding: 12, height: 45 }, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { width: "60%", height: 14, borderRadius: 4, background: "#e5e7eb", animation: "flopay-interim-pulse 1.5s ease-in-out infinite" } }) }),
       /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { display: "flex" }, children: [
@@ -2101,10 +2429,16 @@ function InterimButtonsView({
       "button",
       {
         type: "button",
-        onClick: () => {
+        onClick: async () => {
+          if (cardLoading) return;
+          if (onCardButtonClick) {
+            await onCardButtonClick();
+            return;
+          }
           onButtonClick?.("card");
           setShowCardForm(true);
         },
+        disabled: cardLoading,
         style: {
           width: "100%",
           padding: "0.9rem 1rem",
@@ -2114,7 +2448,7 @@ function InterimButtonsView({
           borderRadius: "8px",
           fontSize: bStyles.cardButtonFontSize ?? "0.95rem",
           fontWeight: 600,
-          cursor: "pointer",
+          cursor: cardLoading ? "not-allowed" : "pointer",
           display: "flex",
           alignItems: "center",
           justifyContent: "center",
@@ -2122,6 +2456,7 @@ function InterimButtonsView({
           boxShadow: "0 1px 2px rgba(0,0,0,0.04)",
           transition: "transform 0.1s",
           position: "relative",
+          opacity: cardLoading ? 0.6 : 1,
           ...bStyles.cardButton
         },
         onMouseDown: (e) => {
@@ -2133,12 +2468,29 @@ function InterimButtonsView({
         children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(CardButtonContentSlot, { content: cardButtonContent })
       }
     ),
+    errorMessage && /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: {
+      margin: "0.25rem 0",
+      padding: "0.625rem 0.875rem",
+      background: "#FEF2F2",
+      border: "1px solid #FECACA",
+      borderRadius: "8px",
+      color: "#991B1B",
+      fontSize: "0.85rem",
+      fontWeight: 600,
+      display: "flex",
+      alignItems: "center",
+      gap: "0.5rem",
+      ...bStyles.errorBanner
+    }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", style: { flexShrink: 0 }, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("path", { d: "M12 9v4m0 4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z", stroke: "#DC2626", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }) }),
+      errorMessage
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("style", { children: `@keyframes flopay-interim-pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.4; } }` })
   ] });
 }
 
 // src/checkout-form.tsx
-var import_shared6 = require("@flopay/shared");
+var import_shared7 = require("@flopay/shared");
 var import_react8 = require("react");
 var import_jsx_runtime6 = require("react/jsx-runtime");
 var WALLET_RESUME_KEY2 = "flopay_wallet_resume";
@@ -2154,6 +2506,7 @@ function CheckoutFormInner({
   userId,
   onComplete,
   onError,
+  onDecline,
   onTokenizedBody,
   layout = "auto",
   submitLabel = "Pay",
@@ -2185,6 +2538,12 @@ function CheckoutFormInner({
     },
     [onErrorChange]
   );
+  const emitDecline = (0, import_react8.useCallback)(
+    (input, overrides) => {
+      onDecline?.(buildDeclineEvent("card", input, overrides));
+    },
+    [onDecline]
+  );
   const processPaymentInternal = (0, import_react8.useCallback)(
     async (tokenizedBody) => {
       setProcessing(true);
@@ -2231,6 +2590,7 @@ function CheckoutFormInner({
             if (result.error) {
               updateError(result.error.message);
               onError?.(result.error);
+              emitDecline(result.error);
               return;
             }
             if (result.status === "succeeded" || result.status === "processing") {
@@ -2265,13 +2625,17 @@ function CheckoutFormInner({
         }
         const errorMessage = json?.message ?? "Payment failed. Please try again.";
         updateError(errorMessage);
+        emitDecline(errorMessage, {
+          code: json?.code,
+          declineCode: json?.declineCode ?? json?.gatewayDeclineReason
+        });
       } catch (err) {
         updateError(err instanceof Error ? err.message : "An unexpected error occurred");
       } finally {
         setProcessing(false);
       }
     },
-    [baseUrl, sessionId, userId, email, firstName, lastName, chv, flopay, onComplete, onError, updateError]
+    [baseUrl, sessionId, userId, email, firstName, lastName, chv, flopay, onComplete, onError, updateError, emitDecline]
   );
   const dispatchTokenizedBody = (0, import_react8.useCallback)(
     (tokenizedBody) => {
@@ -2295,6 +2659,7 @@ function CheckoutFormInner({
         if (result.error) {
           updateError(result.error.message);
           onError?.(result.error);
+          emitDecline(result.error);
         } else if (result.status === "succeeded" || result.status === "processing") {
           dispatchTokenizedBody({
             id: result.paymentIntentId,
@@ -2308,7 +2673,7 @@ function CheckoutFormInner({
         setIs3DSActive(false);
       }
     }
-  }), [flopay, dispatchTokenizedBody, onError, updateError]);
+  }), [flopay, dispatchTokenizedBody, onError, updateError, emitDecline]);
   (0, import_react8.useEffect)(() => {
     if (typeof window === "undefined") return;
     const stored = localStorage.getItem(WALLET_RESUME_KEY2);
@@ -2346,7 +2711,7 @@ function CheckoutFormInner({
           return;
         }
         if (!sessionId || !email) {
-          throw new import_shared6.FloPayError("Missing sessionId or email", "validation_error");
+          throw new import_shared7.FloPayError("Missing sessionId or email", "validation_error");
         }
         const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
           method: "POST",
@@ -2358,16 +2723,18 @@ function CheckoutFormInner({
             isPaypal: false
           })
         });
-        if (!intentResponse.ok) throw new import_shared6.FloPayError("Failed to create payment intent", "api_error");
+        if (!intentResponse.ok) throw new import_shared7.FloPayError("Failed to create payment intent", "api_error");
         const intentJson = await intentResponse.json();
         const intentClientSecret = intentJson.data?.id;
-        if (!intentClientSecret) throw new import_shared6.FloPayError("No client_secret in payment intent response", "api_error");
+        if (!intentClientSecret) throw new import_shared7.FloPayError("No client_secret in payment intent response", "api_error");
         const confirmResult = await flopay.confirmCardPayment({
           clientSecret: intentClientSecret,
           paymentMethodId: pmResult.paymentMethodId
         });
         if (confirmResult.error) {
           updateError(confirmResult.error.message);
+          onError?.(confirmResult.error);
+          emitDecline(confirmResult.error);
           return;
         }
         dispatchTokenizedBody({
@@ -2384,7 +2751,7 @@ function CheckoutFormInner({
         }
       }
     },
-    [flopay, elements, isSubmitting, sessionId, email, baseUrl, isSelfContained, dispatchTokenizedBody, onError, updateError]
+    [flopay, elements, isSubmitting, sessionId, email, baseUrl, isSelfContained, dispatchTokenizedBody, onError, updateError, emitDecline]
   );
   const isReady = flopay !== null && elements !== null;
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsxs)("form", { onSubmit: handleSubmit, className, style: { position: "relative" }, children: [
@@ -2416,7 +2783,7 @@ function CheckoutFormInner({
 }
 
 // src/paypal-button.tsx
-var import_shared7 = require("@flopay/shared");
+var import_shared8 = require("@flopay/shared");
 var import_react9 = require("react");
 var import_jsx_runtime7 = require("react/jsx-runtime");
 function PayPalButton({
@@ -2536,7 +2903,7 @@ function PayPalButton({
       setSubmitting(true);
       onErrorChange?.(null);
       if (!sessionId || !email) {
-        throw new import_shared7.FloPayError("Missing sessionId or email for PayPal payment", "validation_error");
+        throw new import_shared8.FloPayError("Missing sessionId or email for PayPal payment", "validation_error");
       }
       const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
         method: "POST",
@@ -2548,10 +2915,10 @@ function PayPalButton({
           isPaypal: "true"
         })
       });
-      if (!intentResponse.ok) throw new import_shared7.FloPayError("Failed to create payment intent", "api_error");
+      if (!intentResponse.ok) throw new import_shared8.FloPayError("Failed to create payment intent", "api_error");
       const intentJson = await intentResponse.json();
       const intentClientSecret = intentJson.data?.id;
-      if (!intentClientSecret) throw new import_shared7.FloPayError("No client_secret in response", "api_error");
+      if (!intentClientSecret) throw new import_shared8.FloPayError("No client_secret in response", "api_error");
       const result = await flopay.confirmPayment({
         clientSecret: intentClientSecret,
         returnUrl: window.location.href