@amos.com/react-amos-js 0.11.15 → 0.11.18

package/README.md

@@ -44,7 +44,7 @@ The following flow is for credit card and bank account payment method types only
 4. **Create payment intent on your server**: use your server-side Amos client to call `POST /payment_intents`. You may also associate this payment intent with a new or existing customer via `POST /customers`. This must be server-side because it uses your private API key.
 5. **Return the payment intent token to the browser**: your backend responds with the embed token (`components["schemas"]["EmbedToken"]`) needed for confirmation.
 6. **Confirm the payment intent from the client**: `await confirmPayment({ iframeRef, token })`. It resolves `{ status: "succeeded", paymentIntent }`, `{ status: "failed", paymentIntent? }` on decline, or `{ status: "failed", error: "timeout" }` if the iframe does not respond within 15 seconds (`isConfirmTimeout(result)`).
-7. **Handle UX**: show the user a "processing" state while awaiting `confirmPayment`. Do not treat `{ status: "succeeded" }` as settlement proof — verify payment success on your backend via webhooks. Recoverable field errors stay in the iframe; a processor decline still resolves `{ status: "failed" }` (with `paymentIntent` when the confirm API returned a body, including `last_payment_error`). A timeout is **not** a decline — the charge may still settle; do not retry as a new payment.
+7. **Handle UX**: show the user a "processing" state while awaiting `confirmPayment`. Do not treat `{ status: "succeeded" }` as settlement proof — verify payment success on your backend via webhooks. Recoverable field errors stay in the iframe; a processor decline still resolves `{ status: "failed" }` (with `paymentIntent` when the confirm API returned a body — inspect `paymentIntent.state`). A timeout is **not** a decline — the charge may still settle; do not retry as a new payment.
 
 ### Google Pay & Apple Pay
 
@@ -580,13 +580,13 @@ Enter in a card or bank iframe field submits the enclosing host `<form>` via `re
 
 Renders the secure bank account iframe form. A field-shaped skeleton is shown immediately (sized from `appearance`, including resting `.Input` / `.Label` rules) and replaced by the iframe once appearance is applied.
 
-When `requireAchVerification` is true (or `intent` is `"setup"`), and the render token allows verification, the SDK hides the routing/account iframe and mounts [Plaid Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/) in the parent. Hosts do not proxy Pay API (`GET /merchants`, `POST /plaid_link_tokens`); embed does that with `PAY_API_KEY`. Do not put Plaid secrets in the browser.
+When `requireAchVerification` is true (or `intent` is `"setup"`), and the render token allows verification, the SDK hides the routing/account iframe and mounts [Plaid Embedded Institution Search](https://plaid.com/docs/link/embedded-institution-search/) in the parent. A **350px pulse skeleton** covers that slot until Plaid's `onLoad` (1.5s fallback). Do not overlay a host loader. Hosts do not proxy Pay API (`GET /merchants`, `POST /plaid_link_tokens`); embed does that with `PAY_API_KEY`. Do not put Plaid secrets in the browser.
 
 **Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken`.
 
 **Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `defaultValues`, `onValidityChange` (`isValid` is also true after Plaid returns credentials), `onEscapeKeyPressed` — plus:
 
-- `requireAchVerification` (`boolean`, defaults to `false`) — when true, show Plaid Embedded Link instead of routing/account fields. Ignored for `intent="setup"` (always Plaid) and when the render token has bank `verification: false`. Hosts that still have an ACH threshold should compute this themselves and pass a new value when the charge changes.
+- `requireAchVerification` (`boolean`, defaults to `false`) — when true, show Plaid Embedded Link instead of routing/account fields. Ignored for `intent="setup"` (always Plaid) and when the render token has bank `verification: false`. Hosts that still have an ACH threshold should compute this themselves and pass a new value when the charge changes. Changing this prop hides or shows Link; it does not remount the bank form or destroy the Embedded handler.
 - `intent` (`"payment" | "setup"`, defaults to `"payment"`) — `"setup"` always shows Plaid unless the render token disables verification. Use this when saving a bank account for later charges.
 
 ```tsx
@@ -695,12 +695,12 @@ Re-export from `@amos.com/amos-js`. Fills omitted Inter `fonts` / `--font-family
 ## Notes and potential gotchas
 
 - **`ref` / `iframeRef`**: for card and bank forms, pass `ref={iframeRef}` to the form component. The same `iframeRef` must be used when calling `validateForm`, `confirmPayment`, `confirmSetup`, `resetForm`, or `focusField`. The component forwards the ref to the inner iframe.
-- **`confirmPayment` / `confirmSetup` are not settlement proof**: `{ status: "succeeded" }` means authorization succeeded (capture may still finish asynchronously). Verify payment or setup success on your backend via webhooks. Recoverable field errors stay in the iframe; a processor decline still resolves `{ status: "failed" }`. Declined confirms include the intent so you can read `last_payment_error` without a follow-up GET. If the iframe never answers, the Promise resolves `{ status: "failed", error: "timeout" }` after 15 seconds (`CONFIRM_TIMEOUT_MS`, `isConfirmTimeout`) — that is uncertain, not a decline; do not retry as a new payment.
+- **`confirmPayment` / `confirmSetup` are not settlement proof**: `{ status: "succeeded" }` means authorization succeeded (capture may still finish asynchronously). Verify payment or setup success on your backend via webhooks. Recoverable field errors stay in the iframe; a processor decline still resolves `{ status: "failed" }`. Declined confirms include the intent so you can read `state` without a follow-up GET. If the iframe never answers, the Promise resolves `{ status: "failed", error: "timeout" }` after 15 seconds (`CONFIRM_TIMEOUT_MS`, `isConfirmTimeout`) — that is uncertain, not a decline; do not retry as a new payment.
 - **Same components for payment vs setup intents**: `AmosCreditCardPaymentMethodForm` and `AmosBankAccountPaymentMethodForm` support both payment intents and setup intents. The flow differs only by which server call you make and which confirmation function you use (`confirmPayment` vs `confirmSetup`).
 - **Amount format**: for `AmosGooglePayButton` and `AmosApplePayButton`, `amount` is a major-currency decimal string (e.g. `"50.00"` for $50.00). For `components["schemas"]["CreatePaymentIntentInput"]` on the server (card/bank create, and the object the wallet iframe sends to `onConfirm`), `amount` is a number in cents (e.g. `5000`).
 - **Embed host / CSP**: iframes load from `https://js.amos.com` (production) and `https://js-sandbox.amos.com` (sandbox) via `getEmbedOrigin`. Parent pages that pin CSP must allow `frame-src https://js.amos.com https://js-sandbox.amos.com` (and `Permissions-Policy payment=` for those origins) **before** upgrading this package. Older SDK versions still load `embed.amos.com` / `embed-sandbox.amos.com`.
 - **Iframe handshake**: iframe URLs include canonical search params so the embed does not 307. If the document loads but never posts `IFRAME_READY`, the SDK rewrites `src` once with `amosReload`. Appearance is applied after handshake; the iframe stays hidden until `UPDATED_APPEARANCE`, or for 1.5s after `IFRAME_READY` if appearance never acks.
-- **Plaid Embedded Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe mints link tokens. Pass `requireAchVerification` when the host wants Plaid, or `intent="setup"` to always show it, unless the render token disables verification. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method.
+- **Plaid Embedded Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe mints link tokens. Pass `requireAchVerification` when the host wants Plaid, or `intent="setup"` to always show it, unless the render token disables verification. Toggling that prop hides or shows the existing Embedded handler — it does not reload Institution Search. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method. While Link loads, the SDK shows a 350px pulse skeleton until `onLoad` (1.5s fallback) — do not overlay a host loader.
 - **Apple Pay waiting overlay**: on browsers where Apple's QR handoff opens in a popup (non-Safari), `AmosApplePayButton` shows a fixed full-viewport overlay on the host page. **Cancel payment** is available until the buyer authorizes; after that the overlay shows **Completing your payment…** with no Cancel, then hides when `onConfirm` settles. Avoid stacking other fixed UI above it.
 - **Going framework-free**: if you need to use Amos outside of React (vanilla JS, another framework, etc.), use [`@amos.com/amos-js`](../amos-js) directly.
 

package/dist/index.d.ts

@@ -131,9 +131,13 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     defaultValues?: PaymentMethodFormDefaultValues;
     /**
      * When true, hide the routing/account iframe and mount Plaid Embedded
-     * Institution Search in the parent. Ignored when `intent` is `"setup"`
-     * (setup always shows Plaid) or when the render token disables
-     * verification.
+     * Institution Search in the parent. A 350px pulse skeleton covers the
+     * slot until Plaid's `onLoad` (1.5s fallback). Ignored when `intent`
+     * is `"setup"` (setup always shows Plaid) or when the render token
+     * disables verification.
+     *
+     * Changing this prop hides or shows Link; it does not remount the
+     * bank form or destroy the Embedded handler.
      *
      * @default false
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.11.15",
+  "version": "0.11.18",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -57,7 +57,7 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.11.16",
+    "@amos.com/amos-js": "0.11.18",
     "@types/googlepay": "0.7.12"
   },
   "peerDependencies": {

package/src/index.tsx

@@ -411,9 +411,13 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
   defaultValues?: PaymentMethodFormDefaultValues;
   /**
    * When true, hide the routing/account iframe and mount Plaid Embedded
-   * Institution Search in the parent. Ignored when `intent` is `"setup"`
-   * (setup always shows Plaid) or when the render token disables
-   * verification.
+   * Institution Search in the parent. A 350px pulse skeleton covers the
+   * slot until Plaid's `onLoad` (1.5s fallback). Ignored when `intent`
+   * is `"setup"` (setup always shows Plaid) or when the render token
+   * disables verification.
+   *
+   * Changing this prop hides or shows Link; it does not remount the
+   * bank form or destroy the Embedded handler.
    *
    * @default false
    */
@@ -457,6 +461,8 @@ export function AmosBankAccountPaymentMethodForm({
       onValidityChange,
       onEscapeKeyPressed,
     },
+    // `requireAchVerification` is an update, not a remount: amos-js hides
+    // Embedded Link instead of destroying it when the flag flips.
     remountDeps: [renderToken, billingAddressRequirement, intent],
     iframePassthrough: { style, ...rest },
     updateDeps: [