@flopay/react 1.4.14 → 1.4.17

package/README.md

@@ -393,6 +393,41 @@ Session-level `currency` is now **required**. The backend (#760) enforces `@IsNo
 
 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.
 
+### Detached session creation (default)
+
+`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.
+
+`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
+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.
+
+Opt out per session to restore the original single-request create:
+
+```tsx
+<FloPayCheckout
+  createSession={{
+    /* … */
+    deferDataAttachment: false, // one-shot 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`.
+
 ### Advanced: Manual Provider Setup
 
 Use `SplitCardForm` when you need to compose the provider and session yourself.
@@ -547,8 +582,17 @@ session embeds session.vault or advertises gateways.stripe.enabledPaymentMethods
   are charged by the backend's auto-checkout cascade.
 - **3DS** is handled inside the widget — there is no client-side `confirmCardPayment`.
 
-**Failure modes:** the widget renders its own status / decline UI; `onDecline` /
-`onError` receive the mapped reason + message so consumers can react.
+**Processing feedback:** after the hosted widget emits `submitting`, the SDK's
+full-checkout processing overlay remains visible continuously until the widget
+reports `complete`, `decline`, or `error`. Intermediate status polling and
+late card-field validation mutations cannot expose the completed form while a
+charge is still in flight. A synchronous card-validation rejection still
+returns the buyer to the form immediately, as does a `4xx` account-snapshot
+validation failure.
+
+**Failure modes:** `onDecline` / `onError` receive the mapped reason + message
+so consumers can react, and the SDK leaves an inline retry message after its
+terminal failure overlay clears.
 
 > **Backend dependencies:** the hosted widget must emit the `flopay-vault`
 > `postMessage` outcome the SDK listens for (otherwise it falls back to its own
@@ -655,7 +699,7 @@ import { useFloPay, useElements, useCheckout } from '@flopay/react';
 function PaymentStatus() {
   const flopay = useFloPay();       // FloPay | null
   const elements = useElements();    // FloPayElements | null
-  const checkout = useCheckout();    // { session, loading, error }
+  const checkout = useCheckout();    // { session, loading, error, claimPending }
 
   if (!flopay) return <div>Loading SDK...</div>;
   // ...
@@ -683,7 +727,7 @@ function PaymentStatus() {
 |------|---------|-------------|
 | `useFloPay()` | `FloPay \| null` | Current FloPay instance from context. `null` while loading. |
 | `useElements()` | `FloPayElements \| null` | Current elements group from context. `null` while loading. |
-| `useCheckout()` | `CheckoutState` | `{ session, loading, error }` from CheckoutContext |
+| `useCheckout()` | `CheckoutState` | `{ session, loading, error, claimPending }` from CheckoutContext. `claimPending` remains true while a detached shell is not safe to charge. |
 
 ### FloPayProviderProps
 
@@ -785,4 +829,4 @@ endpoint when a buyer enters the card path.
 | `SplitCardFormProps` | Props for `SplitCardForm` |
 | `PayPalButtonProps` | Props for `PayPalButton` |
 | `ElementComponentProps` | Shared props for all element components |
-| `CheckoutState` | `{ session, loading, error }` |
+| `CheckoutState` | `{ session, loading, error, claimPending }` |