@flopay/react 0.3.11 → 0.3.13

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import React from 'react';
 import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, FloPayError, PaymentResult, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody } from '@flopay/shared';
+export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 
 /** Props for the `FloPayProvider` component. */
 interface FloPayProviderProps {
@@ -45,7 +46,7 @@ interface FloPayCheckoutProps {
      * The component POSTs to the billing API, gets the full session back, and renders the form.
      * Alternative to `sessionId` (provide one or the other).
      */
-    createSession?: _flopay_shared.InlineSessionParams;
+    createSession?: InlineSessionDraft;
     /** Billing API base URL. Defaults to the shared `BILLING_API_URL` constant. */
     billingApiUrl?: string;
     /** Visual appearance for payment elements. */
@@ -69,6 +70,8 @@ interface FloPayCheckoutProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /** Whether to show the PayPal button (default: true). */
     showPayPal?: boolean;
     /** Whether to show Apple Pay button (default: true). Only renders on supported devices. */
@@ -91,7 +94,14 @@ interface FloPayCheckoutProps {
      * Called when a payment method button is clicked.
      * `method`: `'card'` | `'paypal'` | `'apple_pay'` | `'google_pay'`
      */
-    onButtonClick?: (method: string) => void;
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Called before the credit/debit card button continues.
+     * Card only: this does not run for PayPal or wallet buttons.
+     * In `layout="buttons"` with `createSession`, the returned patch is merged
+     * into the inline session params before the real card session is created.
+     */
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => void | false | Promise<void | false | InlineSessionPatch> | InlineSessionPatch;
     /**
      * Enable AVS (Address Verification). Shows country dropdown + ZIP/postcode input
      * in the card form. When enabled, billing_details are passed to Stripe for AVS checks.
@@ -142,7 +152,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, fallbackPublishableKey, loading: loadingNode, error: errorNode, onComplete, onError, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, onButtonClick, enableAVS, avsLayout, submitLabel, className, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, fallbackPublishableKey, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -251,6 +261,8 @@ interface CheckoutFormProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /**
      * **Override**: If provided, the form tokenizes the card and confirms
      * the payment, but delegates backend submission to the caller.
@@ -310,6 +322,7 @@ interface CheckoutFormProps {
  */
 declare const CheckoutForm: React.ForwardRefExoticComponent<CheckoutFormProps & React.RefAttributes<CheckoutFormRef>>;
 
+type MaybePromise<T> = T | Promise<T>;
 /** Methods exposed via ref for external 3DS handling. */
 interface SplitCardFormRef {
     handleNextAction: (clientSecret: string) => Promise<void>;
@@ -328,6 +341,8 @@ interface SplitCardFormProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /**
      * **Override**: If provided, delegates backend submission to the caller.
      * When omitted, processes internally (calls processPayment + handles 3DS).
@@ -392,7 +407,12 @@ interface SplitCardFormProps {
      * Called when a payment method button is clicked.
      * `method`: `'card'` | `'paypal'` | `'apple_pay'` | `'google_pay'`
      */
-    onButtonClick?: (method: string) => void;
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Called before the credit/debit card button continues.
+     * Card only: this does not run for PayPal or wallet buttons.
+     */
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<void | false | InlineSessionPatch>;
     /**
      * Enable AVS (Address Verification). Shows country dropdown + ZIP/postcode input.
      * When enabled, billing_details are passed to Stripe's createPaymentMethod for AVS checks.
@@ -412,6 +432,8 @@ interface SplitCardFormProps {
     totalAmount?: number;
     /** Currency code (used for PayPal Elements config). */
     currency?: string;
+    /** Render the card form expanded on first paint when `layout="buttons"`. */
+    initialCardOpen?: boolean;
 }
 /**
  * Split card checkout form matching `checkout/StripeCardForm`:

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import React from 'react';
 import { FloPay, FloPayElements } from '@flopay/js';
 import * as _flopay_shared from '@flopay/shared';
-import { FloPayAppearance, FloPayError, PaymentResult, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody } from '@flopay/shared';
+import { FloPayAppearance, InlineSessionDraft, FloPayError, PaymentResult, DeclineEvent, CheckoutButtonMethod, BeforeButtonClickEvent, InlineSessionPatch, CheckoutMode, CheckoutSession, ElementOptions, ElementChangeEvent, TokenizedBody } from '@flopay/shared';
+export { BeforeButtonClickEvent, CheckoutButtonMethod, DeclineEvent, InlineSessionDraft, InlineSessionPatch } from '@flopay/shared';
 
 /** Props for the `FloPayProvider` component. */
 interface FloPayProviderProps {
@@ -45,7 +46,7 @@ interface FloPayCheckoutProps {
      * The component POSTs to the billing API, gets the full session back, and renders the form.
      * Alternative to `sessionId` (provide one or the other).
      */
-    createSession?: _flopay_shared.InlineSessionParams;
+    createSession?: InlineSessionDraft;
     /** Billing API base URL. Defaults to the shared `BILLING_API_URL` constant. */
     billingApiUrl?: string;
     /** Visual appearance for payment elements. */
@@ -69,6 +70,8 @@ interface FloPayCheckoutProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /** Whether to show the PayPal button (default: true). */
     showPayPal?: boolean;
     /** Whether to show Apple Pay button (default: true). Only renders on supported devices. */
@@ -91,7 +94,14 @@ interface FloPayCheckoutProps {
      * Called when a payment method button is clicked.
      * `method`: `'card'` | `'paypal'` | `'apple_pay'` | `'google_pay'`
      */
-    onButtonClick?: (method: string) => void;
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Called before the credit/debit card button continues.
+     * Card only: this does not run for PayPal or wallet buttons.
+     * In `layout="buttons"` with `createSession`, the returned patch is merged
+     * into the inline session params before the real card session is created.
+     */
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => void | false | Promise<void | false | InlineSessionPatch> | InlineSessionPatch;
     /**
      * Enable AVS (Address Verification). Shows country dropdown + ZIP/postcode input
      * in the card form. When enabled, billing_details are passed to Stripe for AVS checks.
@@ -142,7 +152,7 @@ interface FloPayCheckoutProps {
  * />
  * ```
  */
-declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, fallbackPublishableKey, loading: loadingNode, error: errorNode, onComplete, onError, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, onButtonClick, enableAVS, avsLayout, submitLabel, className, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
+declare function FloPayCheckout({ sessionId: sessionIdProp, createSession: createSessionParams, billingApiUrl, appearance, locale, fallbackPublishableKey, loading: loadingNode, error: errorNode, onComplete, onError, onDecline, showPayPal, showApplePay, showGooglePay, layout, buttonsTheme, buttonsStyles, cardButtonContent, cardBackButtonContent, cardTitleContent, onButtonClick, onBeforeButtonClick, enableAVS, avsLayout, submitLabel, className, children, checkoutMode: checkoutModeProp, confirmLabel, renderConfirmButton, onSessionCompleted, }: FloPayCheckoutProps): React.ReactElement;
 
 /**
  * Returns the current `FloPay` instance, or `null` if the provider
@@ -251,6 +261,8 @@ interface CheckoutFormProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /**
      * **Override**: If provided, the form tokenizes the card and confirms
      * the payment, but delegates backend submission to the caller.
@@ -310,6 +322,7 @@ interface CheckoutFormProps {
  */
 declare const CheckoutForm: React.ForwardRefExoticComponent<CheckoutFormProps & React.RefAttributes<CheckoutFormRef>>;
 
+type MaybePromise<T> = T | Promise<T>;
 /** Methods exposed via ref for external 3DS handling. */
 interface SplitCardFormRef {
     handleNextAction: (clientSecret: string) => Promise<void>;
@@ -328,6 +341,8 @@ interface SplitCardFormProps {
     onComplete?: (result: PaymentResult) => void;
     /** Called when a payment error occurs. */
     onError?: (error: FloPayError) => void;
+    /** Called when a payment is declined or the authentication step fails. */
+    onDecline?: (decline: DeclineEvent) => void;
     /**
      * **Override**: If provided, delegates backend submission to the caller.
      * When omitted, processes internally (calls processPayment + handles 3DS).
@@ -392,7 +407,12 @@ interface SplitCardFormProps {
      * Called when a payment method button is clicked.
      * `method`: `'card'` | `'paypal'` | `'apple_pay'` | `'google_pay'`
      */
-    onButtonClick?: (method: string) => void;
+    onButtonClick?: (method: CheckoutButtonMethod) => void;
+    /**
+     * Called before the credit/debit card button continues.
+     * Card only: this does not run for PayPal or wallet buttons.
+     */
+    onBeforeButtonClick?: (event: BeforeButtonClickEvent) => MaybePromise<void | false | InlineSessionPatch>;
     /**
      * Enable AVS (Address Verification). Shows country dropdown + ZIP/postcode input.
      * When enabled, billing_details are passed to Stripe's createPaymentMethod for AVS checks.
@@ -412,6 +432,8 @@ interface SplitCardFormProps {
     totalAmount?: number;
     /** Currency code (used for PayPal Elements config). */
     currency?: string;
+    /** Render the card form expanded on first paint when `layout="buttons"`. */
+    initialCardOpen?: boolean;
 }
 /**
  * Split card checkout form matching `checkout/StripeCardForm`: