@flopay/react 1.4.24 → 1.6.0

package/README.md

@@ -715,6 +715,20 @@ Renderer selection is mutually exclusive per session — direct PayPal takes pri
 
 **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.
 
+**Flo-owned subscription continuations:** `gateways.paypal.providerObjectType`
+selects the direct PayPal operation. `'order'` loads the PayPal SDK with
+`intent=capture` and invokes `createOrder`, even when the checkout session mode
+is subscription. `'subscription'` preserves the provider-managed
+`intent=subscription` / `createSubscription` flow. `'setup_token'` invokes
+`createVaultSetupToken`; approval submits the returned `vaultSetupToken` to the
+nonce-bound session `/process` route for backend exchange and activation. An
+advertised `'order'`/`'setup_token'` opts the intent request and tokenized
+process body into the `paypal_vaulted` payment-method channel; the intent
+response must match the advertised object type. When the field is absent,
+legacy sessions continue to derive Order versus Subscription from
+`isSubscription` and keep the released `paypal` requests byte-identical. See
+the full [channel-selection and cutover contract](../../docs/PAYPAL_FLO_SUBSCRIPTION_CONTINUATIONS.md).
+
 **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,
@@ -744,7 +758,7 @@ The SDK exposes the relevant pieces in three ways:
 
 - **`FloPayProvider`** (manual composition): accepts an optional `paypalFlopay` prop used to drive Stripe's PayPal redirect leg. Load a second `FloPay` instance yourself only if you need to render PayPal manually. `usePayPalFloPay()` exposes it to descendants.
 
-- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, and `isSubscription`.
+- **`DirectPayPalButton`** (standalone): can be rendered outside `SplitCardForm` when you only need the PayPal button. Pass `clientId`, `currency`, `environment`, `isSubscription`, and the backend-advertised `providerObjectType` when present. `isSubscription` remains the compatibility fallback when the field is absent.
 
 - **`PayPalButton`** (standalone): Must be rendered inside its own `FloPayProvider`:
 
@@ -816,7 +830,7 @@ function PaymentStatus() {
 | `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'`. |
-| `DirectPayPalButton` | Standalone direct PayPal order/subscription button using the session-scoped intent contract. |
+| `DirectPayPalButton` | Standalone direct PayPal Order, provider-managed Subscription, or setup-token button using the session-scoped intent contract. |
 | `PaymentElement` | Provider element for an explicitly declared non-card `paymentMethodTypes` allowlist. |
 | `AddressElement` | Address input element |