@flopay/js 1.2.7 → 1.3.0

package/README.md

@@ -199,10 +199,11 @@ try {
 | Export | Description |
 |--------|-------------|
 | `loadFloPay(publishableKey, options?)` | Initializes the SDK. Returns a `Promise<FloPay>`. Caches by key. |
-| `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `createPaymentMethod()`, `confirmCardPayment()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
+| `FloPay` | Main SDK class. Methods: `elements()`, `submitElements()`, `createPaymentMethod()`, `confirmCardPayment()`, `cardCapture()`, `confirmPayment()`, `confirmPayPalPayment()`, `resumePayPalPayment()`, `retrieveSession()`, `retrieveUnifiedSession()`, `getRawProvider()`, `destroy()` |
 | `FloPayElements` | Element group manager. Methods: `create(type, options?)`, `getElement(type)`, `submit()`, `destroy()` |
 | `StripeAdapter` | `PaymentProviderAdapter` implementation for Stripe |
-| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getUnifiedCheckoutSession()`, `processPayment()`, `waitForCheckoutSessionCompletion()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()` |
+| `PciVaultCardCapture` | `CardCaptureAdapter` implementation that injects the backend-served hosted vault card widget. See [Vault card capture](#vault-card-capture). |
+| `PaymentAPI` | Billing API client. Methods: `getCheckoutSession()`, `getVaultCapture()`, `getUnifiedCheckoutSession()`, `processPayment()`, `waitForCheckoutSessionCompletion()`, `createPaymentIntent()`, `createSetupIntent()`, `getPaymentsByEmail()` |
 | `createCheckoutSession(options)` | Creates a checkout session and redirects. Returns `CheckoutSessionResult`. |
 | `createCheckoutSessionWithRetries(options)` | Same as above with automatic retries (default 3, exponential backoff). |
 
@@ -214,6 +215,7 @@ try {
 | `submitElements()` | `Promise<{ error? }>` | Validates all mounted elements |
 | `createPaymentMethod()` | `Promise<CreatePaymentMethodResult>` | Tokenizes card fields into a `pm_xxx` ID. Auto-detects split fields vs unified PaymentElement. |
 | `confirmCardPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Confirms with `clientSecret` + `paymentMethodId`. Handles 3DS. |
+| `cardCapture(options?)` | `CardCaptureAdapter` | Creates a hosted vault card-widget adapter (`PciVaultCardCapture`). See [Vault card capture](#vault-card-capture). |
 | `confirmPayment(params)` | `Promise<PaymentResult>` | Confirms using mounted elements + `clientSecret` |
 | `confirmPayPalPayment(params)` | `Promise<ConfirmCardPaymentResult>` | Full PayPal flow: create PM -> create intent -> confirm/redirect |
 | `resumePayPalPayment()` | `Promise<ConfirmCardPaymentResult \| null>` | Resumes after PayPal redirect. Returns `null` if no PayPal params in URL. |
@@ -230,3 +232,44 @@ try {
 - `cardExpiry` -- Card expiry field
 - `cardCvc` -- Card CVC field
 - `address` -- Address input element
+
+### Vault card capture
+
+`flopay.cardCapture()` returns a `CardCaptureAdapter` that injects a
+**backend-served, self-contained hosted vault widget** in place of provider-owned
+(Stripe) card fields (TeamFloPay/backend#823, Model A). The widget owns the PCI
+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. The SDK's only job
+is to inject the widget HTML and relay its terminal `postMessage` outcome.
+
+```ts
+// 1. Obtain the vault capture block — embedded on the create-session response
+//    (session.vault) for SDKs ≥ 1.3.0, or fetched explicitly. The first
+//    argument is the checkout session id (`getVaultCapture(checkoutSessionId, nonce?)`):
+const { html, messageToken, expectedOrigin } =
+  await new PaymentAPI(billingApiUrl).getVaultCapture(checkoutSessionId, nonce);
+
+// 2. Inject it and relay the widget's outcome.
+const capture = flopay.cardCapture({ sessionId: checkoutSessionId });
+capture.on('complete', (e) => onComplete({ status: 'succeeded', paymentIntentId: e.intentId }));
+capture.on('decline', (e) => onDecline(e.declineReason, e.message));
+capture.on('error', (e) => onError(e.message));
+// Pass the block's `messageToken` / `expectedOrigin` so the adapter can
+// authenticate the widget's terminal postMessage (both optional).
+await capture.mount(container, { html, messageToken, expectedOrigin });
+```
+
+`CardCaptureAdapter` methods: `mount(container, { html, messageToken?, expectedOrigin? })`,
+`on(event, handler)` (`'ready' | 'complete' | 'decline' | 'error'`), `unmount()`.
+Outcome events arrive via a `window.postMessage` from the widget shaped
+`{ source: 'flopay-vault', type, sessionId, messageToken?, intentId?, declineReason?, message? }`.
+The widget is injected **same-window**, so `source` alone is forgeable: the
+adapter rejects terminal `complete` / `decline` outcomes that are not bound to
+the mounted `sessionId`, that mismatch the mounted `messageToken` (when one was
+supplied), or that arrive from a non-matching `expectedOrigin` (when set).
+
+> Backend contract: TeamFloPay/backend#823. The SDK declares
+> `X-Flo-SDK-Version: 1.3.0` (`FLO_SDK_VERSION_HEADER`) on `POST /v1/checkouts/sessions`
+> so the backend embeds the `vault` block; otherwise it fetches the widget via
+> `PaymentAPI.getVaultCapture()` (`POST /v1/checkouts/sessions/{id}/vault/capture`).