@flopay/js 1.9.19 → 1.9.21

package/README.md

@@ -43,7 +43,7 @@ mounting provider UI. Use `FloPayCheckout` or `SplitCardForm` from
 - `getUnifiedCheckoutSession(sessionId, nonce)` reads and normalizes a session.
 - `createSessionIntent(sessionId, nonce, request)` creates a Stripe wallet/APM or direct-PayPal intent. The request is a discriminated union of provider, payment-method category, type, and id, and intent kind; direct-card requests are not representable.
 - `reportSessionIntentDecline(sessionId, nonce, request)` reports a client-observed non-card decline using a classification code only. Messages, identifiers, card data, credentials, and personal data are rejected before sending.
-- `processPayment(userId, params)` submits a saved or approved non-card payment to the session's `/process` route. When the billing API answers `202`, the SDK keeps polling the session until it completes or times out.
+- `processPayment(userId, params)` submits a saved or approved non-card payment to the session's `/process` route. When the billing API answers `202`, the SDK follows its authenticated status endpoint until the latest transaction attempt succeeds, authorizes, declines, requires buyer action, fails, or times out.
 - `getPaymentsByEmail(email)` looks up prior payments for a saved-payment experience.
 
 ### Create a hosted checkout session
@@ -87,20 +87,23 @@ For detached creation, `timeoutMs` is a fresh per-phase budget: the shell POST g
 
 ### Server-side card gateways (Worldpay)
 
-The billing API can process hosted-vault cards through an approved Worldpay Corporate Gateway entirely server-side. Whether a session can use it is the billing API's decision, made from the merchant's active gateways and their Operations-approved capability record. `PaymentAPI` sends no capability token, gateway hint, or provider selection on any create, so the same request works for every SDK version and integration style. Everything stays provider-neutral, so existing integrations change nothing:
+The billing API can process hosted-vault and eligible saved cards through an approved Worldpay Corporate Gateway entirely server-side. Whether a session can use it is the billing API's decision, made from the merchant's active gateways and the saved method's eligibility. `PaymentAPI` sends no gateway hint, provider selection, eligibility assertion, merchant code, or scheme reference. Everything stays provider-neutral, so existing integrations change nothing:
 
 - Cards still go through the hosted card form, from the embedded `vault` block or `getVaultCapture()`. There is no Worldpay browser SDK, key, or credential: `gateways.worldpayCorporateGateway` has a `null` publishable key and no enabled methods, and it never appears in the normalized `providers` list.
 - Outcomes arrive as the same `complete`, `decline`, and `error` events. Declines use FloPay's decline taxonomy, never a raw processor code. An ambiguous submission stays pending until the billing API reconciles it; the hosted form reports that as an `error`, never a success, and a later session read returns the reconciled status.
-- Worldpay takes one-time item carts only and offers no 3DS authentication, stored credentials, or card setup; the billing API keeps subscription carts on another card gateway.
+- Cardholder authentication (3DS) resumes through the same provider-neutral continuation as every other card gateway. The hosted form reports `action_required` with a Flo-hosted challenge URL, the adapter renders that URL in its own modal overlay, and the outcome is resolved server-side before the hosted form reports the terminal `complete`, `decline`, or `error`. No Worldpay or authentication-provider script, merchant code, ACS URL, or token reaches the browser.
+- Eligible saved-card Auto, Confirm, returning-buyer, and subscription checkouts call the same provider-neutral `/process` route without `tokenizedData`. Immediate success and authorization use the existing Flo shapes; a `202 checkout_processing` response is reconciled through its nonce-protected status URL, including decline, buyer action, and terminal error states.
+- When a saved method cannot be used, `stored_payment_method_unsupported` is preserved as an actionable Flo error with the instruction to choose another payment method. The SDK never silently switches to a different charging behavior. Scheduled subscription rebills, retries, dunning, and stored-credential eligibility remain billing-API responsibilities.
 
-Auto, Confirm, and pre-tokenized sessions charge a stored payment method, which the Worldpay route does not accept; the billing API keeps those on the released Stripe and PayPal routing by itself. Do not add gateway selection, capability headers, or provider-specific branches to a create request, whether through this SDK or a request you build yourself: the billing API owns that decision, and a client-side copy of it would become a second routing authority that drifts from the merchant's real gateway state.
+`PaymentAPI` Auto creates advertise only the generic `async-auto-checkout-v1` response capability so the billing API may return the asynchronous status envelope. It is not a Worldpay capability or routing request; Confirm and Full creates send no capability header. Do not add gateway selection or provider-specific branches to a create request, whether through this SDK or a request you build yourself: the billing API owns that decision.
 
 ### Hosted card capture
 
 `flopay.cardCapture()` returns a `CardCaptureAdapter` that injects the billing API's self-contained hosted card form. The form owns the PCI card fields, its own submit button, tokenization, the charge (created and confirmed server-side), 3DS, and the result, so **no Stripe.js runs on the card path** and card numbers never enter the SDK runtime. The SDK injects the form and relays its terminal outcome.
 
 - Use the session's embedded `vault` block when present. Otherwise fetch one with `PaymentAPI.getVaultCapture(sessionId, nonce)` for a session whose Stripe `enabledPaymentMethods` explicitly includes `card`, or that advertises `gateways.worldpayCorporateGateway`. `getVaultCapture()` shares one active request between concurrent callers, aborts a stalled attempt after ten seconds, and retries transient network failures on the idempotent `POST /v1/checkouts/sessions/{id}/vault/capture` route.
-- Outcome events are `ready`, `complete`, `decline`, and `error`. The form is injected same-window, so the adapter rejects terminal outcomes that are not bound to the mounted session, that mismatch the block's `messageToken`, or that arrive from a different `expectedOrigin`. Pass both from the vault block to `mount()`.
+- Outcome events are `ready`, `complete`, `decline`, and `error`; `challenge_dismissed` is a non-terminal notification that the buyer closed the authentication challenge. The form is injected same-window, so the adapter rejects terminal outcomes that are not bound to the mounted session, that mismatch the block's `messageToken`, or that arrive from a different `expectedOrigin`. Pass both from the vault block to `mount()`.
+- When the buyer's bank asks for authentication, the hosted form hands the challenge up to the adapter, which renders the provider-hosted URL in a full-page modal overlay (`role="dialog"`, `aria-modal`, focus moved into the challenge and restored on teardown) above any processing backdrop. The challenge is not an outcome: it reaches no listener, and the challenge URL never appears in an event or in telemetry. The hosted form resolves the outcome and reports it as the usual `complete`, `decline`, or `error`; if nothing comes back at all, the overlay closes itself after the hosted form's own authentication window and reports an `error`. Closing the overlay abandons the challenge and reports the non-terminal `challenge_dismissed` event, so the host can take down its processing state and leave the form retryable straight away; it is not an outcome, and a late `complete`, `decline`, or `error` from the hosted form still reaches your listeners.
 - A `complete` event's `intentId` is the processing gateway's own reference. It is a Stripe PaymentIntent (or SetupIntent) id only when Stripe took the card; for a server-side card gateway it may be an opaque order reference. Reconcile by `paymentId` and the session instead.
 - For a merchant-server-created no-charge setup session, create the adapter with `operation: 'card_setup'`. A `complete` event may then carry a display-only `paymentMethod` (FloPay id, brand, last four, expiry, and status).
 - `capture.applyTheme(theme)` re-skins the mounted form without remounting; `applyTheme(null)` is the explicit classic reset. Theming is cosmetic and never blocks capture.
@@ -117,7 +120,7 @@ posted only when the vault block supplied both `messageToken` and
 { source: 'flopay-vault-host', type: 'submitLabel', sessionId, messageToken, label }
 ```
 
-A form mounted without those fields (an older billing API) keeps its default. The label is never added to telemetry. The other host directives (theme, submit gate, field order, and the 3DS `action_completed` signal) also target the exact `expectedOrigin` when one was supplied, falling back to `'*'` only for a widget mounted without it.
+A form mounted without those fields (an older billing API) keeps its default. The label is never added to telemetry. The other host directives (theme, submit gate, and field order) also target the exact `expectedOrigin` when one was supplied, falling back to `'*'` only for a widget mounted without it. There is no host directive for authentication: the hosted form accepts no completion signal from the page, because the outcome of a challenge is resolved server-side.
 
 ### Privacy-safe operational telemetry
 
@@ -328,7 +331,8 @@ await api.reportSessionIntentDecline('session_uuid', 'session_nonce', {
 | `claimCheckoutSession(sessionId, nonce, payload)` | `Promise<NormalizedCheckoutSession>` | Sends a `PATCH /v1/checkouts/sessions/{id}/claim` |
 | `createSessionIntent(sessionId, nonce, request, options?)` | `Promise<SessionIntent>` | Creates a Stripe wallet/APM or direct-PayPal intent |
 | `reportSessionIntentDecline(sessionId, nonce, request, options?)` | `Promise<void>` | Reports a non-card decline classification |
-| `processPayment(userId, params, options?)` | `Promise<Response>` | Submits a saved or approved non-card payment to `/process`, polling while the billing API is still processing |
+| `processPayment(userId, params, options?)` | `Promise<Response>` | Submits a saved or approved non-card payment to `/process`; a `202` follows the advertised authenticated status endpoint and maps terminal attempt outcomes back to the existing process response shapes |
+| `waitForCheckoutSessionCompletion(sessionId, options?)` | `Promise<NormalizedCheckoutSession>` | Waits for terminal state; pass the session `nonce` and a processing response's `statusUrl` to reconcile attempt-level success, authorization, decline, buyer action, and failure |
 | `getPaymentsByEmail(email, options?)` | `Promise<{ data, total, page, limit }>` | Lists prior payments for an email |
 | `destroy()` | `void` | Tears down the client's telemetry |
 
@@ -366,6 +370,7 @@ Failures reject with `FloPayError` from `@flopay/shared`. Branch on `type` and `
 | `InvalidCheckoutSessionResponse` | `api_error` | The billing API returned a malformed session or no session id. |
 | `session_auto_completed` | `api_error` | Inline creation found a payment method already on file and completed the session without a checkout. |
 | `checkout_processing_timeout` | `api_error` | `processPayment()` stopped polling while the checkout was still processing. Read the session again shortly. |
+| `stored_payment_method_unsupported` | `api_error` | The backend-selected saved method cannot be used for this transaction. Ask the buyer to choose another payment method; the SDK does not silently change payment behavior. |
 | `vault_capture_timeout` | `api_error` | `getVaultCapture()` did not return the hosted card form within ten seconds. |
 | `card_capture_no_window` | `api_error` | `PciVaultCardCapture.mount()` ran outside a browser. |
 | `card_capture_no_widget_html` | `api_error` | `PciVaultCardCapture.mount()` was called without hosted form HTML. |

package/dist/{card-setup-Bste6_2o.d.cts → card-setup-Bo_lUHo9.d.cts}

@@ -419,8 +419,21 @@ declare class PaymentAPI {
          * `GET /v1/checkouts/sessions/:id`. Required by post-#640 backends.
          */
         nonce?: string;
+        /** Advertised authenticated attempt-status endpoint from a `202` response. */
+        statusUrl?: string;
+        /**
+         * Keep polling after an `ACTION_REQUIRED` attempt. Challenge UIs use this
+         * while the backend resolves the buyer's completed action server-side;
+         * ordinary callers still receive the action immediately.
+         */
+        continueAfterActionRequired?: boolean;
         paymentMethodCategory?: TelemetryPaymentMethodCategory;
+        /** Cancels polling when the owning UI lifecycle ends. */
+        signal?: AbortSignal;
     }): Promise<NormalizedCheckoutSession>;
+    private resolveCheckoutSessionStatus;
+    private waitForCheckoutStatus;
+    private fetchCheckoutStatus;
     /** Normalize a raw session into a provider-agnostic shape. */
     private normalizeRawSession;
     /** Convert raw session to the SDK CheckoutSession shape. */
@@ -433,6 +446,7 @@ declare class PaymentAPI {
     private toVaultBlock;
     private toCheckoutSessionStatus;
     private resolveProcessResponse;
+    private toProcessResponseFromStatus;
     private reconcileProcessPayment;
     private toProcessResponseFromSession;
     private toCheckoutProcessingPending;
@@ -503,14 +517,21 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     private actionOverlay;
     /**
      * Listener that catches the `flopay-vault-3ds-return` postMessage from the
-     * provider's challenge return page. When the SDK owns the challenge iframe
-     * the return page lives inside *that* iframe (not the widget's), so
-     * `window.parent` is the host page — the widget's existing message
-     * listener can't see it. The SDK forwards completion into the widget via
-     * `action_completed` so the widget kicks `/3ds/complete` immediately
-     * instead of waiting on the eventual provider webhook.
+     * challenge return page. It is an overlay-dismissal accelerator only: the
+     * terminal outcome is resolved server-side on `/vault/3ds/return` and
+     * reaches the SDK through the widget's own `/status` poll. There is
+     * deliberately no client-side completion bridge back into the widget
+     * (TeamFloPay/backend#1674).
      */
     private threeDsReturnHandler;
+    /**
+     * Element that held focus when the challenge overlay opened, restored on
+     * teardown. A keyboard or screen-reader buyer would otherwise be stranded on
+     * the obscured page behind the modal once the challenge is gone.
+     */
+    private actionOverlayPreviousFocus;
+    /** Bound on how long the challenge overlay may stay up (see above). */
+    private actionOverlayTimer;
     /** Per-session integrity token to require on outcomes (from mount options). */
     private messageToken;
     /** Strict origin to require on outcomes, when configured. */
@@ -619,22 +640,39 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      *
      * The overlay tears down on the next terminal outcome
      * (`complete`/`decline`/`error`) or when the buyer closes it via the backdrop
-     * close button. Closing manually is a soft abandon — the next `/status` poll
-     * either reveals a real outcome (the challenge completed via the issuer's
-     * own redirect to `/vault/3ds/return`, which posts back into the widget) or
-     * surfaces `requires_action` again so the host can decide what to do.
+     * close button. Closing manually is a soft abandon — it emits the
+     * non-terminal `challenge_dismissed` so the host can drop its processing
+     * backdrop, while the widget keeps polling `/status` and still owns the
+     * eventual outcome (an out-of-band approval can land after the challenge is
+     * gone).
      */
     private showActionRequiredOverlay;
     /**
-     * Tell the vault widget that the buyer has completed (or abandoned) the
-     * challenge. The widget responds by POSTing `/3ds/complete` — its
-     * sub-300ms sync resolver writes the follow-up attempt row immediately,
-     * so the next `/status` poll resolves to a terminal outcome instead of
-     * waiting for the eventual provider webhook. Best-effort — even if the
-     * postMessage fails the widget's poll loop will eventually catch the
-     * terminal state from the provider webhook.
+     * (Re)start the overlay bound. Deliberately longer than the widget's own
+     * `/status` poll window so the widget's deterministic timeout lands first;
+     * this only fires when nothing at all came back.
+     */
+    private armActionRequiredTimeout;
+    /**
+     * Report a challenge the buyer never finished. Both ways out of a challenge
+     * without an outcome — closing the overlay, or never coming back at all —
+     * are the same `customer_abandoned` terminal event.
+     */
+    private reportChallengeAbandoned;
+    /**
+     * Tear the challenge down and give the buyer a terminal, provider-neutral
+     * error. Unlike a manual close, nothing is left to come back to, so this also
+     * ends the attempt for the host.
+     */
+    private timeOutActionRequiredOverlay;
+    /**
+     * The buyer closed the challenge. Report it as abandoned and tell the host —
+     * `challenge_dismissed` is deliberately NON-terminal: the widget is still
+     * polling `/status` and a late `complete`/`decline`/`error` must still be
+     * delivered. Without it the host's processing backdrop (raised on
+     * `submitting`) would hold the buyer behind a modal for the rest of the
+     * widget's authentication window.
      */
-    private postActionCompleted;
     private abandonActionRequiredOverlay;
     private hideActionRequiredOverlay;
     /**

package/dist/{card-setup-Bste6_2o.d.ts → card-setup-Bo_lUHo9.d.ts}

@@ -419,8 +419,21 @@ declare class PaymentAPI {
          * `GET /v1/checkouts/sessions/:id`. Required by post-#640 backends.
          */
         nonce?: string;
+        /** Advertised authenticated attempt-status endpoint from a `202` response. */
+        statusUrl?: string;
+        /**
+         * Keep polling after an `ACTION_REQUIRED` attempt. Challenge UIs use this
+         * while the backend resolves the buyer's completed action server-side;
+         * ordinary callers still receive the action immediately.
+         */
+        continueAfterActionRequired?: boolean;
         paymentMethodCategory?: TelemetryPaymentMethodCategory;
+        /** Cancels polling when the owning UI lifecycle ends. */
+        signal?: AbortSignal;
     }): Promise<NormalizedCheckoutSession>;
+    private resolveCheckoutSessionStatus;
+    private waitForCheckoutStatus;
+    private fetchCheckoutStatus;
     /** Normalize a raw session into a provider-agnostic shape. */
     private normalizeRawSession;
     /** Convert raw session to the SDK CheckoutSession shape. */
@@ -433,6 +446,7 @@ declare class PaymentAPI {
     private toVaultBlock;
     private toCheckoutSessionStatus;
     private resolveProcessResponse;
+    private toProcessResponseFromStatus;
     private reconcileProcessPayment;
     private toProcessResponseFromSession;
     private toCheckoutProcessingPending;
@@ -503,14 +517,21 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
     private actionOverlay;
     /**
      * Listener that catches the `flopay-vault-3ds-return` postMessage from the
-     * provider's challenge return page. When the SDK owns the challenge iframe
-     * the return page lives inside *that* iframe (not the widget's), so
-     * `window.parent` is the host page — the widget's existing message
-     * listener can't see it. The SDK forwards completion into the widget via
-     * `action_completed` so the widget kicks `/3ds/complete` immediately
-     * instead of waiting on the eventual provider webhook.
+     * challenge return page. It is an overlay-dismissal accelerator only: the
+     * terminal outcome is resolved server-side on `/vault/3ds/return` and
+     * reaches the SDK through the widget's own `/status` poll. There is
+     * deliberately no client-side completion bridge back into the widget
+     * (TeamFloPay/backend#1674).
      */
     private threeDsReturnHandler;
+    /**
+     * Element that held focus when the challenge overlay opened, restored on
+     * teardown. A keyboard or screen-reader buyer would otherwise be stranded on
+     * the obscured page behind the modal once the challenge is gone.
+     */
+    private actionOverlayPreviousFocus;
+    /** Bound on how long the challenge overlay may stay up (see above). */
+    private actionOverlayTimer;
     /** Per-session integrity token to require on outcomes (from mount options). */
     private messageToken;
     /** Strict origin to require on outcomes, when configured. */
@@ -619,22 +640,39 @@ declare class PciVaultCardCapture implements CardCaptureAdapter {
      *
      * The overlay tears down on the next terminal outcome
      * (`complete`/`decline`/`error`) or when the buyer closes it via the backdrop
-     * close button. Closing manually is a soft abandon — the next `/status` poll
-     * either reveals a real outcome (the challenge completed via the issuer's
-     * own redirect to `/vault/3ds/return`, which posts back into the widget) or
-     * surfaces `requires_action` again so the host can decide what to do.
+     * close button. Closing manually is a soft abandon — it emits the
+     * non-terminal `challenge_dismissed` so the host can drop its processing
+     * backdrop, while the widget keeps polling `/status` and still owns the
+     * eventual outcome (an out-of-band approval can land after the challenge is
+     * gone).
      */
     private showActionRequiredOverlay;
     /**
-     * Tell the vault widget that the buyer has completed (or abandoned) the
-     * challenge. The widget responds by POSTing `/3ds/complete` — its
-     * sub-300ms sync resolver writes the follow-up attempt row immediately,
-     * so the next `/status` poll resolves to a terminal outcome instead of
-     * waiting for the eventual provider webhook. Best-effort — even if the
-     * postMessage fails the widget's poll loop will eventually catch the
-     * terminal state from the provider webhook.
+     * (Re)start the overlay bound. Deliberately longer than the widget's own
+     * `/status` poll window so the widget's deterministic timeout lands first;
+     * this only fires when nothing at all came back.
+     */
+    private armActionRequiredTimeout;
+    /**
+     * Report a challenge the buyer never finished. Both ways out of a challenge
+     * without an outcome — closing the overlay, or never coming back at all —
+     * are the same `customer_abandoned` terminal event.
+     */
+    private reportChallengeAbandoned;
+    /**
+     * Tear the challenge down and give the buyer a terminal, provider-neutral
+     * error. Unlike a manual close, nothing is left to come back to, so this also
+     * ends the attempt for the host.
+     */
+    private timeOutActionRequiredOverlay;
+    /**
+     * The buyer closed the challenge. Report it as abandoned and tell the host —
+     * `challenge_dismissed` is deliberately NON-terminal: the widget is still
+     * polling `/status` and a late `complete`/`decline`/`error` must still be
+     * delivered. Without it the host's processing backdrop (raised on
+     * `submitting`) would hold the buyer behind a modal for the rest of the
+     * widget's authentication window.
      */
-    private postActionCompleted;
     private abandonActionRequiredOverlay;
     private hideActionRequiredOverlay;
     /**