@flopay/react 0.3.11 → 0.3.12

package/README.md

@@ -121,6 +121,43 @@ Switch from the default form layout to stacked payment buttons with an expandabl
 
 Theme presets: `'default'`, `'minimal'`, `'rounded'`, `'dark'`. Custom styles via `buttonsStyles` merge on top of the theme preset. See the [ButtonsLayoutStyles reference](https://docs.flopay.com/api-reference/react/flopay-checkout#buttonslayoutstyles-reference) for all properties.
 
+#### Button Hooks
+
+Use `onButtonClick` to track button interactions, `onDecline` to track declines/cancellations, and `onBeforeButtonClick` to enrich the credit card flow before the card form opens:
+
+```tsx
+<FloPayCheckout
+  layout="buttons"
+  createSession={{
+    clientId: 'your-client-id',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
+    account: { userId: 'user_1' },
+    successUrl: '/success',
+    cancelUrl: '/cancel',
+  }}
+  onBeforeButtonClick={async ({ method }) => {
+    if (method !== 'card') return;
+
+    const email = await openEmailCaptureModal();
+    if (!email) return false;
+
+    return {
+      account: { email },
+      tagsData: { sessionId: 'checkout_email_captured' },
+    };
+  }}
+  onButtonClick={(method) => {
+    window.dataLayer?.push({ event: 'checkout_button_click', payment_method: method });
+  }}
+  onDecline={(decline) => {
+    window.dataLayer?.push({ event: 'checkout_decline', ...decline });
+  }}
+  onComplete={handleSuccess}
+/>
+```
+
+`onBeforeButtonClick` is **credit card only**. It runs only for the "Credit / Debit Card" button in `layout="buttons"`. It does not run for PayPal, Apple Pay, or Google Pay. If you need required data before every payment method, collect it before rendering checkout.
+
 #### Inline Session Creation
 
 Skip the backend API route — create the session directly in the component:
@@ -141,6 +178,8 @@ Skip the backend API route — create the session directly in the component:
 
 The component POSTs to the billing API, gets the full session back, and renders the form — zero backend code needed.
 
+When you use `onBeforeButtonClick`, `createSession.account.email` can be filled in later for the card-button flow. PayPal and wallets still need all required data before they render.
+
 ### Advanced: Manual Provider Setup
 
 For full control over initialization: