@flopay/react 1.4.0 → 1.4.2

package/README.md

@@ -53,13 +53,13 @@ function CheckoutPage() {
 }
 ```
 
-`FloPayCheckout` automatically fetches the session, initializes the correct payment provider, and renders a `SplitCardForm` with card fields, Apple Pay, Google Pay, and PayPal. Customer data (email, userId, name) is injected from the session.
+`FloPayCheckout` automatically fetches the session, initializes the correct payment providers, and renders a `SplitCardForm` with the hosted vault card widget plus the session's supported wallets, APMs, and PayPal. Customer data (email, userId, name) is injected from the session.
 
 #### Checkout Modes
 
 `FloPayCheckout` supports three checkout modes matching the billing API's `checkoutMode` field:
 
-- **`full`** (default) — Shows the full payment form with card fields + wallet buttons.
+- **`full`** (default) — Shows the hosted card widget plus supported non-card methods.
 - **`confirm`** — Hides the payment form and shows a "Confirm Purchase" button. Uses a saved payment method on the backend.
 - **`auto`** — Auto-submits with a saved payment method after the session loads. Falls back to `full` mode on failure.
 
@@ -187,6 +187,13 @@ the entire integration change — no SDK redeploy or consumer code update is
 required. Wallets only render on supported devices regardless of dashboard
 state (Apple Pay on Safari/macOS/iOS, Google Pay on Chrome).
 
+> **Bundler note:** the vendored APM brand logos ship as sibling `.svg` assets
+> under `dist/payment-logos/`, referenced with `new URL('./…', import.meta.url)`
+> so their bytes stay out of the JS bundle (a card-only checkout ships none of
+> them). Your bundler must support asset URLs — Vite, webpack 5, Rollup, Next,
+> and esbuild all do out of the box. Card-only and vault checkouts never render
+> a method tile, so they never request a logo.
+
 In `layout="buttons"`, the **Credit / Debit Card** button always opens the
 inline card form. External wallets and PayPal keep their own lifecycle:
 buyer cancellation silently returns to the payment-method chooser with all
@@ -204,7 +211,7 @@ two gateway-level props:
 ```tsx
 <FloPayCheckout
   sessionId="sess_abc123"
-  showStripe={true}  // default: true — card + ECE + PaymentElement
+  showStripe={true}  // default: true — Stripe wallets/APMs only
   showPayPal={true}  // default: true — DirectPayPal when gateway present,
                      //                  Stripe-rendered PayPal otherwise
   onComplete={handleSuccess}
@@ -227,7 +234,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 the Stripe-side appearance, the React-rendered wrapper, the submit button, the inputs, and — for `FloPayAutomaticPaymentButton` — the fallback modal that opens when a saved-payment charge can't complete silently.
+`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.
 
 | `theme` | Aesthetic |
 |---|---|
@@ -373,87 +380,9 @@ When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSes
 
 ### Advanced: Manual Provider Setup
 
-For full control over initialization:
-
-```tsx
-import { loadFloPay } from '@flopay/js';
-import { FloPayProvider, CheckoutForm } from '@flopay/react';
-
-const floPayPromise = loadFloPay('pk_test_...');
-
-function CheckoutPage() {
-  return (
-    <FloPayProvider
-      flopay={floPayPromise}
-      options={{
-        amount: 2999,
-        currency: 'usd',
-      }}
-    >
-      <CheckoutForm
-        sessionId="session_uuid"
-        nonce={sessionNonce}
-        email="user@example.com"
-        userId="user_1"
-        onComplete={(result) => {
-          if (result.status === 'succeeded') {
-            window.location.href = '/success';
-          }
-        }}
-        onError={(err) => console.error(err)}
-      />
-    </FloPayProvider>
-  );
-}
-```
-
-`CheckoutForm` handles the full payment lifecycle by default:
-
-1. Validate elements via `submitElements()`
-2. Tokenize card via `createPaymentMethod()` -> `pm_xxx`
-3. Create PaymentIntent via billing API
-4. Confirm card payment (handles 3D Secure)
-5. Submit tokenized body to `POST /v1/checkouts/sessions/<id>/process`
-6. If backend returns `3ds_required`, re-confirm with new client secret
-7. Resume wallet payments after redirect (PayPal)
-
-Pass `nonce` (the session-bound checkout token returned by session creation —
-`CheckoutSessionResult.nonce`, or `session.clientSecret` once the session is
-loaded). The SDK forwards it as `x-checkout-session-token` on every
-continuation call. Post-#640 backends (`TeamFloPay/backend#640`) 401 when the
-header is missing. `FloPayCheckout` already plumbs the prop automatically.
-
-### Override Mode (Custom Backend)
-
-Pass `onTokenizedBody` to handle backend submission yourself:
-
-```tsx
-<CheckoutForm
-  sessionId="session_uuid"
-  billingApiUrl="https://billing.example.com"
-  email="user@example.com"
-  onTokenizedBody={(body) => {
-    // body = {
-    //   id: 'pm_xxx',
-    //   type: 'card',
-    //   threeDSecureActionResultTokenId: 'pi_xxx',
-    //   originalPaymentMethodId: 'pm_xxx',
-    // }
-    myCustomProcessPayment(body);
-  }}
-/>
-```
-
-> **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.
+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.
 
 ```tsx
 import { FloPayProvider, SplitCardForm } from '@flopay/react';
@@ -473,12 +402,13 @@ function CheckoutPage() {
       <SplitCardForm
         sessionId="session_uuid"
         nonce={sessionNonce}
+        session={session}
         billingApiUrl="https://billing.example.com"
         email="user@example.com"
         userId="user_1"
-        totalAmount={29.99}    // dollars (for PayPal Elements config)
+        totalAmount={2999}     // cents
         currency="usd"
-        showPayPal={true}      // default: true
+        enabledPaymentMethods={session.gateways?.stripe?.enabledPaymentMethods}
         onComplete={(result) => {
           if (result.status === 'succeeded') {
             window.location.href = '/success';
@@ -493,26 +423,33 @@ function CheckoutPage() {
 }
 ```
 
-The `SplitCardForm` layout:
-1. Wallet buttons — Apple Pay + Google Pay (via ExpressCheckoutElement in the main Elements instance)
-2. PayPal button (via ExpressCheckoutElement in a separate Elements instance)
-3. "or pay with card" divider
-4. Card Number input
-5. Card Expiry + CVC side by side
-6. Full Name input
-7. Submit button
+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.
+
+Wallets, APMs, and PayPal create intents through
+`POST /v1/checkouts/sessions/{id}/intents`. The discriminated request separates
+provider, payment-method category/type/id, and intent kind. Direct-card intent
+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`.
 
 #### 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.
+country before the hosted vault captures the card**.
 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)
+- **Supported country + malformed postcode** → the vault widget's submit is blocked
   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
@@ -553,17 +490,18 @@ best-effort **in parallel** with the widget's charge:
 
 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
+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.
 
-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:
+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)
@@ -572,9 +510,8 @@ session includes a hosted vault card form (session.vault)
   → 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`.
+- The widget HTML normally comes from embedded `session.vault.html`; the explicit
+  recovery/retry path is `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`.
@@ -584,9 +521,10 @@ session includes a hosted vault card form (session.vault)
 
 > **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
+> success redirect), handle the 3DS step internally, and use the session account
+> snapshot for AVS. The SDK collects and validates those address fields outside
+> the PCI widget and persists them through the session account endpoint; the
+> widget owns only sensitive card-data capture. 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
@@ -598,12 +536,35 @@ session includes a hosted vault card form (session.vault)
 The SDK supports two PayPal paths, selected per-session based on what the billing API advertises under `gateways.*`:
 
 - **Direct PayPal** (preferred where available — works inside Facebook, Instagram, and other in-app browsers): when the session exposes `gateways.paypal.publishableKey`, the SDK renders PayPal via the official PayPal JS SDK using `<DirectPayPalButton>`. The PayPal client ID and `environment` (`'sandbox'`/`'live'`) come directly from the backend.
-- **Stripe-rendered PayPal fallback** (legacy): when only `gateways.stripe` is configured, PayPal renders through Stripe's `ExpressCheckoutElement` in its own Elements wrapper. This path can't render in Facebook/Instagram in-app browsers.
+- **Stripe-rendered PayPal**: when only `gateways.stripe` is configured, PayPal renders through Stripe's `ExpressCheckoutElement` in its own Elements wrapper. This path can't render in Facebook/Instagram in-app browsers.
 
 Renderer selection is mutually exclusive per session — direct PayPal takes priority over Stripe-rendered PayPal. Consumer props such as `showPayPal` continue to gate visibility on the client side.
 
 **PayPal-only sessions:** When the backend advertises only `gateways.paypal` (no `gateways.stripe`), `FloPayCheckout` skips Stripe Elements entirely and renders `<DirectPayPalButton>` as the sole payment surface. Sessions that advertise no supported gateway at all throw a `validation_error` explaining the expected shape.
 
+**Direct PayPal initialization recovery:** PayPal's own cross-window bridge owns
+its 10-second `postMessage init()` acknowledgement deadline; FloPay does not
+change that upstream timeout. If the exact acknowledgement timeout is reported,
+or if `Buttons.render()` is still unsettled after 11 seconds, the SDK hides
+Direct PayPal, waits one second, and makes exactly one background render retry.
+The retry uses a fresh render generation, and callbacks or promise settlements
+from the superseded generation are ignored.
+
+In a mixed checkout, card, wallets, APMs, and any other eligible methods remain
+interactive throughout recovery. If both Direct PayPal attempts fail, PayPal
+stays hidden for that component configuration; the SDK emits one sanitized
+console diagnostic and calls neither `onError` nor `onDecline`. Deterministic
+configuration failures and `isEligible() === false` are not automatically
+retried.
+
+In a PayPal-only checkout, `FloPayCheckout` shows an accessible retrying status
+instead of a blank surface. After automatic recovery is exhausted, it shows safe
+generic unavailable copy and a **Retry PayPal** button. `onError` fires once with
+a `FloPayError` whose `type` is `api_error` and whose stable `code` is
+`paypal_init_timeout`; `onDecline` does not fire and the raw provider message is
+never rendered. Manual retry reuses the current checkout session and performs
+one fresh render attempt without adding another automatic retry.
+
 The SDK exposes the relevant pieces in three ways:
 
 - **`SplitCardForm`** / **`FloPayCheckout`**: pick the renderer automatically based on `gateways.*`. No additional configuration needed.
@@ -615,7 +576,7 @@ The SDK exposes the relevant pieces in three ways:
 - **`PayPalButton`** (standalone): Must be rendered inside its own `FloPayProvider`:
 
 ```tsx
-{/* Card fields provider */}
+{/* Main checkout provider */}
 <FloPayProvider flopay={flopay} options={{ amount, currency }}>
   <SplitCardForm ... />
 </FloPayProvider>
@@ -631,31 +592,30 @@ The SDK exposes the relevant pieces in three ways:
 </FloPayProvider>
 ```
 
-### Using Individual Elements
+### Using Individual Non-card Elements
 
 ```tsx
-import { FloPayProvider, PaymentElement, CardElement, useFloPay } from '@flopay/react';
+import { AddressElement, PaymentElement } from '@flopay/react';
 
 function CustomForm() {
-  const flopay = useFloPay();
-
-  const handleSubmit = async () => {
-    if (!flopay) return;
-    const { error } = await flopay.submitElements();
-    if (error) return console.error(error);
-    const { paymentMethodId } = await flopay.createPaymentMethod();
-    // Use paymentMethodId...
-  };
-
   return (
     <div>
-      <PaymentElement options={{ layout: 'tabs' }} />
-      <button onClick={handleSubmit}>Pay</button>
+      <PaymentElement
+        options={{
+          layout: 'tabs',
+          paymentMethodTypes: ['cashapp', 'ideal'],
+        }}
+      />
+      <AddressElement />
     </div>
   );
 }
 ```
 
+These elements support wallet/APM and address collection. `PaymentElement`
+requires a non-empty `paymentMethodTypes` allowlist and rejects `card`; use the
+hosted vault checkout surface for card payments.
+
 ### Using Hooks
 
 ```tsx
@@ -678,15 +638,12 @@ function PaymentStatus() {
 | Component | Description |
 |-----------|-------------|
 | `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. 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()`. |
+| `FloPayCheckout` | Recommended self-contained session checkout. Resolves gateways, mounts hosted-vault cards, and preserves wallets/APMs/PayPal/saved-payment flows. |
+| `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'`. |
-| `PaymentElement` | Unified payment element (cards, wallets, etc.) |
-| `CardElement` | Combined card input |
-| `CardNumberElement` | Card number field |
-| `CardExpiryElement` | Card expiry field |
-| `CardCvcElement` | Card CVC field |
+| `DirectPayPalButton` | Standalone direct PayPal order/subscription button using the session-scoped intent contract. |
+| `PaymentElement` | Provider element for an explicitly declared non-card `paymentMethodTypes` allowlist. |
 | `AddressElement` | Address input element |
 
 ### Hooks
@@ -704,9 +661,9 @@ function PaymentStatus() {
 | `flopay` | `Promise<FloPay> \| FloPay` | SDK instance or promise from `loadFloPay()` |
 | `options.locale` | `string?` | Locale |
 | `options.appearance` | `FloPayAppearance?` | Theme appearance |
-| `options.clientSecret` | `string?` | PaymentIntent client secret (if intent already exists) |
-| `options.amount` | `number?` | Amount in cents (used when no `clientSecret`) |
-| `options.currency` | `string?` | ISO 4217 currency code (used when no `clientSecret`) |
+| `options.clientSecret` | `string?` | Existing non-card PaymentIntent or SetupIntent secret; the SDK verifies the provider intent against `PaymentElement`'s explicit wallet/APM allowlist before mounting and rejects card or undeclared methods. Card checkout uses the hosted vault. |
+| `options.amount` | `number?` | Amount in cents for deferred non-card Elements without a `clientSecret` |
+| `options.currency` | `string?` | ISO 4217 currency code for deferred non-card Elements without a `clientSecret` |
 | `options.paymentMethodCreation` | `'manual' \| 'auto'` | How payment methods are created |
 
 ### Privacy-safe operational telemetry
@@ -727,38 +684,19 @@ No endpoint, custom tag, user context, message, stack, or metadata can be
 configured. See [`docs/TELEMETRY.md`](../../docs/TELEMETRY.md) for the complete
 privacy and retention contract.
 
-### CheckoutFormProps
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `sessionId` | `string` | Checkout session UUID |
-| `billingApiUrl` | `string` | Billing API base URL |
-| `email` | `string?` | User email |
-| `userId` | `string?` | User ID |
-| `onComplete` | `(result: PaymentResult) => void` | Success callback |
-| `onError` | `(error: FloPayError) => void` | Error callback |
-| `onTokenizedBody` | `(body: TokenizedBody) => void` | Override: handle backend submission yourself |
-| `layout` | `'tabs' \| 'accordion' \| 'auto'` | PaymentElement layout (default: `'auto'`) |
-| `submitLabel` | `string` | Button text (default: `'Pay'`) |
-| `showAddress` | `boolean \| 'billing' \| 'shipping'` | Show address element (default: `false`) |
-| `className` | `string?` | CSS class for form wrapper |
-| `children` | `ReactNode?` | Custom submit button |
-| `firstName` | `string?` | Billing first name |
-| `lastName` | `string?` | Billing last name |
-| `chv` | `string?` | Checkout version for A/B tracking |
-| `isProcessing` | `boolean?` | External processing state |
-| `error` | `string?` | External error message |
-| `onErrorChange` | `(error: string \| null) => void` | Error state change callback |
-
 ### SplitCardFormProps
 
-Shares most props with `CheckoutFormProps`, plus:
+Key payment-surface props include:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `showStripe` | `boolean` | Show the whole Stripe surface (card + ECE + PaymentElement). Default: `true`. Setting `showStripe={false}` together with `showPayPal={false}` (or no PayPal gateway) emits a `FloPayError({ type: 'validation_error' })` via `onError`. |
+| `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. |
+| `billingApiUrl` | `string` | Billing API base URL. |
+| `showStripe` | `boolean` | Show Stripe-backed wallets/APMs. Card checkout is controlled by the session vault capability. |
 | `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 (everything else; `card` is always dropped because the split fields render the card path). |
+| `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. |
 | `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. |
@@ -766,7 +704,7 @@ Shares most props with `CheckoutFormProps`, plus:
 | `currency` | `string` | Currency code for PayPal / wallet config (default: `'usd'`) |
 | `onFirstNameChange` | `(value: string) => void` | First name change callback |
 | `onLastNameChange` | `(value: string) => void` | Last name change callback |
-| `submitLabel` | `string` | Button text (default: `'CONFIRM PAYMENT'`) |
+| `onComplete` / `onDecline` / `onError` | callbacks | Observable checkout outcomes. |
 
 ### ElementComponentProps (shared by all element components)
 
@@ -787,10 +725,7 @@ Shares most props with `CheckoutFormProps`, plus:
 | Type | Description |
 |------|-------------|
 | `FloPayProviderProps` | Props for `FloPayProvider` |
-| `CheckoutFormProps` | Props for `CheckoutForm` |
-| `CheckoutFormRef` | Ref type: `{ handleNextAction(clientSecret) }` |
 | `SplitCardFormProps` | Props for `SplitCardForm` |
-| `SplitCardFormRef` | Ref type: `{ handleNextAction(clientSecret) }` |
 | `PayPalButtonProps` | Props for `PayPalButton` |
 | `ElementComponentProps` | Shared props for all element components |
 | `CheckoutState` | `{ session, loading, error }` |