@flopay/react 1.4.8 → 1.4.11

package/README.md

@@ -182,6 +182,10 @@ partitions that list into two regions inside `SplitCardForm`:
 - `PaymentElement` (accordion) — every other enabled method, e.g. `cashapp`,
   `affirm`, `ideal`, `bancontact`, `sepa_debit`.
 
+`card` is a capability marker, not a Stripe-rendered method. It keeps the
+**Credit / Debit Card** path available and tells SDK 1.4.9+ that the hosted
+vault form can be requested lazily when `session.vault` is absent.
+
 Enabling Cash App Pay (or any future Stripe method) in the Stripe dashboard is
 the entire integration change — no SDK redeploy or consumer code update is
 required. Wallets only render on supported devices regardless of dashboard
@@ -353,11 +357,17 @@ 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.
 
 That create POST sends a stable `Idempotency-Key` header automatically whenever a
-secure RNG is available, so a timeout or lost response never mints a second
-session. `FloPayCheckout` already coalesces concurrent mounts (StrictMode
-double-mount, Suspense remount, navigation flicker) into a single create, and
-rerenders during an in-flight create do **not** replace the key. You normally
-don't need to think about it.
+secure RNG is available. `FloPayCheckout` resolves the key once per logical
+checkout, stores it with the inline-session cache in `sessionStorage`, and reuses
+it across transport retries, effect reruns, and component remounts. Concurrent
+mounts (StrictMode double-mount, Suspense remount, or navigation flicker) share
+both the session create and the auto-mode payment attempt, so one purchase cannot
+fan out into multiple creates or charges.
+
+Logical checkout identity is based on the merchant, buyer, cart/pricing, and
+coupons. Checkout-mode changes, refreshed payment tokens, and analytics/UTM prop
+churn do not rotate the key while that purchase is active. A different cart or
+buyer gets a different key; an email-less buyer is separated by `account.userId`.
 
 To control the key yourself — for example to keep it stable across your own
 server retries — pass `idempotencyKey` on `createSession`:
@@ -386,8 +396,10 @@ When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSes
 ### Advanced: Manual Provider Setup
 
 Use `SplitCardForm` when you need to compose the provider and session yourself.
-Card checkout still requires the backend-hosted vault block; Stripe remains
-limited to wallets/APMs and saved-payment authentication.
+Card checkout uses the backend-hosted vault widget; Stripe remains limited to
+wallets/APMs and saved-payment authentication. The session can supply the
+widget eagerly in `session.vault`, or explicitly advertise `card` in
+`gateways.stripe.enabledPaymentMethods` so the SDK recovers it on demand.
 
 ```tsx
 import { FloPayProvider, SplitCardForm } from '@flopay/react';
@@ -432,7 +444,8 @@ The resulting surfaces are:
 
 1. Wallet buttons and supported APM tiles from the session gateway capability.
 2. Direct or Stripe-hosted PayPal, selected from the session gateways.
-3. The hosted vault widget for card-capable sessions.
+3. The hosted vault widget for sessions with embedded vault HTML or an explicit
+   Stripe `card` capability.
 
 Wallets, APMs, and PayPal create intents through
 `POST /v1/checkouts/sessions/{id}/intents`. The discriminated request separates
@@ -441,9 +454,13 @@ requests are unsupported. Client-observed non-card failures use the
 nonce-protected session decline endpoint and contain no payment tokens,
 provider object IDs, card data, credentials, or PII.
 
-If a card-capable backend omits the vault block, card checkout stays hidden.
-Advertised non-card methods remain usable; if none remain,
-`onError` receives `UnsupportedBackendVaultCapability`.
+For SDK 1.4.9+, an explicit Stripe `card` capability keeps card checkout
+visible even when the backend omits the vault block. In `layout="buttons"`,
+`POST /v1/checkouts/sessions/{id}/vault/capture` is deferred until the buyer
+selects Card. An embedded block remains the preferred fast path and causes no
+recovery POST. Sessions that advertise neither an embedded block nor `card`
+do not call the recovery endpoint; their non-card methods remain usable, and
+if none remain, `onError` receives `UnsupportedBackendVaultCapability`.
 
 #### AVS postcode validation
 
@@ -498,30 +515,34 @@ best-effort **in parallel** with the widget's charge:
 
 ### Vault PCI card form
 
-When the billing API returns a hosted vault card form on the session
-(`session.vault`), the card path renders a **backend-served, self-contained
-hosted vault widget** (`VaultCardFields`) (TeamFloPay/backend#823, Model A).
-Every card-capable session is
-expected to include this block without SDK-version dispatch. It is fully
-**server-driven** — there is no consumer prop to toggle it. The widget owns the
-card fields, its own submit button, card tokenization, the PaymentIntent (created
-**and** confirmed server-side), **3DS**, and the result, so **no Stripe.js runs
-on the card path** and PAN / CVC never enter the SDK runtime. Wallets / PayPal /
-APMs render exactly as before.
+The card path renders a **backend-served, self-contained hosted vault widget**
+(`VaultCardFields`) (TeamFloPay/backend#823, Model A). The billing API may
+return it eagerly in `session.vault`, or advertise `card` under
+`gateways.stripe.enabledPaymentMethods` and let SDK 1.4.9+ request it lazily.
+It is fully **server-driven** — there is no consumer prop to toggle it. The
+widget owns the card fields, its own submit button, card tokenization, the
+PaymentIntent (created **and** confirmed server-side), **3DS**, and the result,
+so **no Stripe.js runs on the card path** and PAN / CVC never enter the SDK
+runtime. Wallets / PayPal / APMs render exactly as before.
 
 Because the widget owns the form, `SplitCardForm` exposes no SDK card-entry or
 card-submit controls. Host-collected AVS fields remain outside the PCI
 widget and gate its submit. The flow is:
 
 ```text
-session includes a hosted vault card form (session.vault)
-  → SDK injects the widget HTML (session.vault.html, or POST /vault/capture)
+session embeds session.vault or advertises gateways.stripe.enabledPaymentMethods: ['card']
+  → SDK uses embedded HTML, or requests POST /vault/capture when Card is needed
+  → concurrent renders/remounts share that active request
   → buyer pays inside the widget (tokenize → charge → 3DS, all backend-owned)
   → widget postMessages its outcome → SDK fires onComplete / onDecline / onError
 ```
 
-- The widget HTML normally comes from embedded `session.vault.html`; the explicit
-  recovery/retry path is `POST /v1/checkouts/sessions/{id}/vault/capture`.
+- Embedded `session.vault.html` is the preferred fast path during rollout and
+  never triggers a recovery request.
+- Deferred capture uses
+  `POST /v1/checkouts/sessions/{id}/vault/capture`, with a ten-second timeout,
+  bounded transient-network retry, and one shared active request per
+  base URL/session/nonce.
 - **Returning customers** with a card on file (`session.providerPaymentMethodId`)
   are charged by the backend's auto-checkout cascade.
 - **3DS** is handled inside the widget — there is no client-side `confirmCardPayment`.
@@ -710,11 +731,11 @@ Key payment-surface props include:
 |------|------|-------------|
 | `sessionId` | `string` | Checkout session UUID. |
 | `nonce` | `string` | Session-bound token forwarded on intent, decline, account, and process calls. |
-| `session` | `CheckoutSession?` | Session capability data, including the hosted `vault` block and gateways. |
+| `session` | `CheckoutSession?` | Session capability data, including the optional hosted `vault` fast path and gateways. |
 | `billingApiUrl` | `string` | Billing API base URL. |
-| `showStripe` | `boolean` | Show Stripe-backed wallets/APMs. Card checkout is controlled by the session vault capability. |
+| `showStripe` | `boolean` | Show Stripe-backed wallets/APMs and the hosted card path when the session embeds `vault` or advertises `card`. |
 | `showPayPal` | `boolean` | Show PayPal. Renderer chosen by `gateways.paypal` presence (DirectPayPal JS SDK when present; Stripe-rendered PayPal otherwise). Default: `true`. |
-| `enabledPaymentMethods` | `string[]?` | Per-session list of Stripe method type identifiers (`apple_pay`, `google_pay`, `cashapp`, `klarna`, `link`, `amazon_pay`, `sepa_debit`, `affirm`, `ideal`, …). Normally threaded automatically from `gateways.stripe.enabledPaymentMethods` by `FloPayCheckout`. The SDK partitions it into the ExpressCheckoutElement big-button row (intersected with `STRIPE_EXPRESS_METHODS`) and the accordion PaymentElement region; `card` is always dropped because the hosted vault owns that path. |
+| `enabledPaymentMethods` | `string[]?` | Per-session list of Stripe method type identifiers (`card`, `apple_pay`, `google_pay`, `cashapp`, `klarna`, `link`, `amazon_pay`, `sepa_debit`, `affirm`, `ideal`, …). Normally threaded automatically from `gateways.stripe.enabledPaymentMethods` by `FloPayCheckout`. The SDK partitions non-card methods between ExpressCheckoutElement and PaymentElement; `card` advertises the hosted-vault path and is never rendered by Stripe. |
 | `showApplePay` | `boolean` | *Deprecated.* Apple Pay availability is dashboard-controlled at Stripe and surfaces through `enabledPaymentMethods`. Emits a one-time `console.warn` when supplied alongside `enabledPaymentMethods` and is otherwise ignored. Removed in `2.0`. |
 | `showGooglePay` | `boolean` | *Deprecated.* See `showApplePay`. |
 | `directPaypal` | `{ clientId: string; environment?: GatewayEnvironment }?` | *Deprecated input on `FloPayCheckout`* — auto-resolved from `gateways.paypal` on the session response. Still accepted on `SplitCardForm` for advanced consumers wiring providers manually. |
@@ -724,6 +745,24 @@ Key payment-surface props include:
 | `onLastNameChange` | `(value: string) => void` | Last name change callback |
 | `onComplete` / `onDecline` / `onError` | callbacks | Observable checkout outcomes. |
 
+#### Deferred-vault rollout boundary
+
+SDK `1.4.9` is the compatibility boundary for omitting embedded capture
+credentials. Keep the backend's current
+`link session → capture → complete idempotency → 201` ordering for requests
+from older or unknown SDK versions, and until the deployed `@flopay/react`
+population has crossed the adoption threshold chosen by the backend rollout.
+The SDK advertises its version in `x-flo-sdk-version` on session create/read.
+
+After that threshold, the backend may omit capture credentials from
+create/read/idempotent-replay responses for requests advertising SDK `>=1.4.9`,
+provided the session explicitly includes `card` in
+`gateways.stripe.enabledPaymentMethods` and the nonce-protected
+`POST /v1/checkouts/sessions/{id}/vault/capture` route remains available.
+Backend rollout verification should confirm that create/read/replay no longer
+invoke PCIVault and that capture issuance occurs only through the deferred
+endpoint when a buyer enters the card path.
+
 ### ElementComponentProps (shared by all element components)
 
 | Prop | Type | Description |