@flopay/react 1.9.14 → 1.9.15

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:
+
+- **Opt-in on create.** An inline Full-mode checkout (`createSession`, or a
+  session created with `PaymentAPI.createAndFetchSession` /
+  `createDetachedSession`) declares the `worldpay-corporate-gateway-v1`
+  capability. Auto, Confirm, and pre-tokenized sessions do not, and neither do
+  older SDKs, so their routing is unchanged. See the `@flopay/js` README for the
+  wire contract.
+- **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