@flopay/react 1.9.20 → 1.9.21

package/README.md

@@ -133,12 +133,13 @@ Direct PayPal never hides its button behind a FloPay identity step: after approv
 
 #### Server-side card gateways (Worldpay)
 
-The billing API can route a checkout's cards to an approved Worldpay Corporate Gateway, processed entirely server-side behind the same hosted card form. Your checkout code does not change:
+The billing API can route hosted and eligible saved cards to an approved Worldpay Corporate Gateway, processed entirely server-side. Your checkout code does not change:
 
-- **No opt-in.** The billing API decides from the merchant's configured gateways whether a session can use Worldpay. The SDK sends no capability token or gateway hint, so routing is the same for every SDK version and create style. Auto, Confirm, and pre-tokenized sessions stay on the released routing because the billing API keeps them there, not because the SDK asks.
+- **No gateway choice.** The billing API selects the gateway and decides stored-credential eligibility. The SDK sends no gateway hint, Worldpay capability, merchant code, scheme reference, or eligibility assertion. An Auto create advertises only the provider-neutral `async-auto-checkout-v1` response capability; Confirm and Full creates do not send it.
 - **Same card surface.** No Stripe runtime, Worldpay SDK, or browser credential is involved. An open session that advertises `gateways.worldpayCorporateGateway` but omits the embedded card form recovers it on demand; a completed or authorized session is never shown the card form again.
-- **Same callbacks.** Success reaches `onComplete` as `status: 'succeeded'`, and a manual-capture hold as `status: 'authorized'` with `paymentId`, `sessionId`, and `authorizationExpiresAt`; `paymentIntentId` is omitted because the processor's reference is not a Stripe object. A refusal reaches `onDecline` with `authorization_declined`. A payment still reconciling when the form stops waiting reaches `onError`, never `onComplete`, and a later session read reports the settled status.
-- **Same authentication.** When the buyer's bank asks for 3DS, the SDK renders the provider-hosted challenge in a modal dialog over your page (`role="dialog"`, `aria-modal`, focus moved into the challenge and restored when it closes) and reports only the terminal outcome through the callbacks above. The challenge URL never reaches a callback or the instrument feed; the only signal is the opaque `3ds_challenge` instrument. Reloading a session still waiting on authentication re-presents the open challenge without reloading it and without charging the card again, and closing it takes the processing state down immediately and hands the buyer back to the card form, with its submit held until that attempt reports an outcome so a closed challenge can never start a second authorization — a server-resolved outcome that lands afterwards (an out-of-band bank approval, say) still reaches your callbacks.
+- **Same saved-card flow.** Returning-buyer Auto and Confirm checkouts, including subscription creation, call the provider-neutral `/process` route without card re-entry or `tokenizedData`. Immediate and asynchronously reconciled success, authorization, decline, and error outcomes reach the existing callbacks and UI states. Scheduled rebills, retry, dunning, credential eligibility, and reconciliation remain backend-owned.
+- **Explicit unsupported use.** `stored_payment_method_unsupported` reaches `onError` with the buyer-safe instruction to choose another payment method. The SDK does not silently switch behavior, and older backends that omit the optional code remain compatible.
+- **Same authentication.** When the buyer's bank asks for 3DS, the SDK renders the provider-hosted challenge in a modal dialog over your page (`role="dialog"`, `aria-modal`, focus moved into the challenge and restored when it closes), posts the existing provider-neutral `/3ds/complete` continuation once after the authenticated return, and reconciles the terminal attempt through `/status`. The challenge URL never reaches a callback, instrument, telemetry event, log, or browser storage; the only instrument signal is opaque `3ds_challenge`.
 - The merchant instrument feed's `card_expanded` event omits `gateway` for these sessions, because the billing API chooses the card's gateway.
 
 #### Themes and layouts
@@ -622,6 +623,7 @@ Checkout errors reach `onError` (and the `error` render prop) as `FloPayError` v
 | `external_payment_method_failed` | `api_error` | A wallet, PayPal, or alternative method failed technically after the buyer clicked it. The chooser offers a retry. |
 | `InvalidCardSetupSurface` | `validation_error` | `FloPayCheckout` was given a card-setup session; use `FloPayCardSetup`. |
 | `three_ds_aborted` / `three_ds_timeout` | `api_error` | The buyer cancelled, or did not finish, the authentication challenge for a saved card in confirm or auto mode. |
+| `stored_payment_method_unsupported` | `api_error` | The backend-selected saved method cannot be used for this transaction. Show the supplied buyer-safe instruction and let the buyer choose another method. |
 | `InvalidPaymentProcessResponse` | `api_error` | Saved-payment processing returned a response the SDK could not use. |
 
 A `validation_error` is also reported when both `showStripe` and `showPayPal` are false with no PayPal gateway, or when a session advertises no supported gateway. When saving the AVS billing address is rejected with a `4xx`, `onError` receives the parsed billing API error while the message shows inline; the buyer corrects it for the next attempt.