@amos.com/react-amos-js 0.11.6 → 0.11.8

package/README.md

@@ -39,8 +39,8 @@ The render token configures the iframe's allowed origin(s), allowed payment meth
 The following flow is for credit card and bank account payment method types only.
 
 1. **Set up prerequisites**: create a `renderToken` (safe for client), and keep `apiKey` and `accountId` server-side only.
-2. **Render your checkout UI** with one of the payment method components (e.g. `AmosCreditCardPaymentMethodForm`). Card and bank forms show a field-shaped skeleton immediately (sized from `appearance`, `additionalFields`, and `billingAddressRequirement`); Google Pay and Apple Pay paint a button-shaped skeleton in the parent document on first render so the 48px slot is reserved before the iframe loads.
-3. **User clicks "Pay now" button**: call `validateForm({ iframeRef })`, which returns `Promise<true>` if the embedded form is valid and `Promise<false>` otherwise.
+2. **Render your checkout UI** with one of the payment method components (e.g. `AmosCreditCardPaymentMethodForm`) **inside a host `<form>`**. Card and bank forms show a field-shaped skeleton immediately (sized from `appearance`, `additionalFields`, and `billingAddressRequirement`); Google Pay and Apple Pay paint a button-shaped skeleton in the parent document on first render so the 48px slot is reserved before the iframe loads. Enter in the iframe submits that enclosing form (PCI-safe; no field values). No-op without a host form, or while Plaid Embedded Institution Search is showing.
+3. **User clicks "Pay now" or presses Enter in the iframe**: call `validateForm({ iframeRef })`, which returns `Promise<true>` if the embedded form is valid and `Promise<false>` otherwise.
 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 })`.
@@ -159,6 +159,8 @@ Radio groups (e.g. account type) always use an above-style group label regardles
 
 ### Rendering the credit card inputs within your custom form
 
+Wrap the component in a host `<form>`. Enter in the iframe submits it (same as Stripe Elements). The parent cannot listen for that key itself because the iframe is cross-origin. If you render the iframe inside a modal, pass `onEscapeKeyPressed` to close it — Escape inside the iframe is likewise invisible to the parent.
+
 ```tsx
 import { useRef, useState } from "react";
 import {
@@ -479,6 +481,9 @@ Renders the secure credit card iframe form. A field-shaped skeleton is shown imm
 - `billingAddressRequirement` (`"country" | "full"`, defaults to `"country"`) — how much billing address the iframe collects. `country` collects country / region and, for CA / PR / GB / US, a postal code (labeled ZIP for the United States). `full` shows a full street address form with Smarty autocomplete.
 - `onValidityChange` (`(event: { isValid: boolean }) => void`) — called when form validity changes. `isValid` is true when all required fields are present and valid. Does not include PCI data. Use this to enable or disable your checkout button.
 - `onCardBrandChanged` (`(event: { brand: CardBrand | null }) => void`) — called when the detected card brand changes. `brand` is `"visa"`, `"mastercard"`, `"amex"`, `"discover"`, `"diners"`, or `"jcb"`, or `null` when the field is empty or the number does not match a known brand. Does not include PCI data.
+- `onEscapeKeyPressed` (`() => void`) — called when the customer presses Escape in the iframe. PCI-safe — no field values. Use this to close a host modal that contains the iframe. Not fired while an iframe dropdown or address suggestion list is open, or while Plaid Embedded Institution Search is showing. The parent cannot attach a keydown listener for this itself because the iframe is cross-origin.
+
+Enter in a card or bank iframe field submits the enclosing host `<form>` via `requestSubmit()` (same as Stripe Elements). Handle that form's `onSubmit` — the parent page cannot see keys typed in the cross-origin iframe. No-op if the component is not inside a `<form>`, or while Plaid Embedded Institution Search is showing.
 
 **Also accepts:** standard iframe props (`React.ComponentProps<"iframe">`), minus `src`, `title`, `name`, and `role` (which are controlled by the SDK).
 
@@ -490,7 +495,7 @@ When `requireAchVerification` is true (or `intent` is `"setup"`), and the render
 
 **Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken`.
 
-**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `onValidityChange` (`isValid` is also true after Plaid returns credentials) — plus:
+**Optional props:** same as `AmosCreditCardPaymentMethodForm` — `appearance`, `billingAddressRequirement`, `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.
 - `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.

package/dist/index.d.ts

@@ -71,6 +71,14 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     onCardBrandChanged?: (event: {
         brand: "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | null;
     }) => void;
+    /**
+     * Called when the customer presses Escape in the iframe. PCI-safe —
+     * no field values. Use this to close a host modal that contains the
+     * iframe. Not fired while an iframe dropdown or address suggestion
+     * list is open, or while Plaid Embedded Institution Search is
+     * showing.
+     */
+    onEscapeKeyPressed?: () => void;
     additionalFields?: CreditCardAdditionalFields;
     billingAddressRequirement?: BillingAddressRequirement;
     /**
@@ -80,7 +88,7 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
      */
     defaultValues?: PaymentMethodFormDefaultValues;
 };
-export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, additionalFields, billingAddressRequirement, defaultValues, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onCardBrandChanged, onEscapeKeyPressed, additionalFields, billingAddressRequirement, defaultValues, style, ...rest }: AmosCreditCardPaymentMethodFormProps): import("react").JSX.Element;
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
@@ -92,6 +100,14 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     onValidityChange?: (event: {
         isValid: boolean;
     }) => void;
+    /**
+     * Called when the customer presses Escape in the iframe. PCI-safe —
+     * no field values. Use this to close a host modal that contains the
+     * iframe. Not fired while an iframe dropdown or address suggestion
+     * list is open, or while Plaid Embedded Institution Search is
+     * showing.
+     */
+    onEscapeKeyPressed?: () => void;
     billingAddressRequirement?: BillingAddressRequirement;
     /**
      * Seed account holder name and billing address. Provided keys
@@ -117,7 +133,7 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
      */
     intent?: "payment" | "setup";
 };
-export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, billingAddressRequirement, defaultValues, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
+export declare function AmosBankAccountPaymentMethodForm({ ref, renderToken, appearance, onValidityChange, onEscapeKeyPressed, billingAddressRequirement, defaultValues, requireAchVerification, intent, style, ...rest }: AmosBankAccountPaymentMethodFormProps): import("react").JSX.Element;
 type AmosGooglePayButtonProps = {
     ref?: ForwardedIframeRef;
     renderToken: string;

package/dist/index.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@amos.com/amos-js"),t=require("react"),n=require("react/jsx-runtime");function r(e){return e?e.current??null:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmPayment)({iframe:r(t),token:n,defaultValues:i})}function o({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmSetup)({iframe:r(t),token:n,defaultValues:i})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c({iframeRef:t,field:n}){(0,e.focusField)({iframe:r(t),field:n})}function l(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function u(e,{style:t,className:n,id:r,...i}){n!=null&&(e.className=n),r!=null&&(e.id=r),Object.assign(e.style,t);for(let[t,n]of Object.entries(i))n!=null&&(t in e?Reflect.set(e,t,n):e.setAttribute(t,String(n)))}function d({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let c=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return c.current=a,l(n,a.iframe),u(a.iframe,o),()=>{a.destroy(),c.current=null,l(n,null)}},[...a]),(0,t.useEffect)(()=>{c.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=c.current?.iframe;e&&u(e,o)})}var f=`oklch(0.97 0 0)`;function p({height:r,borderRadius:i,containerRef:a}){return(0,t.useLayoutEffect)(()=>{(0,e.ensureSkeletonStyles)()},[]),(0,n.jsxs)(`div`,{style:{boxSizing:`border-box`,position:`relative`,width:`100%`,height:r,minHeight:r,overflow:`hidden`},children:[(0,n.jsx)(`div`,{className:`amos-js-form-skeleton-input amos-js-wallet-skeleton`,style:{position:`absolute`,inset:0,height:r,borderRadius:i,background:f,pointerEvents:`none`,zIndex:0},"aria-hidden":!0}),(0,n.jsx)(`div`,{ref:a,style:{position:`absolute`,inset:0,zIndex:1,width:`100%`,height:`100%`}})]})}function m({ref:r,renderToken:i,appearance:a,onValidityChange:o,onCardBrandChanged:s,additionalFields:c={cardholderName:!1},billingAddressRequirement:l=`country`,defaultValues:u,style:f,...p}){let m=(0,t.useRef)(null);return d({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:c,billingAddressRequirement:l,defaultValues:u,onValidityChange:o,onCardBrandChanged:s},remountDeps:[i,c.cardholderName,l],iframePassthrough:{style:f,...p},updateDeps:[a,c,l,u,o,s]}),(0,n.jsx)(`div`,{ref:m})}function h({ref:r,renderToken:i,appearance:a,onValidityChange:o,billingAddressRequirement:s=`country`,defaultValues:c,requireAchVerification:l=!1,intent:u=`payment`,style:f,...p}){let m=(0,t.useRef)(null);return d({containerRef:m,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:s,defaultValues:c,requireAchVerification:l,intent:u,onValidityChange:o},remountDeps:[i,s,u],iframePassthrough:{style:f,...p},updateDeps:[a,s,c,l,u,o]}),(0,n.jsx)(`div`,{ref:m})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}function _({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}exports.AmosApplePayButton=_,exports.AmosBankAccountPaymentMethodForm=h,exports.AmosCreditCardPaymentMethodForm=m,exports.AmosGooglePayButton=g,exports.confirmPayment=a,exports.confirmSetup=o,exports.focusField=c,exports.resetForm=s,exports.validateForm=i,Object.keys(e).forEach(function(t){t!=="default"&&!Object.prototype.hasOwnProperty.call(exports,t)&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@amos.com/amos-js"),t=require("react"),n=require("react/jsx-runtime");function r(e){return e?e.current??null:null}function i({iframeRef:t}){return(0,e.validateForm)({iframe:r(t)})}function a({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmPayment)({iframe:r(t),token:n,defaultValues:i})}function o({iframeRef:t,token:n,defaultValues:i}){return(0,e.confirmSetup)({iframe:r(t),token:n,defaultValues:i})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c({iframeRef:t,field:n}){(0,e.focusField)({iframe:r(t),field:n})}function l(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function u(e,{style:t,className:n,id:r,...i}){n!=null&&(e.className=n),r!=null&&(e.id=r),Object.assign(e.style,t);for(let[t,n]of Object.entries(i))n!=null&&(t in e?Reflect.set(e,t,n):e.setAttribute(t,String(n)))}function d({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let c=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return c.current=a,l(n,a.iframe),u(a.iframe,o),()=>{a.destroy(),c.current=null,l(n,null)}},[...a]),(0,t.useEffect)(()=>{c.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=c.current?.iframe;e&&u(e,o)})}var f=`oklch(0.97 0 0)`;function p({height:r,borderRadius:i,containerRef:a}){return(0,t.useLayoutEffect)(()=>{(0,e.ensureSkeletonStyles)()},[]),(0,n.jsxs)(`div`,{style:{boxSizing:`border-box`,position:`relative`,width:`100%`,height:r,minHeight:r,overflow:`hidden`},children:[(0,n.jsx)(`div`,{className:`amos-js-form-skeleton-input amos-js-wallet-skeleton`,style:{position:`absolute`,inset:0,height:r,borderRadius:i,background:f,pointerEvents:`none`,zIndex:0},"aria-hidden":!0}),(0,n.jsx)(`div`,{ref:a,style:{position:`absolute`,inset:0,zIndex:1,width:`100%`,height:`100%`}})]})}function m({ref:r,renderToken:i,appearance:a,onValidityChange:o,onCardBrandChanged:s,onEscapeKeyPressed:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:u=`country`,defaultValues:f,style:p,...m}){let h=(0,t.useRef)(null);return d({containerRef:h,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:u,defaultValues:f,onValidityChange:o,onCardBrandChanged:s,onEscapeKeyPressed:c},remountDeps:[i,l.cardholderName,u],iframePassthrough:{style:p,...m},updateDeps:[a,l,u,f,o,s,c]}),(0,n.jsx)(`div`,{ref:h})}function h({ref:r,renderToken:i,appearance:a,onValidityChange:o,onEscapeKeyPressed:s,billingAddressRequirement:c=`country`,defaultValues:l,requireAchVerification:u=!1,intent:f=`payment`,style:p,...m}){let h=(0,t.useRef)(null);return d({containerRef:h,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,defaultValues:l,requireAchVerification:u,intent:f,onValidityChange:o,onEscapeKeyPressed:s},remountDeps:[i,c,f],iframePassthrough:{style:p,...m},updateDeps:[a,c,l,u,f,o,s]}),(0,n.jsx)(`div`,{ref:h})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}function _({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let f=(0,t.useRef)(null),m=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return d({containerRef:f,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onConfirm:u},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,u]}),(0,n.jsx)(p,{height:s,borderRadius:m,containerRef:f})}exports.AmosApplePayButton=_,exports.AmosBankAccountPaymentMethodForm=h,exports.AmosCreditCardPaymentMethodForm=m,exports.AmosGooglePayButton=g,exports.confirmPayment=a,exports.confirmSetup=o,exports.focusField=c,exports.resetForm=s,exports.validateForm=i,Object.keys(e).forEach(function(t){t!=="default"&&!Object.prototype.hasOwnProperty.call(exports,t)&&Object.defineProperty(exports,t,{enumerable:!0,get:function(){return e[t]}})});

package/dist/index.mjs

@@ -92,73 +92,77 @@ function E({ height: e, borderRadius: t, containerRef: r }) {
 		})]
 	});
 }
-function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, additionalFields: a = { cardholderName: !1 }, billingAddressRequirement: s = "country", defaultValues: c, style: l, ...u }) {
-	let d = p(null);
+function D({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onCardBrandChanged: i, onEscapeKeyPressed: a, additionalFields: s = { cardholderName: !1 }, billingAddressRequirement: c = "country", defaultValues: l, style: u, ...d }) {
+	let f = p(null);
 	return w({
-		containerRef: d,
+		containerRef: f,
 		iframeRef: e,
 		mount: o,
 		options: {
 			renderToken: t,
 			appearance: n,
-			additionalFields: a,
-			billingAddressRequirement: s,
-			defaultValues: c,
+			additionalFields: s,
+			billingAddressRequirement: c,
+			defaultValues: l,
 			onValidityChange: r,
-			onCardBrandChanged: i
+			onCardBrandChanged: i,
+			onEscapeKeyPressed: a
 		},
 		remountDeps: [
 			t,
-			a.cardholderName,
-			s
+			s.cardholderName,
+			c
 		],
 		iframePassthrough: {
-			style: l,
-			...u
+			style: u,
+			...d
 		},
 		updateDeps: [
 			n,
-			a,
 			s,
 			c,
+			l,
 			r,
-			i
+			i,
+			a
 		]
-	}), /* @__PURE__ */ m("div", { ref: d });
+	}), /* @__PURE__ */ m("div", { ref: f });
 }
-function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, billingAddressRequirement: i = "country", defaultValues: o, requireAchVerification: s = !1, intent: c = "payment", style: l, ...u }) {
-	let d = p(null);
+function O({ ref: e, renderToken: t, appearance: n, onValidityChange: r, onEscapeKeyPressed: i, billingAddressRequirement: o = "country", defaultValues: s, requireAchVerification: c = !1, intent: l = "payment", style: u, ...d }) {
+	let f = p(null);
 	return w({
-		containerRef: d,
+		containerRef: f,
 		iframeRef: e,
 		mount: a,
 		options: {
 			renderToken: t,
 			appearance: n,
-			billingAddressRequirement: i,
-			defaultValues: o,
-			requireAchVerification: s,
-			intent: c,
-			onValidityChange: r
+			billingAddressRequirement: o,
+			defaultValues: s,
+			requireAchVerification: c,
+			intent: l,
+			onValidityChange: r,
+			onEscapeKeyPressed: i
 		},
 		remountDeps: [
 			t,
-			i,
-			c
+			o,
+			l
 		],
 		iframePassthrough: {
-			style: l,
-			...u
+			style: u,
+			...d
 		},
 		updateDeps: [
 			n,
-			i,
 			o,
 			s,
 			c,
-			r
+			l,
+			r,
+			i
 		]
-	}), /* @__PURE__ */ m("div", { ref: d });
+	}), /* @__PURE__ */ m("div", { ref: f });
 }
 function k({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: o, onConfirm: c }) {
 	let u = p(null), d = l({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.11.6",
+  "version": "0.11.8",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -38,9 +38,9 @@
   "description": "React SDK for embedding Amos payment methods via iframes. Wraps @amos.com/amos-js.",
   "devDependencies": {
     "@amos.com/node": "0.1.57",
-    "@biomejs/biome": "2.5.10",
+    "@biomejs/biome": "2.5.11",
     "@changesets/cli": "2.31.1",
-    "@types/node": "26.3.0",
+    "@types/node": "26.4.0",
     "@types/react": "19.2.18",
     "@typescript/typescript6": "6.0.2",
     "typescript": "7.0.2",
@@ -48,7 +48,7 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.11.8",
+    "@amos.com/amos-js": "0.11.10",
     "@types/googlepay": "0.7.12"
   },
   "peerDependencies": {

package/src/index.tsx

@@ -304,6 +304,14 @@ type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
       | "jcb"
       | null;
   }) => void;
+  /**
+   * Called when the customer presses Escape in the iframe. PCI-safe —
+   * no field values. Use this to close a host modal that contains the
+   * iframe. Not fired while an iframe dropdown or address suggestion
+   * list is open, or while Plaid Embedded Institution Search is
+   * showing.
+   */
+  onEscapeKeyPressed?: () => void;
   additionalFields?: CreditCardAdditionalFields;
   billingAddressRequirement?: BillingAddressRequirement;
   /**
@@ -320,6 +328,7 @@ export function AmosCreditCardPaymentMethodForm({
   appearance,
   onValidityChange,
   onCardBrandChanged,
+  onEscapeKeyPressed,
   additionalFields = { cardholderName: false },
   billingAddressRequirement = "country",
   defaultValues,
@@ -340,6 +349,7 @@ export function AmosCreditCardPaymentMethodForm({
       defaultValues,
       onValidityChange,
       onCardBrandChanged,
+      onEscapeKeyPressed,
     },
     remountDeps: [
       renderToken,
@@ -354,6 +364,7 @@ export function AmosCreditCardPaymentMethodForm({
       defaultValues,
       onValidityChange,
       onCardBrandChanged,
+      onEscapeKeyPressed,
     ],
   });
 
@@ -369,6 +380,14 @@ type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
    * has returned credentials. Does not include PCI data.
    */
   onValidityChange?: (event: { isValid: boolean }) => void;
+  /**
+   * Called when the customer presses Escape in the iframe. PCI-safe —
+   * no field values. Use this to close a host modal that contains the
+   * iframe. Not fired while an iframe dropdown or address suggestion
+   * list is open, or while Plaid Embedded Institution Search is
+   * showing.
+   */
+  onEscapeKeyPressed?: () => void;
   billingAddressRequirement?: BillingAddressRequirement;
   /**
    * Seed account holder name and billing address. Provided keys
@@ -400,6 +419,7 @@ export function AmosBankAccountPaymentMethodForm({
   renderToken,
   appearance,
   onValidityChange,
+  onEscapeKeyPressed,
   billingAddressRequirement = "country",
   defaultValues,
   requireAchVerification = false,
@@ -421,6 +441,7 @@ export function AmosBankAccountPaymentMethodForm({
       requireAchVerification,
       intent,
       onValidityChange,
+      onEscapeKeyPressed,
     },
     remountDeps: [renderToken, billingAddressRequirement, intent],
     iframePassthrough: { style, ...rest },
@@ -431,6 +452,7 @@ export function AmosBankAccountPaymentMethodForm({
       requireAchVerification,
       intent,
       onValidityChange,
+      onEscapeKeyPressed,
     ],
   });