@flopay/react 1.2.8 → 1.3.1

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,73 @@ The `SplitCardForm` layout:
 6. Full Name input
 7. Submit button
 
+#### AVS postcode validation
+
+When AVS collection is enabled (`enableAVS`) and the postcode field is shown,
+`SplitCardForm` validates the postcode **format against the live selected
+country before the card is captured**, on both the Stripe and vault card paths.
+It reuses `@flopay/shared`'s country-aware
+[postcode helpers](../shared/README.md#postal-code-helpers) (the same
+`validator` rules the billing API applies), so client and server agree.
+
+- **Supported country + malformed postcode** → the submit is blocked (the vault
+  widget's submit button is gated; the Stripe path returns before tokenizing)
+  and an inline, country-specific message shows the expected format
+  (e.g. *"Enter a valid ZIP Code (e.g. 12345 or 12345-6789)"*). On the vault
+  path the inline message appears once the field is blurred, since the disabled
+  submit means it can't be reached by a submit attempt.
+- **Supported country + empty postcode** → the same submit gate applies, and
+  once the field is blurred (or a submit is attempted) an inline *required*
+  message shows (e.g. *"ZIP Code is required"*) rather than the expected-format
+  copy.
+- **Country with no postal system** (or a locale `validator` doesn't recognise)
+  → the postcode field is shown but **optional**: empty and format checks are
+  both skipped, so these buyers are never blocked.
+
+### 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 +617,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 |