@flopay/react 1.4.16 → 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.
@@ -664,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>;
   // ...
@@ -692,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
 
@@ -794,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 }` |