@flopay/react 1.8.3 → 1.8.6

package/README.md

@@ -59,17 +59,18 @@ function CheckoutPage() {
 
 For inline checkout creation, `createSession.account.userId` remains required,
 but `email`, `firstName`, and `lastName` may be omitted. `FloPayCheckout`
-creates a mountable session shell first, then collects and attaches the missing
-identity before payment can continue:
+creates a mountable session shell first, immediately attaches the known catalog,
+and collects buyer identity at the method-appropriate point:
 
 - Hosted card checkout renders a required email field first, above name, AVS,
   and the hosted card widget. Submit stays gated until the email passes the
   shared `isValidEmail()` validator and a name is present.
 - Apple Pay, Google Pay, other Stripe wallets, and PayPal use provider-returned
-  email/name automatically when available.
+  email/name automatically when available. Their provider UI starts without a
+  Flo identity preflight.
 - A wallet, PayPal, or APM that does not return the missing fields opens a
-  required second pane for email/name before the SDK creates an intent or
-  processes payment.
+  single required fallback pane after that provider miss (or before submission
+  for a method that cannot return identity).
 
 The SDK never attaches a blank email. The merchant-supplied `userId` is not
 replaced by provider data.
@@ -405,7 +406,7 @@ the default layout to `"buttons"` keeps the resolved checkout session and its
 gateway capabilities, so the **Credit / Debit Card** choice remains available
 without recreating the session.
 
-> **Deprecated**: the legacy `buttonsTheme` prop (`'default'` / `'minimal'` / `'rounded'` / `'dark'`) still works but new code should use `theme` so the same value drives both the buttons-layout wrapper and the auto-payment fallback. See [ButtonsLayoutStyles reference](https://docs.flopay.com/api-reference/react/flopay-checkout#buttonslayoutstyles-reference) for the underlying override fields.
+> **Deprecated**: the legacy `buttonsTheme` prop (`'default'` / `'minimal'` / `'rounded'` / `'dark'`) still works but new code should use `theme` so the same value drives both the buttons-layout wrapper and the auto-payment fallback. See [ButtonsLayoutStyles reference](https://flopay.com/docs/api-reference/react/flopay-checkout#buttonslayoutstyles-reference) for the underlying override fields.
 
 #### Button Hooks
 
@@ -470,8 +471,9 @@ Skip the backend API route — create the session directly in the component:
 />
 ```
 
-The component creates a lightweight shell, renders the form, and claims the
-session after buyer identity is available — zero merchant backend code needed.
+The component creates a lightweight shell, attaches the catalog immediately,
+renders every otherwise-eligible method, and identifies the buyer later from
+the selected method or its fallback — zero merchant backend code needed.
 
 #### Authorisation-only checkout
 
@@ -549,20 +551,36 @@ When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSes
 
 `createSession` checkouts are created in two phases (TeamFloPay/backend#1099):
 a lightweight session *shell* that skips catalog validation and the
-buyer-identity advisory locks, then a background **claim** that attaches buyer
-identity, address, products and coupons.
+buyer-identity advisory locks, then a background **claim** that attaches the
+catalog. If the draft already contains an email, that claim also attaches the
+buyer. Otherwise it deliberately omits `accountData` and returns a complete,
+still-anonymous session (`buyerIdentified: false`).
 
 `FloPayCheckout` renders from the shell, so the hosted card form mounts and
 becomes interactive without waiting for either the claim or Stripe.js — Stripe
-wallets, APMs and PayPal load in parallel with the claim and appear when it
-lands. The card widget's submit button stays gated for that window, because the
+wallets, APMs and PayPal load in parallel with the catalog claim and appear
+from its full `enabledPaymentMethods` list when it lands. The card widget's
+submit button stays gated for that window, because the
 billing API rejects a charge against an unclaimed session; if a buyer clicks
 during it, the widget cancels the click and the form asks them to press pay
 again. In practice the claim resolves while the card is still being filled in.
 
 Nothing else changes for you: the same session, the same callbacks, the same
 results. Catalog and coupon errors still surface as a checkout load error, just
-from the claim rather than the create.
+from the claim rather than the create. Missing buyer identity never delays this
+catalog claim: provider-capable methods identify the buyer during payment, and
+`claim(account)` performs a separate buyer-only attachment when manual
+collection is needed.
+
+That buyer-only attachment is not specific to detached creation. Any
+still-anonymous session the checkout renders — a one-shot create without an
+email, or an existing session passed as `sessionId` + `nonce` that the billing
+API returns with `buyerIdentified: false` — gets the same late-buyer claim
+rebuilt from the session's nonce, so the email the SDK collects (or a wallet /
+PayPal approval supplies) reaches `PATCH /v1/checkouts/sessions/{id}/claim`
+before payment. The hosted vault widget's charge is refused server-side for a
+session with no bound buyer, so without that claim an email-less session loaded
+by id would never complete.
 
 Opt out per session to restore the original single-request create:
 
@@ -578,7 +596,8 @@ Opt out per session to restore the original single-request create:
 Detached creation applies only to `checkoutMode: 'full'` (the billing API
 rejects it for `auto` / `confirm`) and is skipped when `tokenizedData` is
 supplied. There is **no fallback** to the one-shot create — it requires a
-billing API that exposes `PATCH /v1/checkouts/sessions/{id}/claim`.
+billing API `v1.7.12` or newer that exposes the independent catalog/buyer
+`PATCH /v1/checkouts/sessions/{id}/claim` contract.
 
 ### Advanced: Manual Provider Setup
 
@@ -769,6 +788,14 @@ Renderer selection is mutually exclusive per session — direct PayPal takes pri
 
 **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.
 
+**Provider-first buyer identity:** Direct PayPal never hides its Smart Button
+behind a Flo buyer-details preflight. An anonymous buyer starts PayPal normally;
+after approval the SDK reads the payer email/name, attaches valid returned
+details, and continues processing. If PayPal returns incomplete identity, the
+SDK shows exactly one required fallback pane after approval and resumes with
+the collected values. A checkout that supplied buyer details up front keeps its
+existing request bodies and callbacks.
+
 **Flo-owned subscription continuations:** `gateways.paypal.providerObjectType`
 selects the direct PayPal operation. `'order'` loads the PayPal SDK with
 `intent=capture` and invokes `createOrder`, even when the checkout session mode
@@ -949,6 +976,7 @@ Key payment-surface props include:
 | `currency` | `string` | Currency code for PayPal / wallet config (default: `'usd'`) |
 | `onFirstNameChange` | `(value: string) => void` | First name change callback |
 | `onLastNameChange` | `(value: string) => void` | Last name change callback |
+| `onBuyerIdentityReady` | `(identity) => MaybePromise<void>?` | Called once checkout has collected a missing buyer email (or a wallet / PayPal approval supplied one) on a still-anonymous session. `FloPayCheckout` wires its late-buyer `PATCH /claim` here — including for custom-layout children, via `CheckoutContext`. A standalone form around a `session` with `buyerIdentified: false` that is given neither a prop nor a context claim builds its own from `sessionId` + `nonce`, so the hosted vault charge is never submitted against an unbound buyer. Supply the prop to take the claim over yourself. |
 | `onComplete` / `onDecline` / `onError` | callbacks | Observable checkout outcomes. |
 
 #### Deferred-vault rollout boundary