@flopay/react 1.4.19 → 1.4.21

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.
@@ -356,6 +402,41 @@ 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.
 
+#### Authorisation-only checkout
+
+Set `captureMethod: 'manual'` in the same `createSession` draft for an eligible
+item-only card checkout:
+
+```tsx
+<FloPayCheckout
+  createSession={{
+    clientId: 'your-client-id',
+    captureMethod: 'manual',
+    currency: 'EUR',
+    items: [{ code: 'order_123', totalAmount: 29.99 }],
+    account: { userId: 'user_1', email: 'user@example.com' },
+    successUrl: '/success',
+    cancelUrl: '/cancel',
+  }}
+  onComplete={(result) => {
+    if (result.status === 'authorized') {
+      saveAuthorisation({
+        paymentId: result.paymentId,
+        sessionId: result.sessionId,
+        expiresAt: result.authorizationExpiresAt,
+      });
+    }
+  }}
+  onSessionCompleted={(successUrl) => router.push(successUrl)}
+/>
+```
+
+The component still releases the buyer to the success experience, but its
+overlay says `PAYMENT AUTHORISED`. `authorized` means funds are held, not paid.
+Capture remains a merchant-authenticated REST operation and is never available
+to browser code. Manual capture is rejected for subscription carts. See the
+repository's [pre-authorisation guide](../../docs/PREAUTHORIZATION.md).
+
 That create POST sends a stable `Idempotency-Key` header automatically whenever a
 secure RNG is available. `FloPayCheckout` resolves the key once per logical
 checkout, stores it with the inline-session cache in `sessionStorage`, and reuses
@@ -714,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'`. |
@@ -741,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` | `VaultCardThemeColors?` | Hosted widget colors. |
+| `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
@@ -854,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 |