@flopay/react 1.0.3 → 1.1.3

package/README.md

@@ -215,7 +215,8 @@ Use `onButtonClick` to track button interactions, `onDecline` to track declines/
   layout="buttons"
   createSession={{
     clientId: 'your-client-id',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
+    currency: 'EUR',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
     account: { userId: 'user_1', email: 'test@email.com' },
     successUrl: '/success',
     cancelUrl: '/cancel',
@@ -258,7 +259,8 @@ Skip the backend API route — create the session directly in the component:
   layout="buttons"
   createSession={{
     clientId: 'your-client-id',
-    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99, currency: 'EUR' }],
+    currency: 'EUR',
+    items: [{ providerItemId: 'product-1', providerItemName: 'Widget', totalAmount: 29.99 }],
     account: { userId: 'user_1', email: 'user@example.com', firstName: 'Jane', lastName: 'Doe' },
     successUrl: '/success',
     cancelUrl: '/cancel',
@@ -269,6 +271,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.
 
+Session-level `currency` is now **required**. The backend (#760) enforces `@IsNotEmpty` on the field; the SDK pre-validates and throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` before issuing the request when neither the session nor any item/subscription/product carries a currency. Pass `currency` at the top of `createSession` (preferred), or rely on the legacy fallback to the first item/subscription/product `currency`.
+
 When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSessionPatch` is merged into the draft session params before the selected buttons-layout flow continues. That lets you add tracking data or update account fields just in time without pre-creating a separate backend session.
 
 ### Advanced: Manual Provider Setup
@@ -389,13 +393,22 @@ The `SplitCardForm` layout:
 
 ### PayPal Handling
 
-PayPal requires its own Stripe Elements instance because it cannot share an Elements group that uses `paymentMethodCreation: 'manual'`. In addition, the billing API may return a dedicated Stripe account for PayPal via `gatewayData.paypalPublishableKey` — when set, every PayPal Stripe operation uses that key. When the field is `null` or missing, PayPal is disabled (the button is not rendered); there is no fallback to the primary `publishableKey`.
+The SDK supports two PayPal paths, selected per-session based on what the billing API advertises under `gateways.*`:
+
+- **Direct PayPal** (preferred where available — works inside Facebook, Instagram, and other in-app browsers): when the session exposes `gateways.paypal.publishableKey`, the SDK renders PayPal via the official PayPal JS SDK using `<DirectPayPalButton>`. The PayPal client ID and `environment` (`'sandbox'`/`'live'`) come directly from the backend.
+- **Stripe-rendered PayPal fallback** (legacy): when only `gateways.stripe` is configured, PayPal renders through Stripe's `ExpressCheckoutElement` in its own Elements wrapper. This path can't render in Facebook/Instagram in-app browsers.
+
+Renderer selection is mutually exclusive per session — direct PayPal takes priority over Stripe-rendered PayPal. Consumer props such as `showPayPal` continue to gate visibility on the client side.
+
+**PayPal-only sessions:** When the backend advertises only `gateways.paypal` (no `gateways.stripe`), `FloPayCheckout` skips Stripe Elements entirely and renders `<DirectPayPalButton>` as the sole payment surface. Sessions that advertise no supported gateway at all throw a `validation_error` explaining the expected shape.
+
+The SDK exposes the relevant pieces in three ways:
 
-The SDK handles this in two ways:
+- **`SplitCardForm`** / **`FloPayCheckout`**: pick the renderer automatically based on `gateways.*`. No additional configuration needed.
 
-- **`SplitCardForm`**: Automatically manages two Elements instances internally. Card/wallet fields use the primary Stripe account with `paymentMethodCreation: 'manual'`. PayPal renders inside a separate `<Elements>` wrapper backed by the dedicated PayPal FloPay instance (exposed via the `usePayPalFloPay()` hook).
+- **`FloPayProvider`** (manual composition): accepts an optional `paypalFlopay` prop used to drive Stripe's PayPal redirect leg. Load a second `FloPay` instance yourself only if you need to render PayPal manually. `usePayPalFloPay()` exposes it to descendants.
 
-- **`FloPayProvider`** (manual composition): accepts an optional `paypalFlopay` prop. Load a second `FloPay` instance with the PayPal publishable key yourself, then pass it in alongside the primary instance. `usePayPalFloPay()` exposes it to descendants.
+- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, and `isSubscription`.
 
 - **`PayPalButton`** (standalone): Must be rendered inside its own `FloPayProvider`: