@flopay/react 1.0.3 → 1.1.3

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -10,9 +10,9 @@ interface FloPayProviderProps {
     /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
     flopay: Promise<FloPay> | FloPay;
     /**
-     * Optional dedicated `FloPay` instance for PayPal, loaded with
-     * `gatewayData.paypalPublishableKey`. When omitted or `null`, PayPal is
-     * disabled (the button is not rendered).
+     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
+     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
+     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
      */
     paypalFlopay?: Promise<FloPay> | FloPay | null;
     /** Optional configuration applied when creating the elements group. */
@@ -84,6 +84,12 @@ interface FloPayCheckoutProps {
     showApplePay?: boolean;
     /** Whether to show Google Pay button (default: true). Only renders on supported devices. */
     showGooglePay?: boolean;
+    /**
+     * Enables on-screen diagnostic panels (PayPal gate decision, DirectPayPalButton
+     * lifecycle). Intended for debugging in-app browsers (Facebook, Instagram, etc.)
+     * where remote console access is impractical. Off by default.
+     */
+    debug?: boolean;
     /** Layout mode: 'default' (all visible) or 'buttons' (PayPal/wallets + expandable card form). */
     layout?: 'default' | 'buttons';
     /** Theme preset for the buttons layout: 'default', 'minimal', 'rounded', or 'dark'. */
@@ -148,8 +154,8 @@ interface FloPayCheckoutProps {
     onSessionCompleted?: (successUrl: string) => void;
     /**
      * @deprecated No longer used. The Stripe publishable key is sourced exclusively
-     * from the checkout session's `gatewayData.publishableKey`. Accepted only for
-     * backward compatibility with older consumer code — the value is ignored.
+     * from the checkout session's `gateways.stripe.publishableKey`. Accepted only
+     * for backward compatibility with older consumer code — the value is ignored.
      */
     fallbackPublishableKey?: string;
 }
@@ -170,7 +176,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, debug, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -180,9 +186,9 @@ declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: creat
  */
 declare function useFloPay(): FloPay | null;
 /**
- * Returns the dedicated PayPal `FloPay` instance (loaded with
- * `gatewayData.paypalPublishableKey`), or `null` if PayPal is disabled
- * for this session.
+ * Returns the Stripe `FloPay` instance dedicated to the Stripe-rendered
+ * PayPal fallback, or `null` if PayPal is disabled for this session. Direct
+ * PayPal (`gateways.paypal`) does not use this instance.
  *
  * Must be called within a `<FloPayProvider>`.
  */
@@ -480,6 +486,26 @@ interface SplitCardFormProps {
     currency?: string;
     /** Render the card form expanded on first paint when `layout="buttons"`. */
     initialCardOpen?: boolean;
+    /**
+     * Direct PayPal gateway configuration. When provided, PayPal renders via
+     * the official PayPal JS SDK (in-app browser compliant) instead of via
+     * Stripe's ExpressCheckoutElement. Selection is mutually exclusive:
+     * setting this disables the Stripe-rendered PayPal path automatically.
+     */
+    directPaypal?: {
+        clientId: string;
+        environment?: GatewayEnvironment;
+    };
+    /** Whether the active session represents a subscription (drives direct PayPal intent). */
+    isSubscription?: boolean;
+    /** Backing session — forwarded to direct-PayPal so it can populate accountData. */
+    session?: CheckoutSession | null;
+    /**
+     * Enables on-screen diagnostic panels for the PayPal/wallet gating decision
+     * and the `DirectPayPalButton` lifecycle. Intended for debugging in-app
+     * browsers where remote console access is impractical. Off by default.
+     */
+    debug?: boolean;
 }
 /**
  * Split card checkout form matching `checkout/StripeCardForm`:
@@ -545,6 +571,110 @@ interface PayPalButtonProps {
  */
 declare function PayPalButton({ sessionId, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
 
+/**
+ * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
+ * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
+ * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
+ */
+interface DirectPayPalTokenizedOverrides {
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+}
+/**
+ * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
+ * dispatcher. Direct PayPal completes via the backend's process endpoint and
+ * never produces a Stripe PaymentIntent, so we still forward a synthetic
+ * `TokenizedBody` describing the captured order, optionally with the
+ * session/account patch captured at click-time.
+ */
+type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
+/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
+interface DirectPayPalBeforeButtonClickResult {
+    proceed: boolean;
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+}
+/**
+ * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
+ * consumer patch the session/account before PayPal creates the order, and lets
+ * them abort the click entirely by returning `proceed: false`.
+ */
+type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
+interface DirectPayPalButtonProps {
+    /** Checkout session ID. */
+    sessionId: string;
+    /** Billing API base URL. */
+    billingApiUrl: string;
+    /** Buyer email. */
+    email?: string;
+    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
+    clientId: string;
+    /** Gateway environment, drives the sandbox/live SDK script. */
+    environment?: GatewayEnvironment;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Whether the session is a subscription (drives intent + flow selection). */
+    isSubscription: boolean;
+    /**
+     * If provided, called with the tokenized body once PayPal capture
+     * completes. When omitted, the component processes payment internally.
+     */
+    onTokenizedBody?: DirectPayPalTokenizedHandler;
+    /** Called when the full self-contained payment flow succeeds. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** Decline emitter (mirrors SplitCardForm semantics). */
+    onDecline?: (decline: DeclineEvent) => void;
+    /** External processing state. */
+    isProcessing?: boolean;
+    /** Notify the parent of the loading state for placeholder swapping. */
+    onLoadStateChange?: (ready: boolean) => void;
+    /** Tracks button-click for analytics. */
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Click-time gate (runs before PayPal creates the order). When provided, the
+     * returned patch is applied to the in-flight create-intent and tokenized
+     * dispatch so callers using `onBeforeButtonClick` see the same session/email
+     * the Stripe-rendered PayPal flow does.
+     */
+    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
+    /** Backing session — used for self-contained accountData population. */
+    session?: CheckoutSession | null;
+    /**
+     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
+     * true) to bind the button to. When set, the button skips its usual
+     * `POST /v1/checkouts/payments/intents` round-trip on click and feeds this
+     * id straight into PayPal's create-order / create-subscription callback.
+     *
+     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
+     * creates a fresh PayPal order after a stalled process attempt and returns
+     * its id; the SDK re-renders this button bound to that id so the buyer can
+     * confirm with one more click without the backend re-creating the order on
+     * each retry.
+     *
+     * Changing this value remounts the PayPal SDK so the new createOrder
+     * binding takes effect (PayPal's render() options aren't live-updatable).
+     */
+    existingOrderId?: string;
+    /**
+     * When true, renders an on-screen lifecycle tracer panel above the button
+     * (mount, loadScript, eligibility, render, errors). Intended for debugging
+     * in-app browsers (Facebook IAB, etc.) where remote console access is
+     * impractical. Off by default — leave disabled in production.
+     */
+    debug?: boolean;
+}
+/**
+ * Direct PayPal renderer powered by the official PayPal JS SDK.
+ *
+ * Renders inside Facebook / Instagram / Meta in-app browsers where Stripe's
+ * PayPal ExpressCheckoutElement breaks. Selection between this and the Stripe-
+ * rendered PayPal happens at the caller site based on whether the session
+ * advertises `gateways.paypal.publishableKey`.
+ */
+declare function DirectPayPalButton({ sessionId, billingApiUrl, email, clientId, environment, currency, isSubscription, onTokenizedBody, onComplete, onErrorChange, onDecline, isProcessing, onLoadStateChange, onButtonClick, runBeforeButtonClick, session, existingOrderId, debug, }: DirectPayPalButtonProps): React.ReactElement | null;
+
 interface FloPayAutomaticPaymentSuccessEvent {
     result: PaymentResult;
     session: CheckoutSession | null;
@@ -576,4 +706,4 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
 }
 declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId, checkoutMethod, clientId, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
 
-export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };
+export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody, AVSFieldConfig, GatewayEnvironment, CheckoutItem, CheckoutSubscription, ButtonsLayoutTheme, ButtonsLayoutStyles } from '@flopay/shared';
 export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -10,9 +10,9 @@ interface FloPayProviderProps {
     /** A `FloPay` instance or a promise that resolves to one (from `loadFloPay()`). */
     flopay: Promise<FloPay> | FloPay;
     /**
-     * Optional dedicated `FloPay` instance for PayPal, loaded with
-     * `gatewayData.paypalPublishableKey`. When omitted or `null`, PayPal is
-     * disabled (the button is not rendered).
+     * Optional Stripe `FloPay` instance used to drive the Stripe-rendered PayPal
+     * fallback. When omitted or `null`, the Stripe-rendered PayPal button is
+     * not rendered. Direct PayPal (`gateways.paypal`) does not use this prop.
      */
     paypalFlopay?: Promise<FloPay> | FloPay | null;
     /** Optional configuration applied when creating the elements group. */
@@ -84,6 +84,12 @@ interface FloPayCheckoutProps {
     showApplePay?: boolean;
     /** Whether to show Google Pay button (default: true). Only renders on supported devices. */
     showGooglePay?: boolean;
+    /**
+     * Enables on-screen diagnostic panels (PayPal gate decision, DirectPayPalButton
+     * lifecycle). Intended for debugging in-app browsers (Facebook, Instagram, etc.)
+     * where remote console access is impractical. Off by default.
+     */
+    debug?: boolean;
     /** Layout mode: 'default' (all visible) or 'buttons' (PayPal/wallets + expandable card form). */
     layout?: 'default' | 'buttons';
     /** Theme preset for the buttons layout: 'default', 'minimal', 'rounded', or 'dark'. */
@@ -148,8 +154,8 @@ interface FloPayCheckoutProps {
     onSessionCompleted?: (successUrl: string) => void;
     /**
      * @deprecated No longer used. The Stripe publishable key is sourced exclusively
-     * from the checkout session's `gatewayData.publishableKey`. Accepted only for
-     * backward compatibility with older consumer code — the value is ignored.
+     * from the checkout session's `gateways.stripe.publishableKey`. Accepted only
+     * for backward compatibility with older consumer code — the value is ignored.
      */
     fallbackPublishableKey?: string;
 }
@@ -170,7 +176,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, onFullNameChange, onCountryChange, onZipChange, showPayPal, showApplePay, showGooglePay, debug, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, showSecurityFooter, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, initialErrorMessage, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -180,9 +186,9 @@ declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: creat
  */
 declare function useFloPay(): FloPay | null;
 /**
- * Returns the dedicated PayPal `FloPay` instance (loaded with
- * `gatewayData.paypalPublishableKey`), or `null` if PayPal is disabled
- * for this session.
+ * Returns the Stripe `FloPay` instance dedicated to the Stripe-rendered
+ * PayPal fallback, or `null` if PayPal is disabled for this session. Direct
+ * PayPal (`gateways.paypal`) does not use this instance.
  *
  * Must be called within a `<FloPayProvider>`.
  */
@@ -480,6 +486,26 @@ interface SplitCardFormProps {
     currency?: string;
     /** Render the card form expanded on first paint when `layout="buttons"`. */
     initialCardOpen?: boolean;
+    /**
+     * Direct PayPal gateway configuration. When provided, PayPal renders via
+     * the official PayPal JS SDK (in-app browser compliant) instead of via
+     * Stripe's ExpressCheckoutElement. Selection is mutually exclusive:
+     * setting this disables the Stripe-rendered PayPal path automatically.
+     */
+    directPaypal?: {
+        clientId: string;
+        environment?: GatewayEnvironment;
+    };
+    /** Whether the active session represents a subscription (drives direct PayPal intent). */
+    isSubscription?: boolean;
+    /** Backing session — forwarded to direct-PayPal so it can populate accountData. */
+    session?: CheckoutSession | null;
+    /**
+     * Enables on-screen diagnostic panels for the PayPal/wallet gating decision
+     * and the `DirectPayPalButton` lifecycle. Intended for debugging in-app
+     * browsers where remote console access is impractical. Off by default.
+     */
+    debug?: boolean;
 }
 /**
  * Split card checkout form matching `checkout/StripeCardForm`:
@@ -545,6 +571,110 @@ interface PayPalButtonProps {
  */
 declare function PayPalButton({ sessionId, billingApiUrl, email, userId, firstName, lastName, chv, onTokenizedBody, onComplete, onErrorChange, isProcessing, }: PayPalButtonProps): React.ReactElement;
 
+/**
+ * Overrides that `SplitCardForm`'s tokenized-body dispatcher uses to apply a
+ * `runBeforeButtonClick` patch to the in-flight processPayment call. Kept in
+ * sync structurally with `TokenizedBodyOverrides` in `split-card-form.tsx`.
+ */
+interface DirectPayPalTokenizedOverrides {
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+}
+/**
+ * Internal handler signature aligned with `SplitCardForm`'s tokenized-body
+ * dispatcher. Direct PayPal completes via the backend's process endpoint and
+ * never produces a Stripe PaymentIntent, so we still forward a synthetic
+ * `TokenizedBody` describing the captured order, optionally with the
+ * session/account patch captured at click-time.
+ */
+type DirectPayPalTokenizedHandler = (body: TokenizedBody, overrides?: DirectPayPalTokenizedOverrides) => void;
+/** Click-time `runBeforeButtonClick` result, structurally compatible with `SplitCardForm`. */
+interface DirectPayPalBeforeButtonClickResult {
+    proceed: boolean;
+    accountPatch?: InlineSessionPatch['account'];
+    sessionId?: string;
+}
+/**
+ * Click-time gate. Mirrors `RunBeforeButtonClick` in `SplitCardForm`: lets the
+ * consumer patch the session/account before PayPal creates the order, and lets
+ * them abort the click entirely by returning `proceed: false`.
+ */
+type DirectPayPalRunBeforeButtonClick = (method: CheckoutButtonMethod) => Promise<DirectPayPalBeforeButtonClickResult>;
+interface DirectPayPalButtonProps {
+    /** Checkout session ID. */
+    sessionId: string;
+    /** Billing API base URL. */
+    billingApiUrl: string;
+    /** Buyer email. */
+    email?: string;
+    /** PayPal client identifier (`gateways.paypal.publishableKey`). */
+    clientId: string;
+    /** Gateway environment, drives the sandbox/live SDK script. */
+    environment?: GatewayEnvironment;
+    /** ISO 4217 currency code. */
+    currency: string;
+    /** Whether the session is a subscription (drives intent + flow selection). */
+    isSubscription: boolean;
+    /**
+     * If provided, called with the tokenized body once PayPal capture
+     * completes. When omitted, the component processes payment internally.
+     */
+    onTokenizedBody?: DirectPayPalTokenizedHandler;
+    /** Called when the full self-contained payment flow succeeds. */
+    onComplete?: (result: PaymentResult) => void;
+    /** Called when an error occurs. */
+    onErrorChange?: (error: string | null) => void;
+    /** Decline emitter (mirrors SplitCardForm semantics). */
+    onDecline?: (decline: DeclineEvent) => void;
+    /** External processing state. */
+    isProcessing?: boolean;
+    /** Notify the parent of the loading state for placeholder swapping. */
+    onLoadStateChange?: (ready: boolean) => void;
+    /** Tracks button-click for analytics. */
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Click-time gate (runs before PayPal creates the order). When provided, the
+     * returned patch is applied to the in-flight create-intent and tokenized
+     * dispatch so callers using `onBeforeButtonClick` see the same session/email
+     * the Stripe-rendered PayPal flow does.
+     */
+    runBeforeButtonClick?: DirectPayPalRunBeforeButtonClick;
+    /** Backing session — used for self-contained accountData population. */
+    session?: CheckoutSession | null;
+    /**
+     * Pre-existing PayPal Order id (or Subscription id when `isSubscription` is
+     * true) to bind the button to. When set, the button skips its usual
+     * `POST /v1/checkouts/payments/intents` round-trip on click and feeds this
+     * id straight into PayPal's create-order / create-subscription callback.
+     *
+     * Used by `SplitCardForm`'s `paypal_direct_required` retry path: backend
+     * creates a fresh PayPal order after a stalled process attempt and returns
+     * its id; the SDK re-renders this button bound to that id so the buyer can
+     * confirm with one more click without the backend re-creating the order on
+     * each retry.
+     *
+     * Changing this value remounts the PayPal SDK so the new createOrder
+     * binding takes effect (PayPal's render() options aren't live-updatable).
+     */
+    existingOrderId?: string;
+    /**
+     * When true, renders an on-screen lifecycle tracer panel above the button
+     * (mount, loadScript, eligibility, render, errors). Intended for debugging
+     * in-app browsers (Facebook IAB, etc.) where remote console access is
+     * impractical. Off by default — leave disabled in production.
+     */
+    debug?: boolean;
+}
+/**
+ * Direct PayPal renderer powered by the official PayPal JS SDK.
+ *
+ * Renders inside Facebook / Instagram / Meta in-app browsers where Stripe's
+ * PayPal ExpressCheckoutElement breaks. Selection between this and the Stripe-
+ * rendered PayPal happens at the caller site based on whether the session
+ * advertises `gateways.paypal.publishableKey`.
+ */
+declare function DirectPayPalButton({ sessionId, billingApiUrl, email, clientId, environment, currency, isSubscription, onTokenizedBody, onComplete, onErrorChange, onDecline, isProcessing, onLoadStateChange, onButtonClick, runBeforeButtonClick, session, existingOrderId, debug, }: DirectPayPalButtonProps): React.ReactElement | null;
+
 interface FloPayAutomaticPaymentSuccessEvent {
     result: PaymentResult;
     session: CheckoutSession | null;
@@ -576,4 +706,4 @@ interface FloPayAutomaticPaymentButtonProps extends Omit<React.ButtonHTMLAttribu
 }
 declare function FloPayAutomaticPaymentButton({ sessionId, createSession, paymentMethodId, checkoutMethod, clientId, items, subscriptions, account, successUrl, cancelUrl, couponCodes, tagsData, utmMetadata, billingApiUrl, locale, buttonsTheme, buttonsStyles: stylesOverride, onSuccess, onError, onDecline, children, disabled, type, style, ...buttonProps }: FloPayAutomaticPaymentButtonProps): react_jsx_runtime.JSX.Element;
 
-export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };
+export { AddressElement, CardCvcElement, CardElement, CardExpiryElement, CardNumberElement, CheckoutForm, type CheckoutFormProps, type CheckoutFormRef, type CheckoutState, DirectPayPalButton, type DirectPayPalButtonProps, type ElementComponentProps, FloPayAutomaticPaymentButton, type FloPayAutomaticPaymentButtonProps, type FloPayAutomaticPaymentSuccessEvent, FloPayCheckout, type FloPayCheckoutProps, FloPayProvider, type FloPayProviderProps, PayPalButton, type PayPalButtonProps, PaymentElement, SplitCardForm, type SplitCardFormProps, type SplitCardFormRef, useCheckout, useElements, useFloPay, usePayPalFloPay };