@flopay/react 0.3.5 → 0.3.12

package/dist/index.mjs

@@ -69,7 +69,7 @@ function FloPayProvider({
 // src/flopay-checkout.tsx
 import React5, { useCallback as useCallback2, useEffect as useEffect4, useMemo as useMemo3, useRef as useRef3, useState as useState3 } from "react";
 import { loadFloPay, PaymentAPI } from "@flopay/js";
-import { FloPayError as FloPayError2, resolveBillingApiUrl as resolveBillingApiUrl3, buildCheckoutDisplayData, resolveButtonsLayoutTheme as resolveButtonsLayoutTheme2 } from "@flopay/shared";
+import { FloPayError as FloPayError3, resolveBillingApiUrl as resolveBillingApiUrl3, buildCheckoutDisplayData, resolveButtonsLayoutTheme as resolveButtonsLayoutTheme2 } from "@flopay/shared";
 
 // src/card-button-content.tsx
 import "react";
@@ -113,10 +113,29 @@ function DefaultCardButtonContent() {
     )
   ] });
 }
+function DefaultBackButtonContent() {
+  return /* @__PURE__ */ jsx2(Fragment, { children: "Go back" });
+}
+function DefaultTitleContent() {
+  return /* @__PURE__ */ jsx2(Fragment, { children: "Secure card checkout" });
+}
+function isEmptySlotContent(content) {
+  return content !== void 0 && (content === "" || content === null || content === false);
+}
 function CardButtonContentSlot({
   content
 }) {
-  return /* @__PURE__ */ jsx2(Fragment, { children: content ?? /* @__PURE__ */ jsx2(DefaultCardButtonContent, {}) });
+  return /* @__PURE__ */ jsx2(Fragment, { children: content === void 0 ? /* @__PURE__ */ jsx2(DefaultCardButtonContent, {}) : content });
+}
+function BackButtonContentSlot({
+  content
+}) {
+  return /* @__PURE__ */ jsx2(Fragment, { children: content === void 0 ? /* @__PURE__ */ jsx2(DefaultBackButtonContent, {}) : content });
+}
+function TitleContentSlot({
+  content
+}) {
+  return /* @__PURE__ */ jsx2(Fragment, { children: content === void 0 ? /* @__PURE__ */ jsx2(DefaultTitleContent, {}) : content });
 }
 
 // src/elements.tsx
@@ -208,8 +227,116 @@ function useBillingApiUrl() {
   return ctx.billingApiUrl || resolveBillingApiUrl2();
 }
 
-// src/split-card-form.tsx
+// src/checkout-utils.ts
 import { FloPayError } from "@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 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
+import { FloPayError as FloPayError2 } from "@flopay/shared";
 import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
 var WALLET_RESUME_KEY = "flopay_wallet_resume";
 var FLOPAY_KEYFRAMES = `
@@ -347,7 +474,8 @@ function PayPalButtonInner({
   onTokenizedBody,
   onErrorChange,
   isProcessing = false,
-  onButtonClick
+  onButtonClick,
+  onDecline
 }) {
   const stripe = useStripeRaw();
   const elements = useStripeElements();
@@ -367,7 +495,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);
@@ -389,7 +519,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.");
@@ -397,7 +529,7 @@ function PayPalButtonInner({
         setSubmitting(false);
       }
     })();
-  }, [stripe, onTokenizedBody, onErrorChange]);
+  }, [stripe, onTokenizedBody, onErrorChange, onDecline]);
   const handlePayPalConfirm = useCallback(async (_event) => {
     if (!stripe || !elements) return;
     onButtonClick?.("paypal");
@@ -438,7 +570,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;
@@ -453,7 +589,7 @@ function PayPalButtonInner({
     } finally {
       setSubmitting(false);
     }
-  }, [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange]);
+  }, [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]);
   return /* @__PURE__ */ jsxs2(Fragment2, { children: [
     /* @__PURE__ */ jsx4("div", { children: /* @__PURE__ */ jsx4(
       ExpressCheckoutElement,
@@ -462,6 +598,9 @@ function PayPalButtonInner({
         onLoadError: () => {
         },
         onConfirm: handlePayPalConfirm,
+        onCancel: () => {
+          onDecline?.(buildDeclineEvent("paypal", "PayPal checkout was cancelled."));
+        },
         options: {
           buttonType: { paypal: "paypal" },
           paymentMethods: {
@@ -484,13 +623,15 @@ function WalletButtonInner({
   showGooglePay = true,
   onTokenizedBody,
   onErrorChange,
-  onButtonClick
+  onButtonClick,
+  onDecline
 }) {
   const stripe = useStripeRaw();
   const elements = useStripeElements();
   const [ready, setReady] = useState2(false);
   const [submitting, setSubmitting] = useState2(false);
   const baseUrl = billingApiUrl.replace(/\/+$/, "");
+  const lastWalletMethodRef = useRef2("card");
   const handleWalletConfirm = useCallback(
     async (_event) => {
       if (!stripe || !elements) return;
@@ -531,7 +672,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({
@@ -545,7 +691,7 @@ function WalletButtonInner({
         setSubmitting(false);
       }
     },
-    [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange]
+    [stripe, elements, sessionId, email, baseUrl, onTokenizedBody, onErrorChange, onDecline]
   );
   return /* @__PURE__ */ jsxs2(Fragment2, { children: [
     /* @__PURE__ */ jsx4("div", { children: /* @__PURE__ */ jsx4(
@@ -554,7 +700,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: {
@@ -579,6 +732,7 @@ function SplitCardFormInner({
   userId,
   onComplete,
   onError,
+  onDecline,
   onTokenizedBody,
   firstName,
   lastName,
@@ -598,7 +752,10 @@ function SplitCardFormInner({
   buttonsTheme,
   buttonsStyles: buttonsStylesOverride,
   cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent,
   onButtonClick,
+  onBeforeButtonClick,
   enableAVS = false,
   avsLayout: avsLayoutProp = "row",
   country: countryProp,
@@ -607,6 +764,7 @@ function SplitCardFormInner({
   onZipChange,
   totalAmount = 0,
   currency = "usd",
+  initialCardOpen = false,
   innerRef
 }) {
   const flopay = useFloPay();
@@ -617,9 +775,10 @@ function SplitCardFormInner({
   const [is3DSActive, setIs3DSActive] = useState2(false);
   const [selectedCountry, setSelectedCountry] = useState2(countryProp ?? "US");
   const [zipCode, setZipCode] = useState2(zipProp ?? "");
+  const [accountPatch, setAccountPatch] = useState2({});
   const zipCodeRef = useRef2(zipProp ?? "");
   const selectedCountryRef = useRef2(countryProp ?? "US");
-  const [viewState, setViewState] = useState2("buttons");
+  const [viewState, setViewState] = useState2(initialCardOpen ? "card" : "buttons");
   const showCardForm = viewState === "expanding" || viewState === "card";
   const TRANSITION_MS = 280;
   const expandToCard = useCallback(() => {
@@ -630,6 +789,11 @@ function SplitCardFormInner({
     setViewState("collapsing");
     setTimeout(() => setViewState("buttons"), TRANSITION_MS);
   }, []);
+  useEffect3(() => {
+    if (layout === "buttons" && initialCardOpen) {
+      setViewState("card");
+    }
+  }, [layout, initialCardOpen]);
   const [fullName, setFullName] = useState2("");
   const [formReady, setFormReady] = useState2(false);
   const [overlayStatus, setOverlayStatus] = useState2(null);
@@ -653,6 +817,14 @@ function SplitCardFormInner({
   const isSubmitting = externalProcessing ?? processing;
   const isSelfContained = !onTokenizedBody;
   const baseUrl = resolvedBillingApiUrl.replace(/\/+$/, "");
+  const resolvedAccount = useMemo2(() => mergeAccountPatch({
+    userId,
+    email,
+    firstName,
+    lastName,
+    country: countryProp,
+    zip: zipProp
+  }, accountPatch), [userId, email, firstName, lastName, countryProp, zipProp, accountPatch]);
   const stripeInstance = useMemo2(() => {
     if (!flopay) return null;
     return flopay.getRawProvider();
@@ -678,6 +850,12 @@ function SplitCardFormInner({
     },
     [onErrorChange]
   );
+  const emitDecline = useCallback(
+    (method, input, overrides) => {
+      onDecline?.(buildDeclineEvent(method, input, overrides));
+    },
+    [onDecline]
+  );
   const showWallets = showApplePay || showGooglePay;
   const handleNameChange = useCallback((value) => {
     setFullName(value);
@@ -685,6 +863,30 @@ function SplitCardFormInner({
     onFirstNameChange?.(parts[0] ?? "");
     onLastNameChange?.(parts.length > 1 ? parts.slice(1).join(" ") : "");
   }, [onFirstNameChange, onLastNameChange]);
+  const runBeforeCardButtonClick = 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 FloPayError2 ? err : new FloPayError2(
+        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 = useCallback(
     async (tokenizedBody) => {
       if (processingRef.current) return;
@@ -697,16 +899,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
@@ -739,6 +941,7 @@ function SplitCardFormInner({
               setOverlayStatus("error");
               updateError(result.error.message);
               onError?.(result.error);
+              emitDecline("card", result.error);
               return;
             }
             if (result.status === "succeeded" || result.status === "processing") {
@@ -781,7 +984,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");
@@ -790,7 +997,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");
@@ -802,7 +1014,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 = useCallback(
     (tokenizedBody) => {
@@ -826,6 +1038,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,
@@ -839,7 +1052,7 @@ function SplitCardFormInner({
         setIs3DSActive(false);
       }
     }
-  }), [flopay, dispatchTokenizedBody, onError, updateError]);
+  }), [flopay, dispatchTokenizedBody, onError, updateError, emitDecline]);
   useEffect3(() => {
     if (typeof window === "undefined") return;
     const stored = localStorage.getItem(WALLET_RESUME_KEY);
@@ -862,7 +1075,9 @@ 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);
@@ -890,23 +1105,23 @@ function SplitCardFormInner({
           updateError(pmResult.error?.message ?? "Failed to create payment method.");
           return;
         }
-        if (!sessionId || !email) {
-          throw new FloPayError("Missing sessionId or email", "validation_error");
+        if (!sessionId || !resolvedAccount.email) {
+          throw new FloPayError2("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 FloPayError("Failed to create payment intent", "api_error");
+        if (!intentResponse.ok) throw new FloPayError2("Failed to create payment intent", "api_error");
         const intentJson = await intentResponse.json();
         const intentClientSecret = intentJson.data?.id;
-        if (!intentClientSecret) throw new FloPayError("No client_secret in payment intent response", "api_error");
+        if (!intentClientSecret) throw new FloPayError2("No client_secret in payment intent response", "api_error");
         const confirmResult = await flopay.confirmCardPayment({
           clientSecret: intentClientSecret,
           paymentMethodId: pmResult.paymentMethodId
@@ -914,6 +1129,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;
         }
@@ -934,7 +1151,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) {
@@ -944,6 +1161,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: {
@@ -974,7 +1193,7 @@ function SplitCardFormInner({
           style: {
             display: "inline-flex",
             alignItems: "center",
-            gap: "0.5rem",
+            gap: hideBackButtonLabel ? 0 : "0.5rem",
             background: "none",
             border: "none",
             cursor: "pointer",
@@ -999,11 +1218,11 @@ function SplitCardFormInner({
               transition: "background-color 0.15s",
               ...bStyles.backButtonIcon
             }, children: /* @__PURE__ */ jsx4("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ jsx4("path", { d: "M15 18l-6-6 6-6" }) }) }),
-            "Go back"
+            /* @__PURE__ */ jsx4(BackButtonContentSlot, { content: cardBackButtonContent })
           ]
         }
       ),
-      /* @__PURE__ */ jsx4("div", { style: {
+      hideTitle ? /* @__PURE__ */ jsx4("div", { style: { flex: 1 } }) : /* @__PURE__ */ jsx4("div", { style: {
         flex: 1,
         textAlign: "center",
         fontWeight: 600,
@@ -1011,9 +1230,9 @@ function SplitCardFormInner({
         color: "#262833",
         paddingRight: 80,
         ...bStyles.title
-      }, children: "Secure card checkout" })
+      }, children: /* @__PURE__ */ jsx4(TitleContentSlot, { content: cardTitleContent }) })
     ] }),
-    !isButtons && /* @__PURE__ */ jsx4("div", { style: { textAlign: "center", fontWeight: 600, fontSize: "1.1rem", padding: "0.5rem 0", color: "#262833" }, children: "Secure card checkout" }),
+    !isButtons && !hideTitle && /* @__PURE__ */ jsx4("div", { style: { textAlign: "center", fontWeight: 600, fontSize: "1.1rem", padding: "0.5rem 0", color: "#262833" }, children: /* @__PURE__ */ jsx4(TitleContentSlot, { content: cardTitleContent }) }),
     /* @__PURE__ */ jsx4("div", { style: {
       backgroundColor: cardInputBg,
       border: `1px solid ${resolvedBorder}`,
@@ -1217,32 +1436,36 @@ function SplitCardFormInner({
             PayPalButtonInner,
             {
               sessionId,
-              email,
+              email: resolvedAccount.email,
               billingApiUrl: resolvedBillingApiUrl,
               onTokenizedBody: dispatchTokenizedBody,
               onErrorChange: updateError,
               isProcessing: isSubmitting,
-              onButtonClick
+              onButtonClick,
+              onDecline
             }
           ) }) : showPayPal ? /* @__PURE__ */ jsx4("div", { style: { height: 44, borderRadius: 8, background: "#e5e7eb", animation: "flopay-pulse 1.5s ease-in-out infinite" } }) : null,
           showWallets && stripeInstance ? /* @__PURE__ */ jsx4(StripeElements, { stripe: stripeInstance, options: walletOptions, children: /* @__PURE__ */ jsx4(
             WalletButtonInner,
             {
               sessionId,
-              email,
+              email: resolvedAccount.email,
               billingApiUrl: resolvedBillingApiUrl,
               showApplePay,
               showGooglePay,
               onTokenizedBody: dispatchTokenizedBody,
               onErrorChange: updateError,
-              onButtonClick
+              onButtonClick,
+              onDecline
             }
           ) }) : showWallets ? /* @__PURE__ */ jsx4("div", { style: { height: 44, borderRadius: 8, background: "#e5e7eb", animation: "flopay-pulse 1.5s ease-in-out infinite" } }) : null,
           /* @__PURE__ */ jsx4(
             "button",
             {
               type: "button",
-              onClick: () => {
+              onClick: async () => {
+                const shouldContinue = await runBeforeCardButtonClick();
+                if (!shouldContinue) return;
                 onButtonClick?.("card");
                 expandToCard();
               },
@@ -1307,23 +1530,25 @@ function SplitCardFormInner({
       WalletButtonInner,
       {
         sessionId,
-        email,
+        email: resolvedAccount.email,
         billingApiUrl: resolvedBillingApiUrl,
         showApplePay,
         showGooglePay,
         onTokenizedBody: dispatchTokenizedBody,
-        onErrorChange: updateError
+        onErrorChange: updateError,
+        onDecline
       }
     ) }),
     showPayPal && stripeInstance && /* @__PURE__ */ jsx4(StripeElements, { stripe: stripeInstance, options: paypalOptions, children: /* @__PURE__ */ jsx4(
       PayPalButtonInner,
       {
         sessionId,
-        email,
+        email: resolvedAccount.email,
         billingApiUrl: resolvedBillingApiUrl,
         onTokenizedBody: dispatchTokenizedBody,
         onErrorChange: updateError,
-        isProcessing: isSubmitting
+        isProcessing: isSubmitting,
+        onDecline
       }
     ) }),
     (showWallets && stripeInstance || showPayPal && stripeInstance) && /* @__PURE__ */ jsxs2("div", { style: {
@@ -1355,6 +1580,7 @@ function FloPayCheckout({
   error: errorNode,
   onComplete,
   onError,
+  onDecline,
   showPayPal = true,
   showApplePay = true,
   showGooglePay = true,
@@ -1362,7 +1588,10 @@ function FloPayCheckout({
   buttonsTheme,
   buttonsStyles,
   cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent,
   onButtonClick,
+  onBeforeButtonClick,
   enableAVS,
   avsLayout,
   submitLabel,
@@ -1384,13 +1613,28 @@ function FloPayCheckout({
   const [currentMode, setCurrentMode] = useState3("full");
   const [confirmProcessing, setConfirmProcessing] = useState3(false);
   const [modeError, setModeError] = useState3(null);
+  const [createSessionPatch, setCreateSessionPatch] = useState3(void 0);
+  const [cardBootstrapPending, setCardBootstrapPending] = useState3(false);
+  const [deferredCardOpen, setDeferredCardOpen] = useState3(false);
   const autoCheckoutAttempted = useRef3(false);
   const onCompleteRef = useRef3(onComplete);
   onCompleteRef.current = onComplete;
   const onErrorRef = useRef3(onError);
   onErrorRef.current = onError;
+  const onDeclineRef = useRef3(onDecline);
+  onDeclineRef.current = onDecline;
   const onSessionCompletedRef = useRef3(onSessionCompleted);
   onSessionCompletedRef.current = onSessionCompleted;
+  const effectiveCreateSession = useMemo3(
+    () => createSessionParams ? mergeInlineSessionPatch(createSessionParams, createSessionPatch) : void 0,
+    [createSessionParams, createSessionPatch]
+  );
+  const emitDecline = useCallback2(
+    (method, input, overrides) => {
+      onDeclineRef.current?.(buildDeclineEvent(method, input, overrides));
+    },
+    []
+  );
   const processPaymentForMode = useCallback2(
     async (sess) => {
       const baseUrl = resolvedBillingUrl.replace(/\/+$/, "");
@@ -1430,9 +1674,13 @@ function FloPayCheckout({
           // No client secret available
         };
       }
-      throw new FloPayError2(
+      throw new FloPayError3(
         json?.message ?? "Payment failed. Please try again.",
-        "api_error"
+        "api_error",
+        {
+          code: json?.code ?? json?.gatewayErrorCode,
+          declineCode: json?.declineCode ?? json?.gatewayDeclineReason
+        }
       );
     },
     [resolvedBillingUrl, resolvedSessionId]
@@ -1451,6 +1699,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")) {
@@ -1473,6 +1724,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" });
@@ -1480,16 +1734,24 @@ function FloPayCheckout({
       }
       return false;
     },
-    [resolvedBillingUrl, resolvedSessionId]
+    [resolvedBillingUrl, resolvedSessionId, emitDecline]
   );
   const inflightRef = useRef3(/* @__PURE__ */ new Map());
   const initializedHashRef = useRef3(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;
@@ -1499,138 +1761,167 @@ function FloPayCheckout({
     return `flopay_session_${Math.abs(h).toString(36)}`;
   }
   const createSessionHash = useMemo3(
-    () => 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 = useRef3(effectiveCreateSession);
+  createSessionParamsRef.current = effectiveCreateSession;
+  useEffect4(() => {
+    setResolvedSessionId(sessionIdProp ?? "");
+  }, [sessionIdProp]);
+  async function resolveInlineSession(params, cacheKey) {
+    ensureInlineSessionReady(params);
+    const api = new 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 = useCallback2(
+    async (patch) => {
+      const baseParams = createSessionParamsRef.current;
+      if (!baseParams) {
+        throw new FloPayError3("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 FloPayError3(
+          "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
+          "validation_error"
+        );
+      }
+      const instance = await loadFloPay(publishableKey, {
+        billingApiUrl: resolvedBillingUrl,
+        locale
+      });
+      flopayRef.current = instance;
+      setFloPay(instance);
+      initializedHashRef.current = cacheKey;
+      setIsLoading(false);
+      return resolved;
+    },
+    [fallbackPublishableKey, locale, resolvedBillingUrl]
   );
-  const createSessionParamsRef = useRef3(createSessionParams);
-  createSessionParamsRef.current = createSessionParams;
+  const handleDeferredCardButtonClick = useCallback2(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 FloPayError3(
+          "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 FloPayError3 ? err : new FloPayError3(
+        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
+  ]);
   useEffect4(() => {
     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 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 FloPayError2(
-              "No publishable key found. Provide fallbackPublishableKey or ensure the session includes gatewayData.publishableKey.",
-              "validation_error"
-            );
-          }
-          const instance = await 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 FloPayError2 ? err : new FloPayError2(err instanceof Error ? err.message : "Failed to create session", "api_error");
+          const floPayErr = err instanceof FloPayError3 ? err : new FloPayError3(err instanceof Error ? err.message : "Failed to create session", "api_error");
           setLoadError(floPayErr);
         }
       })();
@@ -1648,7 +1939,7 @@ function FloPayCheckout({
         const sess = result.data.session ?? null;
         setSession(sess);
         if (!sess) {
-          throw new FloPayError2("No session data returned", "api_error");
+          throw new FloPayError3("No session data returned", "api_error");
         }
         if (sess.status === "complete") {
           setIsLoading(false);
@@ -1687,7 +1978,7 @@ function FloPayCheckout({
         if (!cancelled) setIsLoading(false);
       } catch (err) {
         if (cancelled) return;
-        const floPayErr = err instanceof FloPayError2 ? err : new FloPayError2(err instanceof Error ? err.message : "Failed to initialize checkout", "api_error");
+        const floPayErr = err instanceof FloPayError3 ? err : new FloPayError3(err instanceof Error ? err.message : "Failed to initialize checkout", "api_error");
         setLoadError(floPayErr);
         setIsLoading(false);
       }
@@ -1699,7 +1990,7 @@ function FloPayCheckout({
       }
       if (!publishableKey) publishableKey = fallbackPublishableKey;
       if (!publishableKey) {
-        throw new FloPayError2(
+        throw new FloPayError3(
           "No publishable key found in session response. Provide a fallbackPublishableKey prop or ensure the session includes gatewayData.publishableKey.",
           "validation_error"
         );
@@ -1715,7 +2006,7 @@ function FloPayCheckout({
     return () => {
       cancelled = true;
     };
-  }, [resolvedSessionId, createSessionHash, resolvedBillingUrl, fallbackPublishableKey, locale, checkoutModeProp]);
+  }, [resolvedSessionId, createSessionHash, checkoutModeProp, deferInlineSessionUntilCardClick, bootstrapInlineSession]);
   const handleConfirmCheckout = useCallback2(async () => {
     if (confirmProcessing || !session) return;
     setConfirmProcessing(true);
@@ -1730,17 +2021,18 @@ function FloPayCheckout({
         setCurrentMode("full");
       }
     } catch (err) {
-      const floPayErr = err instanceof FloPayError2 ? err : new FloPayError2(
+      const floPayErr = err instanceof FloPayError3 ? err : new FloPayError3(
         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 = useMemo3(() => {
     if (!unified || !session) return void 0;
     const opts = {
@@ -1766,6 +2058,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__ */ jsx5(Fragment3, { children: loadingNode });
     if (layout === "buttons") {
@@ -1794,7 +2088,7 @@ function FloPayCheckout({
       /* @__PURE__ */ jsx5("style", { children: `@keyframes spin { to { transform: rotate(360deg); } }` })
     ] });
   }
-  if (loadError) {
+  if (loadError && !shouldKeepDeferredInterimVisible) {
     if (errorNode) return /* @__PURE__ */ jsx5(Fragment3, { children: errorNode(loadError) });
     return /* @__PURE__ */ jsx5(
       "div",
@@ -1809,17 +2103,23 @@ function FloPayCheckout({
       }
     );
   }
-  if ((!flopay || !providerOptions) && createSessionParams && layout === "buttons") {
+  if (shouldShowInterimButtons) {
     return /* @__PURE__ */ jsx5(CheckoutContext.Provider, { value: checkoutValue, children: /* @__PURE__ */ jsx5(
       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
       }
     ) });
   }
@@ -1900,6 +2200,7 @@ function FloPayCheckout({
         currency: session?.currency?.toLowerCase() ?? "usd",
         onComplete,
         onError,
+        onDecline,
         showPayPal,
         showApplePay,
         showGooglePay,
@@ -1907,11 +2208,15 @@ function FloPayCheckout({
         buttonsTheme,
         buttonsStyles,
         cardButtonContent,
+        cardBackButtonContent,
+        cardTitleContent,
         onButtonClick,
+        onBeforeButtonClick,
         enableAVS,
         avsLayout,
         country: session?.customer?.country,
         zip: session?.customer?.zip,
+        initialCardOpen: deferredCardOpen,
         submitLabel,
         className
       }
@@ -1944,14 +2249,26 @@ function SessionInjector({
 }
 function InterimButtonsView({
   onButtonClick,
+  onCardButtonClick,
+  cardLoading = false,
+  cardOpen,
+  errorMessage,
   showPayPal,
   showApplePay,
   showGooglePay,
   buttonsTheme,
   buttonsStyles: stylesOverride,
-  cardButtonContent
+  cardButtonContent,
+  cardBackButtonContent,
+  cardTitleContent
 }) {
   const [showCardForm, setShowCardForm] = useState3(false);
+  const isCardOpenControlled = typeof cardOpen === "boolean";
+  useEffect4(() => {
+    if (isCardOpenControlled) {
+      setShowCardForm(cardOpen);
+    }
+  }, [cardOpen, isCardOpenControlled]);
   const bStyles = useMemo3(() => {
     const base = resolveButtonsLayoutTheme2(buttonsTheme);
     if (!stylesOverride) return base;
@@ -1960,6 +2277,8 @@ function InterimButtonsView({
       ...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 }
     };
@@ -1973,6 +2292,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__ */ jsxs3("div", { style: {
       backgroundColor: bStyles.cardFormContainer?.backgroundColor ?? "white",
       borderRadius: "8px",
@@ -1985,19 +2306,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: [
@@ -2011,11 +2339,11 @@ function InterimButtonsView({
                 backgroundColor: "#f3f4f6",
                 ...bStyles.backButtonIcon
               }, children: /* @__PURE__ */ jsx5("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round", children: /* @__PURE__ */ jsx5("path", { d: "M15 18l-6-6 6-6" }) }) }),
-              "Go back"
+              /* @__PURE__ */ jsx5(BackButtonContentSlot, { content: cardBackButtonContent })
             ]
           }
         ),
-        /* @__PURE__ */ jsx5("div", { style: {
+        hideTitle ? /* @__PURE__ */ jsx5("div", { style: { flex: 1 } }) : /* @__PURE__ */ jsx5("div", { style: {
           flex: 1,
           textAlign: "center",
           fontWeight: 600,
@@ -2023,7 +2351,7 @@ function InterimButtonsView({
           color: "#262833",
           paddingRight: 80,
           ...bStyles.title
-        }, children: "Secure card checkout" })
+        }, children: /* @__PURE__ */ jsx5(TitleContentSlot, { content: cardTitleContent }) })
       ] }),
       /* @__PURE__ */ jsx5("div", { style: { backgroundColor: inputBg, border: `1px solid ${inputBorder}`, borderTopLeftRadius: 8, borderTopRightRadius: 8, padding: 12, height: 45 }, children: /* @__PURE__ */ jsx5("div", { style: { width: "60%", height: 14, borderRadius: 4, background: "#e5e7eb", animation: "flopay-interim-pulse 1.5s ease-in-out infinite" } }) }),
       /* @__PURE__ */ jsxs3("div", { style: { display: "flex" }, children: [
@@ -2057,10 +2385,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",
@@ -2070,7 +2404,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",
@@ -2078,6 +2412,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) => {
@@ -2089,12 +2424,29 @@ function InterimButtonsView({
         children: /* @__PURE__ */ jsx5(CardButtonContentSlot, { content: cardButtonContent })
       }
     ),
+    errorMessage && /* @__PURE__ */ jsxs3("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__ */ jsx5("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", style: { flexShrink: 0 }, children: /* @__PURE__ */ jsx5("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__ */ jsx5("style", { children: `@keyframes flopay-interim-pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.4; } }` })
   ] });
 }
 
 // src/checkout-form.tsx
-import { FloPayError as FloPayError3 } from "@flopay/shared";
+import { FloPayError as FloPayError4 } from "@flopay/shared";
 import { forwardRef as forwardRef2, useCallback as useCallback3, useEffect as useEffect5, useImperativeHandle as useImperativeHandle2, useState as useState4 } from "react";
 import { Fragment as Fragment4, jsx as jsx6, jsxs as jsxs4 } from "react/jsx-runtime";
 var WALLET_RESUME_KEY2 = "flopay_wallet_resume";
@@ -2110,6 +2462,7 @@ function CheckoutFormInner({
   userId,
   onComplete,
   onError,
+  onDecline,
   onTokenizedBody,
   layout = "auto",
   submitLabel = "Pay",
@@ -2141,6 +2494,12 @@ function CheckoutFormInner({
     },
     [onErrorChange]
   );
+  const emitDecline = useCallback3(
+    (input, overrides) => {
+      onDecline?.(buildDeclineEvent("card", input, overrides));
+    },
+    [onDecline]
+  );
   const processPaymentInternal = useCallback3(
     async (tokenizedBody) => {
       setProcessing(true);
@@ -2187,6 +2546,7 @@ function CheckoutFormInner({
             if (result.error) {
               updateError(result.error.message);
               onError?.(result.error);
+              emitDecline(result.error);
               return;
             }
             if (result.status === "succeeded" || result.status === "processing") {
@@ -2221,13 +2581,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 = useCallback3(
     (tokenizedBody) => {
@@ -2251,6 +2615,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,
@@ -2264,7 +2629,7 @@ function CheckoutFormInner({
         setIs3DSActive(false);
       }
     }
-  }), [flopay, dispatchTokenizedBody, onError, updateError]);
+  }), [flopay, dispatchTokenizedBody, onError, updateError, emitDecline]);
   useEffect5(() => {
     if (typeof window === "undefined") return;
     const stored = localStorage.getItem(WALLET_RESUME_KEY2);
@@ -2302,7 +2667,7 @@ function CheckoutFormInner({
           return;
         }
         if (!sessionId || !email) {
-          throw new FloPayError3("Missing sessionId or email", "validation_error");
+          throw new FloPayError4("Missing sessionId or email", "validation_error");
         }
         const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
           method: "POST",
@@ -2314,16 +2679,18 @@ function CheckoutFormInner({
             isPaypal: false
           })
         });
-        if (!intentResponse.ok) throw new FloPayError3("Failed to create payment intent", "api_error");
+        if (!intentResponse.ok) throw new FloPayError4("Failed to create payment intent", "api_error");
         const intentJson = await intentResponse.json();
         const intentClientSecret = intentJson.data?.id;
-        if (!intentClientSecret) throw new FloPayError3("No client_secret in payment intent response", "api_error");
+        if (!intentClientSecret) throw new FloPayError4("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({
@@ -2340,7 +2707,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__ */ jsxs4("form", { onSubmit: handleSubmit, className, style: { position: "relative" }, children: [
@@ -2372,7 +2739,7 @@ function CheckoutFormInner({
 }
 
 // src/paypal-button.tsx
-import { FloPayError as FloPayError4 } from "@flopay/shared";
+import { FloPayError as FloPayError5 } from "@flopay/shared";
 import { useCallback as useCallback4, useEffect as useEffect6, useRef as useRef4, useState as useState5 } from "react";
 import { Fragment as Fragment5, jsx as jsx7, jsxs as jsxs5 } from "react/jsx-runtime";
 function PayPalButton({
@@ -2492,7 +2859,7 @@ function PayPalButton({
       setSubmitting(true);
       onErrorChange?.(null);
       if (!sessionId || !email) {
-        throw new FloPayError4("Missing sessionId or email for PayPal payment", "validation_error");
+        throw new FloPayError5("Missing sessionId or email for PayPal payment", "validation_error");
       }
       const intentResponse = await fetch(`${baseUrl}/v1/checkouts/payments/intents`, {
         method: "POST",
@@ -2504,10 +2871,10 @@ function PayPalButton({
           isPaypal: "true"
         })
       });
-      if (!intentResponse.ok) throw new FloPayError4("Failed to create payment intent", "api_error");
+      if (!intentResponse.ok) throw new FloPayError5("Failed to create payment intent", "api_error");
       const intentJson = await intentResponse.json();
       const intentClientSecret = intentJson.data?.id;
-      if (!intentClientSecret) throw new FloPayError4("No client_secret in response", "api_error");
+      if (!intentClientSecret) throw new FloPayError5("No client_secret in response", "api_error");
       const result = await flopay.confirmPayment({
         clientSecret: intentClientSecret,
         returnUrl: window.location.href