@flopay/react 1.9.22 → 1.9.27

package/README.md

@@ -125,7 +125,9 @@ The payment-method list is gateway-driven: the billing API sends `gateways.strip
 The SDK renders PayPal one of two ways, chosen per session from its gateways:
 
 - **Direct PayPal** (preferred, and works inside Facebook, Instagram, and other in-app browsers): when the session has `gateways.paypal`, PayPal renders through the official PayPal JS SDK with the client id and `environment` (`sandbox` or `live`) from the billing API. If only PayPal is advertised, `FloPayCheckout` skips Stripe entirely.
-- **Stripe-rendered PayPal**: when only `gateways.stripe` is configured, PayPal renders through Stripe's express checkout. It cannot render in Facebook or Instagram in-app browsers.
+- **Stripe-routed PayPal**: when only `gateways.stripe` is configured, an ordinary browser renders PayPal through Stripe Express Checkout. Instagram, generic Android WebViews, and other known in-app browsers instead get a Flo-owned PayPal tile that starts Stripe's full-page hosted approval without mounting the popup-bound Express element.
+
+`walletPresentation` is a bounded merchant preference shared by `FloPayCheckout` and `SplitCardForm`: `auto` (the default) and `popup` retain Express Checkout in an ordinary browser, while `prefer_redirect` selects the Flo tile. Browser safety remains authoritative, so a known in-app browser or a positive popup block switches Stripe-routed PayPal to the tile for the rest of the checkout session even when `popup` was requested. The tile still creates the session-scoped Stripe PayPal intent, stores the bounded continuation, and calls Stripe with the current page as `return_url` and `redirect: 'if_required'`. On return, the SDK resumes the same checkout session without creating a duplicate payment. Apple Pay and Google Pay are unchanged and are not affected by this preference.
 
 Direct PayPal never hides its button behind a FloPay identity step: after approval the SDK reads the payer's email and name, and asks once for anything missing. `gateways.paypal.providerObjectType` selects the operation: `order` (a one-time Order, even for a subscription-mode session), `subscription` (a PayPal-managed subscription), or `setup_token` (vault the account; the approval token is exchanged by the billing API). `approvalPresentation` selects the bounded `app_switch` mode only for a one-time Order in an in-app browser, where it enables PayPal's app switch; ordinary browsers, subscriptions, and setup tokens keep the popup flow. It is a mode, never a URL. If an in-app popup is blocked, `onTechnicalFailure` on `DirectPayPalButton` receives `popupBlocked: true` with guidance to open the page in the system browser, and PayPal stays visible for retry.
 
@@ -469,6 +471,7 @@ export function ComposedCheckout({ session, nonce }: { session: CheckoutSession;
 | `renderConfirmButton` | `function?` | Custom confirm-mode button renderer |
 | `showStripe` | `boolean?` | Show Stripe wallets and alternative methods (default `true`) |
 | `showPayPal` | `boolean?` | Show PayPal (default `true`) |
+| `walletPresentation` | `WalletPresentation?` | Stripe-PayPal presentation preference: `auto`, `popup`, or `prefer_redirect` |
 | `enabledPaymentMethods` | `string[]?` | Overrides the session's advertised Stripe methods |
 | `enableAVS` | `boolean \| AVSFieldConfig` | Collect and validate the billing address |
 | `avsLayout` | `'row' \| 'column'` | AVS field layout |
@@ -559,6 +562,7 @@ Also accepts every standard `button` attribute, such as `onClick`, `disabled`, a
 | `theme` | `ThemeId?` | Theme bundle |
 | `submitLabel` | `(string \| null)?` | Live wording for the hosted card submit button; omitted, `null`, or blank shows the hosted default `CONFIRM PAYMENT` |
 | `showStripe` / `showPayPal` | `boolean?` | Toggle Stripe methods and PayPal |
+| `walletPresentation` | `WalletPresentation?` | Stripe-PayPal presentation preference: `auto`, `popup`, or `prefer_redirect` |
 | `enabledPaymentMethods` | `string[]?` | Stripe method identifiers; `card` advertises the hosted card form |
 | `enableAVS` | `boolean \| AVSFieldConfig` | Collect and validate the billing address |
 | `cardFieldOrder` | `VaultCardFieldKey[]?` | Order of the hosted card rows |
@@ -604,6 +608,7 @@ Also accepts every standard `button` attribute, such as `onClick`, `disabled`, a
 | `CheckoutButtonMethod` | The payment method a button represents |
 | `InlineSessionDraft` | Draft accepted by `FloPayCheckoutProps.createSession` |
 | `InlineSessionPatch` | Partial draft returned from `FloPayCheckoutProps.onBeforeButtonClick` |
+| `WalletPresentation` | Closed wallet presentation preference: `auto`, `popup`, or `prefer_redirect` |
 | `FloInstrumentEvent` | Versioned merchant instrument union |
 
 ## Errors