@flopay/react 1.9.14 → 1.9.16

package/README.md

@@ -109,7 +109,9 @@ Use `onInstrument` on `FloPayCheckout` or `FloPayProvider` to forward a stable,
 privacy-safe checkout funnel to your own analytics. The callback receives the
 exported `FloInstrumentEvent` discriminated union; `schemaVersion` is always `1`,
 and `gateway` is included as `stripe` or `paypal` only when the event is
-attributable to that payment provider. Hosted-vault events may omit `gateway`.
+attributable to that payment provider. Hosted-vault events may omit `gateway`,
+and `card_expanded` always does when the session can route cards to a
+[server-side card gateway](#server-side-card-gateways-worldpay).
 
 ```tsx
 import type { FloInstrumentEvent } from '@flopay/react';
@@ -205,6 +207,38 @@ its wording, for example with the amount the buyer is about to pay:
   The SDK sends the label only to that exact origin, bound to the checkout
   session. Against an older backend the hosted form keeps its default.
 
+#### Server-side card gateways (Worldpay)
+
+The billing API can route a checkout's cards to an approved Worldpay Corporate
+Gateway (TeamFloPay/backend#1563). It processes those payments entirely
+server-side behind the same hosted vault card form, so your checkout code does
+not change and never needs to know which gateway took the card:
+
+- **No opt-in.** The billing API decides from the merchant's configured
+  gateways whether a session can use Worldpay (TeamFloPay/backend#1641). 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.
+- **Same card surface.** `FloPayCheckout` and `SplitCardForm` mount the hosted
+  form with no Stripe runtime and no Worldpay browser SDK or credentials. When
+  a session read omitted the embedded vault block, an open session that
+  advertises `gateways.worldpayCorporateGateway` recovers the form from
+  `POST /v1/checkouts/sessions/{id}/vault/capture` instead of failing to mount.
+  A completed or authorized session is never offered the card form again.
+- **Same callbacks.** A success reaches `onComplete` as
+  `{ status: 'succeeded', checkoutMethod: 'card' }`, and a manual-capture hold
+  as `status: 'authorized'` with `paymentId`, `sessionId`, and
+  `authorizationExpiresAt`. `paymentIntentId` is omitted for these sessions
+  because the processor's order reference is not a Stripe object. A refusal
+  reaches `onDecline` with the stable `authorization_declined` code. A payment
+  the billing API is still reconciling when the hosted form stops waiting
+  reaches `onError`, never `onComplete`; a later session read reports the
+  settled status through `onComplete` or `onSessionCompleted`.
+- **Unattributed card funnel.** `card_expanded` omits `gateway` for these
+  sessions, because the billing API, not the browser, chooses the card's
+  gateway.
+
 ### Secure saved-card setup
 
 Use `FloPayCardSetup` to let a customer add or verify a card without creating a