@flopay/react 1.4.20 → 1.4.22

package/README.md

@@ -83,6 +83,52 @@ function CheckoutPage() {
 
 The mode can also be set on the session itself via the billing API's `checkoutMode` field. The `checkoutMode` prop overrides the session value.
 
+### Secure saved-card setup
+
+Use `FloPayCardSetup` to let a customer add or verify a card without creating a
+purchase or charge. Your trusted server must first call the
+merchant-authenticated card-setup endpoint and pass only its opaque `sessionId`
+and bound `nonce` to the browser. Never send Client Basic credentials, OAuth
+tokens, or a customer identifier to this component.
+
+```tsx
+import { FloPayCardSetup } from '@flopay/react';
+
+function AddCard({ sessionId, nonce }: { sessionId: string; nonce: string }) {
+  return (
+    <FloPayCardSetup
+      sessionId={sessionId}
+      nonce={nonce}
+      onComplete={({ paymentMethod }) => {
+        // Display-only when supplied. Re-list from the server if absent during
+        // a mixed-version backend rollout.
+        console.log(paymentMethod?.brand, paymentMethod?.lastFour);
+      }}
+      onDecline={({ message }) => showCardError(message)}
+      onValidation={(message) => showCardValidation(message)}
+      onError={(error) => {
+        if (error.retryable) showRetry();
+      }}
+      onCancel={() => closeAddCard()}
+    />
+  );
+}
+```
+
+The component reads and validates the setup session before injecting FloPay's
+hosted PCI card widget. It refuses purchase sessions, zero-amount non-setup
+sessions, non-zero setup sessions, and setup sessions containing products. Bank
+authentication is shown through the existing hosted challenge and does not
+count as success while pending. Completion fires only after verification says
+the card is usable; decline, validation, retryable technical failure, and
+unmount cancellation remain separate outcomes.
+
+Saved-card listing, setup-session creation, and deletion remain authenticated
+merchant REST calls. Replacement is composition: complete setup for the new
+card, then ask your server to delete the old card. `FloPayCardSetup` deliberately
+has no customer-id, merchant-credential, list, delete, purchase, or Stripe
+Elements prop.
+
 #### Expired Sessions
 
 When `FloPayCheckout` or `FloPayAutomaticPaymentButton` loads a checkout session whose `status` is `expired`, the component calls `onError` with a `FloPayError` so your app can route the customer into a recovery flow.
@@ -238,7 +284,7 @@ legacy props will be removed in `2.0`.
 
 #### Theming
 
-`FloPayCheckout`, `FloPayAutomaticPaymentButton`, and `SplitCardForm` accept a single `theme` prop that maps to a coherent `{appearance, buttonsLayout}` bundle in `@flopay/shared`'s `THEMES` map. One value styles non-card Stripe Elements, the React-rendered wrapper and AVS inputs, the hosted vault widget, and — for `FloPayAutomaticPaymentButton` — the fallback modal that opens when a saved-payment charge can't complete silently.
+`FloPayCheckout`, `FloPayAutomaticPaymentButton`, `SplitCardForm`, and `FloPayCardSetup` accept a single `theme` prop that maps to a coherent `{appearance, buttonsLayout}` bundle in `@flopay/shared`'s `THEMES` map. (`FloPayCardSetup` styles only the hosted vault widget — there are no surrounding Stripe Elements on that surface — and unlike the checkout components it defaults to `'modern-light'` rather than `'classic'`.) One value styles non-card Stripe Elements, the React-rendered wrapper and AVS inputs, the hosted vault widget, and — for `FloPayAutomaticPaymentButton` — the fallback modal that opens when a saved-payment charge can't complete silently.
 
 | `theme` | Aesthetic |
 |---|---|
@@ -749,6 +795,7 @@ function PaymentStatus() {
 |-----------|-------------|
 | `FloPayProvider` | Context provider. Accepts `flopay` (instance or promise), `options?`, and `children`. Creates the elements group automatically. |
 | `FloPayCheckout` | Recommended self-contained session checkout. Resolves gateways, mounts hosted-vault cards, and preserves wallets/APMs/PayPal/saved-payment flows. |
+| `FloPayCardSetup` | Browser-only no-charge card verification for a merchant-server-created setup session. Requires `sessionId` + `nonce`; reports ready, verified completion, decline, validation, retryable technical error, and cancellation outcomes. |
 | `SplitCardForm` | Advanced checkout surface combining hosted-vault cards with wallets, APMs, and PayPal. Supports `ref` for imperative next-action handling. |
 | `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'`. |
@@ -776,6 +823,24 @@ function PaymentStatus() {
 | `options.currency` | `string?` | ISO 4217 currency code for deferred non-card Elements without a `clientSecret` |
 | `options.paymentMethodCreation` | `'manual' \| 'auto'` | How payment methods are created |
 
+### FloPayCardSetupProps
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `sessionId` | `string` | Opaque id returned by the merchant-authenticated setup-session endpoint. |
+| `nonce` | `string` | Required session-bound read/capture token. |
+| `billingApiUrl` | `string?` | Billing API base URL; defaults through normal FloPay environment resolution. |
+| `telemetry` | `boolean?` | Privacy-safe operational telemetry; set `false` to opt out. |
+| `theme` | `ThemeId \| VaultCardThemeColors?` | High-level theme id (same values as `FloPayCheckout`, resolved through the same bundle) or raw hosted-widget colors. Defaults to `'modern-light'`; `'classic'` keeps the historic FloPay look. |
+| `containerStyle` | `React.CSSProperties?` | Inline styles for the hosted-widget container. |
+| `loading` | `React.ReactNode?` | Content shown while the session and hosted widget load. |
+| `onReady` | `() => void` | Hosted widget is mounted and accepting input. |
+| `onComplete` | `(event: FloPayCardSetupCompleteEvent) => void` | Verified usable card. Includes `sessionId` and optional display-only `paymentMethod`; never amount, charge, or payment-success data. |
+| `onDecline` | `(event: FloPayCardSetupDeclineEvent) => void` | Terminal card-verification decline. |
+| `onValidation` | `(message: string \| null) => void` | Live hosted-field validation; not a technical error. |
+| `onError` | `(error: FloPayCardSetupError) => void` | Validation/technical failure with stable `code` and explicit `retryable`. |
+| `onCancel` | `(event: FloPayCardSetupCancelEvent) => void` | Fires once when the component unmounts before a terminal outcome. |
+
 ### Privacy-safe operational telemetry
 
 `FloPayCheckout` emits the same closed Flo-owned lifecycle/error/performance
@@ -889,6 +954,11 @@ endpoint when a buyer enters the card path.
 | Type | Description |
 |------|-------------|
 | `FloPayProviderProps` | Props for `FloPayProvider` |
+| `FloPayCardSetupProps` | Props for `FloPayCardSetup` |
+| `FloPayCardSetupCompleteEvent` | Verified setup completion with optional display-only `paymentMethod` |
+| `FloPayCardSetupDeclineEvent` | Terminal card-verification decline |
+| `FloPayCardSetupCancelEvent` | Unmount-before-terminal cancellation |
+| `FloPayCardSetupError` | Structured setup failure with stable `code` and `retryable` classification |
 | `SplitCardFormProps` | Props for `SplitCardForm` |
 | `PayPalButtonProps` | Props for `PayPalButton` |
 | `ElementComponentProps` | Shared props for all element components |