@flopay/react 1.2.7 → 1.3.0

package/README.md

@@ -406,6 +406,13 @@ Pass `onTokenizedBody` to handle backend submission yourself:
 />
 ```
 
+> **Vault card path — `onTokenizedBody` does not fire.** When the session uses the
+> [vault PCI card form](#vault-pci-card-form), the backend-served widget owns the
+> whole charge (tokenize → PaymentIntent → 3DS → result), so there is no
+> client-side tokenization step to override. Use `onComplete` / `onDecline` /
+> `onError` instead — the SDK relays the widget's terminal outcome to them. The
+> legacy Stripe path's `onTokenizedBody` is unchanged.
+
 ### SplitCardForm (Split Card Fields + PayPal)
 
 `SplitCardForm` renders separate CardNumber, CardExpiry, and CardCVC fields with an integrated PayPal button. It matches the existing checkout/StripeCardForm layout.
@@ -457,6 +464,50 @@ The `SplitCardForm` layout:
 6. Full Name input
 7. Submit button
 
+### 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`) instead of Stripe's embedded card
+elements (TeamFloPay/backend#823, Model A). The backend embeds this block for
+any SDK that advertises `x-flo-sdk-version >= 1.3.0`, so 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, on the vault path `SplitCardForm` hides its own
+card fields, cardholder-name input, AVS fields, and submit button. 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)
+  → buyer pays inside the widget (tokenize → charge → 3DS, all backend-owned)
+  → widget postMessages its outcome → SDK fires onComplete / onDecline / onError
+```
+
+- The widget HTML comes from the embedded `session.vault.html` (SDKs ≥ 1.3.0 send
+  `X-Flo-SDK-Version`, so the backend embeds it on create-session) or, if absent,
+  from `POST /v1/checkouts/sessions/{id}/vault/capture`.
+- **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`.
+
+**Failure modes:** the widget renders its own status / decline UI; `onDecline` /
+`onError` receive the mapped reason + message so consumers can react.
+
+> **Backend dependencies:** the hosted widget must emit the `flopay-vault`
+> `postMessage` outcome the SDK listens for (otherwise it falls back to its own
+> success redirect), handle the 3DS step internally, and own AVS for the vault
+> path (the SDK no longer collects it inline; account-level address set at
+> session-create still flows to the backend). Because the widget is injected
+> **same-window**, every terminal outcome must be bound to the session id, and —
+> to fully defend against same-window forgery — the backend should mint a
+> per-session `messageToken` on the vault block and echo it in each
+> `postMessage`; the SDK threads it through and rejects outcomes that omit or
+> mismatch it (TeamFloPay/backend#823).
+
 ### PayPal Handling
 
 The SDK supports two PayPal paths, selected per-session based on what the billing API advertises under `gateways.*`:
@@ -543,7 +594,8 @@ function PaymentStatus() {
 |-----------|-------------|
 | `FloPayProvider` | Context provider. Accepts `flopay` (instance or promise), `options?`, and `children`. Creates the elements group automatically. |
 | `CheckoutForm` | Drop-in form with unified PaymentElement. Self-contained by default, or override with `onTokenizedBody`. Supports `ref` for imperative `handleNextAction()`. |
-| `SplitCardForm` | Split card form (CardNumber + CardExpiry + CardCvc + Full Name). Integrates PayPal via separate Elements instance. Supports `ref` for imperative `handleNextAction()`. |
+| `SplitCardForm` | Split card form (CardNumber + CardExpiry + CardCvc + Full Name). Integrates PayPal via separate Elements instance. Renders the [vault PCI card form](#vault-pci-card-form) when the session includes a hosted vault card form (`session.vault`). Supports `ref` for imperative `handleNextAction()`. |
+| `VaultCardFields` | Hosted vault PCI card fields. Used internally by `SplitCardForm` on the vault path; consumes a `CardCaptureAdapter` from `useFloPay().cardCapture()`. |
 | `PayPalButton` | Standalone PayPal button. Requires its own `FloPayProvider` with `paymentMethodCreation` set to something other than `'manual'`. |
 | `PaymentElement` | Unified payment element (cards, wallets, etc.) |
 | `CardElement` | Combined card input |