@amos.com/amos-js 0.7.2 → 0.9.0

package/README.md

@@ -51,11 +51,14 @@ const form = mountAmosCreditCardPaymentMethodForm(
         "--radius": "0.5rem",
       },
     },
-    onPaymentIntentConfirmationSucceeded: (paymentIntent) => {
-      console.log("Payment succeeded:", paymentIntent.id);
-    },
-    onConfirmationFailed: (errorMessage) => {
-      console.error("Payment failed:", errorMessage);
+    onResult: (result) => {
+      // Unlock UI. Verify settlement on your backend via webhooks.
+      if (result.status === "succeeded") {
+        console.log("Confirm returned:", result);
+      } else if (result.status === "failed") {
+        console.error("Confirm failed:", result.errorMessage);
+      }
+      // status === "incomplete": field errors shown in the iframe; customer can retry
     },
   },
 );
@@ -87,12 +90,12 @@ form.destroy();
 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** by calling `mountAmosCreditCardPaymentMethodForm(container, options)` (or `mountAmosBankAccountPaymentMethodForm(...)`) along with the required option (`onConfirmationFailed`) and optional callbacks (`onPaymentIntentConfirmationSucceeded`, `onSetupIntentConfirmationSucceeded`). The iframe height is auto-managed by the SDK.
+2. **Render your checkout UI** by calling `mountAmosCreditCardPaymentMethodForm(container, options)` (or `mountAmosBankAccountPaymentMethodForm(...)`) along with the required `onResult` callback. The iframe height is auto-managed by the SDK.
 3. **User clicks "Pay now" button**: call `validateForm({ iframe: form.iframe })`, 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**: call `confirmPaymentIntent({ iframe: form.iframe, token })` in the browser to continue the payment flow.
-7. **Handle UX**: show the user a "processing" state when the "Pay now" button is clicked, and show a success or error message via `onPaymentIntentConfirmationSucceeded` and `onConfirmationFailed`.
+7. **Handle UX**: show the user a "processing" state when the "Pay now" button is clicked, and handle `onResult`. Do not treat `onResult` as settlement proof — verify payment success on your backend via webhooks. Recoverable field errors are shown in the iframe (`status: "incomplete"`).
 
 ### Google Pay
 
@@ -128,11 +131,12 @@ const button = mountAmosGooglePayButton(
       const { token } = await response.json();
       return token;
     },
-    onPaymentIntentConfirmationSucceeded: (paymentIntent) => {
-      console.log("Google Pay succeeded:", paymentIntent.id);
-    },
-    onConfirmationFailed: (errorMessage) => {
-      console.error("Google Pay failed:", errorMessage);
+    onResult: (result) => {
+      if (result.status === "succeeded") {
+        console.log("Google Pay confirm returned:", result);
+      } else if (result.status === "failed") {
+        console.error("Google Pay failed:", result.errorMessage);
+      }
     },
   },
 );
@@ -147,7 +151,7 @@ Setup intents are used to save payment methods for future use (e.g. recurring pa
 
 - On the server, call `POST /setup_intents` instead of `POST /payment_intents`.
 - On the client, call `confirmSetupIntent({ iframe, token })` instead of `confirmPaymentIntent({ iframe, token })`.
-- Use `onSetupIntentConfirmationSucceeded` instead of `onPaymentIntentConfirmationSucceeded`.
+- The same `onResult` callback is used; succeeded setup intents arrive as `{ status: "succeeded", intent: "setup", setupIntent }`.
 
 The same `mountAmosCreditCardPaymentMethodForm` / `mountAmosBankAccountPaymentMethodForm` controllers support both payment intents and setup intents — they are differentiated by which confirmation function you call.
 
@@ -226,15 +230,15 @@ Mount the secure credit-card payment method form into a container element (an `H
 **Required `options`:**
 
 - `renderToken` (`string`)
-- `onConfirmationFailed` (`(errorMessage: string) => void`)
+- `onResult` (`(result: ConfirmationResult) => void`) — required. Called when the interactive confirmation attempt finishes (`succeeded`, `failed`, or `incomplete`). Not settlement proof; verify via webhooks.
 
 **Optional `options`:**
 
 - `appearance` (`{ themeVariables?: Partial<Record<ThemeVariable, string>>; labels?: "above" | "floating" | "placeholder" }`)
 - `additionalFields` (`{ cardholderName: boolean }`, defaults to `{ cardholderName: false }`)
 - `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.
-- `onPaymentIntentConfirmationSucceeded` (`(paymentIntent: components["schemas"]["PaymentIntent"]) => void`)
-- `onSetupIntentConfirmationSucceeded` (`(setupIntent: components["schemas"]["SetupIntent"]) => void`)
+
+
 - `onHeightChange`, `onAppearanceReady` (advanced — override the default iframe styling logic)
 
 **Returns** `AmosPaymentMethodFormMountController`:
@@ -257,8 +261,8 @@ Mount the secure Google Pay button (express checkout) into a container element.
 - `amount` (`string`)
 - `merchantName` (`string`)
 - `onInitiatePaymentIntentRequest` (`({ paymentIntentCreateAttributes, customerCreateAttributes }) => Promise<components["schemas"]["EmbedToken"]["token"]>`)
-- `onPaymentIntentConfirmationSucceeded` (`(paymentIntent: components["schemas"]["PaymentIntent"]) => void`)
-- `onConfirmationFailed` (`(errorMessage: string) => void`)
+
+- `onResult` (`(result: ConfirmationResult) => void`) — required. Called when the interactive confirmation attempt finishes (`succeeded`, `failed`, or `incomplete`). Not settlement proof; verify via webhooks.
 
 **Optional `options`:** `appearance`, `onHeightChange`, `onAppearanceReady`.
 
@@ -307,7 +311,7 @@ Advanced helpers exposed for integrators that need to construct or inspect the m
 ## Notes and potential gotchas
 
 - **`iframe` argument**: every messaging helper (`validateForm`, `confirmPaymentIntent`, `confirmSetupIntent`) accepts the `iframe` element directly. With the mount helpers, use `controller.iframe`.
-- **Same components for payment vs setup intents**: `mountAmosCreditCardPaymentMethodForm` and `mountAmosBankAccountPaymentMethodForm` support both payment intents and setup intents. The flow differs only by which server call you make and which confirmation function you use. You may optionally provide `onPaymentIntentConfirmationSucceeded` and/or `onSetupIntentConfirmationSucceeded`; the appropriate one is invoked based on the flow.
+- **Same components for payment vs setup intents**: `mountAmosCreditCardPaymentMethodForm` and `mountAmosBankAccountPaymentMethodForm` support both payment intents and setup intents. The flow differs only by which server call you make and which confirmation function you use. Handle both outcomes via `onResult`.
 - **Amount format**: for `mountAmosGooglePayButton`, `amount` is a string (e.g. `"5000"` for $50.00). For `components["schemas"]["CreatePaymentIntentInput"]` on the server, `amount` is a number in cents (e.g. `5000`).
 - **Browser-only**: the mount and messaging helpers require `window` and the DOM. They are not safe to call during server-side rendering — call them from client-side code only (for example, inside a `useEffect`-like hook in your framework of choice).
 

package/dist/apple-pay.d.ts

@@ -1,5 +1,5 @@
 import { components } from '@amos.com/node';
-import { Appearance } from './types';
+import { Appearance, ConfirmationResult } from './types';
 /**
  * Build the iframe `src` URL for the embedded Apple Pay button.
  */
@@ -41,13 +41,10 @@ export type ApplePayButtonListenerOptions = {
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
     }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
     /**
-     * Called when payment intent confirmation succeeds.
+     * Called when the interactive confirmation flow finishes (success or
+     * terminal failure). Not settlement proof — verify via webhooks.
      */
-    onPaymentIntentConfirmationSucceeded: (paymentIntent: components["schemas"]["PaymentIntent"]) => void;
-    /**
-     * Called when payment intent confirmation fails.
-     */
-    onConfirmationFailed: (errorMessage: string) => void;
+    onResult: (result: ConfirmationResult) => void;
 };
 /**
  * Controller returned by {@link attachApplePayButtonListeners} and

package/dist/google-pay.d.ts

@@ -1,5 +1,5 @@
 import { components } from '@amos.com/node';
-import { Appearance } from './types';
+import { Appearance, ConfirmationResult } from './types';
 /**
  * Build the iframe `src` URL for the embedded Google Pay button.
  */
@@ -41,13 +41,10 @@ export type GooglePayButtonListenerOptions = {
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
     }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
     /**
-     * Called when payment intent confirmation succeeds.
+     * Called when the interactive confirmation flow finishes (success or
+     * terminal failure). Not settlement proof — verify via webhooks.
      */
-    onPaymentIntentConfirmationSucceeded: (paymentIntent: components["schemas"]["PaymentIntent"]) => void;
-    /**
-     * Called when payment intent confirmation fails.
-     */
-    onConfirmationFailed: (errorMessage: string) => void;
+    onResult: (result: ConfirmationResult) => void;
 };
 /**
  * Controller returned by {@link attachGooglePayButtonListeners} and

package/dist/index.d.ts

@@ -4,10 +4,10 @@ export { attachApplePayButtonListeners, getApplePayButtonInitialHeight, getApple
 export type { FormattedGooglePayPaymentData, GooglePayButtonController, GooglePayButtonListenerOptions, } from './google-pay';
 export { attachGooglePayButtonListeners, formatGooglePayPaymentData, getGooglePayButtonInitialHeight, getGooglePayButtonSrc, } from './google-pay';
 export { decodeJwt, getEmbedOrigin } from './jwt';
-export { confirmPaymentIntent, confirmSetupIntent, sendConfirmationFailed, sendParentReadyMessage, updateAmount, updateAppearance, updateMerchantName, validateForm, } from './messaging';
+export { confirmPaymentIntent, confirmSetupIntent, sendConfirmationResult, sendParentReadyMessage, updateAmount, updateAppearance, updateMerchantName, validateForm, } from './messaging';
 export type { AmosApplePayButtonMountController, AmosApplePayButtonOptions, AmosBankAccountPaymentMethodFormOptions, AmosCreditCardPaymentMethodFormOptions, AmosGooglePayButtonMountController, AmosGooglePayButtonOptions, AmosPaymentMethodFormMountController, } from './mount';
 export { mountAmosApplePayButton, mountAmosBankAccountPaymentMethodForm, mountAmosCreditCardPaymentMethodForm, mountAmosGooglePayButton, } from './mount';
 export type { BillingAddressRequirement, CreditCardAdditionalFields, PaymentMethodFormController, PaymentMethodFormListenerOptions, } from './payment-method-form';
 export { attachPaymentMethodFormListeners, getBankAccountFormInitialHeight, getBankAccountFormSrc, getCreditCardFormInitialHeight, getCreditCardFormSrc, } from './payment-method-form';
-export type { Appearance, AppearanceLabels, Message, ThemeVariable, } from './types';
+export type { Appearance, AppearanceLabels, ConfirmationResult, Message, ThemeVariable, } from './types';
 export { createMessage } from './types';

package/dist/index.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`data-amos-apple-pay-waiting`;function t({onCancel:t}){let n=document.querySelector(`[${e}]`);if(n)return n;let r=document.createElement(`div`);r.setAttribute(e,`true`),r.setAttribute(`role`,`dialog`),r.setAttribute(`aria-modal`,`true`),r.setAttribute(`aria-labelledby`,`amos-apple-pay-waiting-title`),Object.assign(r.style,{position:`fixed`,inset:`0`,zIndex:`2147483646`,display:`flex`,alignItems:`center`,justifyContent:`center`,padding:`24px`,boxSizing:`border-box`,background:`rgba(0, 0, 0, 0.55)`,fontFamily:`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`});let i=document.createElement(`div`);Object.assign(i.style,{width:`100%`,maxWidth:`360px`,borderRadius:`12px`,background:`#fff`,padding:`28px 24px 20px`,boxSizing:`border-box`,textAlign:`center`,boxShadow:`0 12px 40px rgba(0, 0, 0, 0.25)`});let a=document.createElement(`div`);a.setAttribute(`aria-hidden`,`true`),Object.assign(a.style,{display:`inline-flex`,alignItems:`center`,justifyContent:`center`,gap:`6px`,marginBottom:`16px`,fontSize:`28px`,fontWeight:`600`,letterSpacing:`-0.02em`,color:`#000`,lineHeight:`1`}),a.innerHTML=`<svg width="22" height="26" viewBox="0 0 14 17" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path d="M13.072 5.846c-.1.08-1.873 1.09-1.873 3.34 0 2.61 2.29 3.53 2.36 3.55-.04.1-.368 1.27-.766 2.52-.35 1.09-.72 2.18-1.28 2.18-.55 0-.73-.36-1.43-.36-.71 0-.93.37-1.48.37-.55 0-.93-.99-1.35-2.01-.5-1.2-.88-2.43-.88-3.85 0-2.26 1.47-3.46 2.91-3.46.57 0 1.11.38 1.49.38.37 0 .98-.45 1.7-.45.28 0 1.27.03 1.97 1.01ZM9.52 3.37c.3-.36.52-.86.52-1.36 0-.07 0-.14-.01-.2-.5.02-1.1.33-1.46.75-.28.32-.55.84-.55 1.35 0 .07.01.15.02.17.04.01.1.02.16.02.45 0 1.02-.3 1.32-.73Z"/></svg><span>Pay</span>`;let o=document.createElement(`p`);o.id=`amos-apple-pay-waiting-title`,Object.assign(o.style,{margin:`0 0 20px`,fontSize:`15px`,lineHeight:`1.45`,color:`#1a1a1a`}),o.textContent=`Complete your payment in the open Apple Pay window, or close Apple Pay to continue paying another way.`;let s=document.createElement(`button`);return s.type=`button`,s.textContent=`Cancel payment`,Object.assign(s.style,{display:`block`,width:`100%`,border:`none`,borderRadius:`8px`,padding:`12px 16px`,background:`#2c2c2e`,color:`#fff`,fontSize:`15px`,fontWeight:`500`,cursor:`pointer`}),s.addEventListener(`click`,t),i.append(a,o,s),r.append(i),document.body.append(r),r}function n(){document.querySelector(`[${e}]`)?.remove()}function r(e){let[t=``,n=``,r=``]=e?.split(`.`)??[],i=typeof atob==`function`?atob:e=>Buffer.from(e,`base64`).toString(`utf8`);return{header:JSON.parse(i(t)),payload:JSON.parse(i(n)),signature:r}}function i(e){let{env:t=`sandbox`}=r(e).payload;switch(t){case`production`:return`https://embed.amos.com`;case`sandbox`:return`https://embed-sandbox.amos.com`;default:return`https://embed-sandbox.amos.com`}}function a(e){return e}function o(e){e?.contentWindow?.postMessage(a({type:`PARENT_ACKNOWLEDGED_IFRAME_READY`}),`*`)}function s({iframe:e,appearance:t={}}){e?.contentWindow?.postMessage(a({type:`UPDATE_APPEARANCE`,appearance:t}),`*`)}function c({iframe:e,amount:t}){e?.contentWindow?.postMessage(a({type:`UPDATE_AMOUNT`,amount:t}),`*`)}function l({iframe:e,merchantName:t}){e?.contentWindow?.postMessage(a({type:`UPDATE_MERCHANT_NAME`,merchantName:t}),`*`)}function u({iframe:e}){let t=crypto.randomUUID();return new Promise(n=>{e?.contentWindow?.postMessage(a({type:`VALIDATE_FORM`,requestId:t}),`*`);let r=setTimeout(()=>{window.removeEventListener(`message`,i),n(!1)},5e3);function i(e){e.data.type===`VALIDATE_FORM`&&e.data.requestId===t&&(window.removeEventListener(`message`,i),clearTimeout(r),n(e.data.isValid??!1))}window.addEventListener(`message`,i)})}function d({iframe:e,token:t}){let{payment_intent_id:n}=r(t).payload;e?.contentWindow?.postMessage(a({type:`CONFIRM_PAYMENT_INTENT`,token:t,id:n??void 0}),`*`)}function f({iframe:e,token:t}){let{setup_intent_id:n}=r(t).payload;e?.contentWindow?.postMessage(a({type:`CONFIRM_SETUP_INTENT`,token:t,id:n??void 0}),`*`)}function p({iframe:e,errorMessage:t}){e?.contentWindow?.postMessage(a({type:`CONFIRMATION_FAILED`,errorMessage:t}),`*`)}function m(e){return`${i(e)}/iframe/apple-pay?token=${e}`}function h(){return`40px`}function g(e){e.contentWindow?.postMessage(a({type:`APPLE_PAY_CANCEL`}),`*`)}function _(e,r){let i={...r};function a(){c({iframe:e,amount:i.amount})}function u(){l({iframe:e,merchantName:i.merchantName})}function f(r){if(r.source===e.contentWindow)switch(r.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:i.appearance}),a(),u();break;case`UPDATE_HEIGHT`:i.onHeightChange?.(r.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:r.data.appearance});break;case`UPDATED_APPEARANCE`:i.onAppearanceReady?.();break;case`APPLE_PAY_WINDOW_OPEN`:t({onCancel:()=>{g(e),n()}});break;case`APPLE_PAY_WINDOW_CLOSE`:n();break;case`CREATE_PAYMENT_INTENT`:i.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:r.data.paymentIntentCreateAttributes,customerCreateAttributes:r.data.customerCreateAttributes}).then(t=>{d({iframe:e,token:t})}).catch(t=>{p({iframe:e,errorMessage:t instanceof Error?t.message:`Unknown error`})});break;case`PAYMENT_INTENT_CONFIRMATION_SUCCEEDED`:n(),i.onPaymentIntentConfirmationSucceeded(r.data.paymentIntent);break;case`CONFIRMATION_FAILED`:n(),i.onConfirmationFailed(r.data.errorMessage);break}}return window.addEventListener(`message`,f),{update(t){let n=`appearance`in t,r=`amount`in t,o=`merchantName`in t;i={...i,...t},n&&s({iframe:e,appearance:i.appearance}),r&&a(),o&&u()},destroy(){window.removeEventListener(`message`,f),n()}}}function v(e){return`${i(e)}/iframe/google-pay?token=${e}`}function y(){return`40px`}function b(e,t){let n={...t};function r(){c({iframe:e,amount:n.amount})}function i(){l({iframe:e,merchantName:n.merchantName})}function a(t){switch(t.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:n.appearance}),r(),i();break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CREATE_PAYMENT_INTENT`:n.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:t.data.paymentIntentCreateAttributes,customerCreateAttributes:t.data.customerCreateAttributes}).then(t=>{d({iframe:e,token:t})}).catch(t=>{p({iframe:e,errorMessage:t instanceof Error?t.message:`Unknown error`})});break;case`PAYMENT_INTENT_CONFIRMATION_SUCCEEDED`:n.onPaymentIntentConfirmationSucceeded(t.data.paymentIntent);break;case`CONFIRMATION_FAILED`:n.onConfirmationFailed(t.data.errorMessage);break}}return window.addEventListener(`message`,a),{update(t){let a=`appearance`in t,o=`amount`in t,c=`merchantName`in t;n={...n,...t},a&&s({iframe:e,appearance:n.appearance}),o&&r(),c&&i()},destroy(){window.removeEventListener(`message`,a)}}}function x({paymentData:e}){return{paymentMethod:{type:`googlepay`,billing_address_attributes:{name:e.shippingAddress?.name,address_line1:e.shippingAddress?.address1,address_line2:e.shippingAddress?.address2,city:e.shippingAddress?.locality,state:e.shippingAddress?.administrativeArea,postal_code:e.shippingAddress?.postalCode,country:e.shippingAddress?.countryCode,email:e.email,phone:e.shippingAddress?.phoneNumber},card_profile_attributes:{wallet_provider:`googlepay`,wallet_payload:e.paymentMethodData.tokenizationData.token,wallet_last4:e.paymentMethodData.info?.cardDetails,wallet_brand:(()=>{switch(e.paymentMethodData.info?.cardNetwork){case`AMEX`:return`american_express`;case`VISA`:return`visa`;case`MASTERCARD`:return`master`;case`DISCOVER`:return`discover`;default:return}})()}}}}var S={country:212,full:452},C=80,w={country:400,full:640};function T(e,t={cardholderName:!1},n=`country`){let r=Object.entries(t).filter(([,e])=>e).map(([e])=>e).join(`,`),a=new URLSearchParams({token:e,additionalFields:r,billingAddressRequirement:n});return`${i(e)}/iframe/card?${a}`}function E(e,t=`country`){let n=new URLSearchParams({token:e,billingAddressRequirement:t});return`${i(e)}/iframe/bank?${n}`}function D(e={cardholderName:!1},t=`country`){return`${(S[t]??S.country)+(e.cardholderName?C:0)}px`}function O(e=`country`){return`${w[e]??w.country}px`}function k(e,t){let n={...t};function r(t){switch(t.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:n.appearance});break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`PAYMENT_INTENT_CONFIRMATION_SUCCEEDED`:n.onPaymentIntentConfirmationSucceeded?.(t.data.paymentIntent);break;case`SETUP_INTENT_CONFIRMATION_SUCCEEDED`:n.onSetupIntentConfirmationSucceeded?.(t.data.setupIntent);break;case`CONFIRMATION_FAILED`:n.onConfirmationFailed(t.data.errorMessage);break}}return window.addEventListener(`message`,r),{update(t){let r=`appearance`in t;n={...n,...t},r&&s({iframe:e,appearance:n.appearance})},destroy(){window.removeEventListener(`message`,r)}}}function A(e){if(typeof e==`string`){let t=document.querySelector(e);if(!(t instanceof HTMLElement))throw Error(`[amos-js] Container "${e}" did not match any HTMLElement.`);return t}return e}var j={width:`calc(100% + 8px)`,transition:`opacity 150ms ease-in, height 200ms ease-in-out`,margin:`0 -4px`,opacity:`0`,border:`0`};function M({src:e,title:t,name:n,height:r,allow:i}){let a=document.createElement(`iframe`);return a.src=e,a.title=t,a.name=n,a.setAttribute(`role`,`presentation`),a.scrolling=`no`,i&&(a.allow=i),Object.assign(a.style,j,{height:r}),a}function N(e,t){let n=A(e),{renderToken:r,additionalFields:i={cardholderName:!1},billingAddressRequirement:a=`country`,...o}=t,s=M({src:T(r,i,a),title:`Secure credit card payment method form powered by Amos`,name:`amos-credit-card-payment-method-form`,height:D(i,a)});n.appendChild(s);let c=k(s,{...o,onHeightChange:e=>{s.style.height=e,o.onHeightChange?.(e)},onAppearanceReady:()=>{s.style.opacity=`1`,o.onAppearanceReady?.()}});return{iframe:s,update:c.update,destroy(){c.destroy(),s.remove()}}}function P(e,t){let n=A(e),{renderToken:r,billingAddressRequirement:i=`country`,...a}=t,o=M({src:E(r,i),title:`Secure bank account payment method form powered by Amos`,name:`amos-bank-account-payment-method-form`,height:O(i)});n.appendChild(o);let s=k(o,{...a,onHeightChange:e=>{o.style.height=e,a.onHeightChange?.(e)},onAppearanceReady:()=>{o.style.opacity=`1`,a.onAppearanceReady?.()}});return{iframe:o,update:s.update,destroy(){s.destroy(),o.remove()}}}function F(e,t){let n=A(e),{renderToken:r,...i}=t,a=M({src:v(r),title:`Secure Google Pay button powered by Amos`,name:`amos-google-pay-button`,height:y(),allow:`payment`});n.appendChild(a);let o=b(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}function I(e,t){let n=A(e),{renderToken:r,...i}=t,a=M({src:m(r),title:`Secure Apple Pay button powered by Amos`,name:`amos-apple-pay-button`,height:h(),allow:`payment`});n.appendChild(a);let o=_(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}exports.attachApplePayButtonListeners=_,exports.attachGooglePayButtonListeners=b,exports.attachPaymentMethodFormListeners=k,exports.confirmPaymentIntent=d,exports.confirmSetupIntent=f,exports.createMessage=a,exports.decodeJwt=r,exports.formatGooglePayPaymentData=x,exports.getApplePayButtonInitialHeight=h,exports.getApplePayButtonSrc=m,exports.getBankAccountFormInitialHeight=O,exports.getBankAccountFormSrc=E,exports.getCreditCardFormInitialHeight=D,exports.getCreditCardFormSrc=T,exports.getEmbedOrigin=i,exports.getGooglePayButtonInitialHeight=y,exports.getGooglePayButtonSrc=v,exports.mountAmosApplePayButton=I,exports.mountAmosBankAccountPaymentMethodForm=P,exports.mountAmosCreditCardPaymentMethodForm=N,exports.mountAmosGooglePayButton=F,exports.sendConfirmationFailed=p,exports.sendParentReadyMessage=o,exports.updateAmount=c,exports.updateAppearance=s,exports.updateMerchantName=l,exports.validateForm=u;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`data-amos-apple-pay-waiting`;function t({onCancel:t}){let n=document.querySelector(`[${e}]`);if(n)return n;let r=document.createElement(`div`);r.setAttribute(e,`true`),r.setAttribute(`role`,`dialog`),r.setAttribute(`aria-modal`,`true`),r.setAttribute(`aria-labelledby`,`amos-apple-pay-waiting-title`),Object.assign(r.style,{position:`fixed`,inset:`0`,zIndex:`2147483646`,display:`flex`,alignItems:`center`,justifyContent:`center`,padding:`24px`,boxSizing:`border-box`,background:`rgba(0, 0, 0, 0.55)`,fontFamily:`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`});let i=document.createElement(`div`);Object.assign(i.style,{width:`100%`,maxWidth:`360px`,borderRadius:`12px`,background:`#fff`,padding:`28px 24px 20px`,boxSizing:`border-box`,textAlign:`center`,boxShadow:`0 12px 40px rgba(0, 0, 0, 0.25)`});let a=document.createElement(`div`);a.setAttribute(`aria-hidden`,`true`),Object.assign(a.style,{display:`inline-flex`,alignItems:`center`,justifyContent:`center`,gap:`6px`,marginBottom:`16px`,fontSize:`28px`,fontWeight:`600`,letterSpacing:`-0.02em`,color:`#000`,lineHeight:`1`}),a.innerHTML=`<svg width="22" height="26" viewBox="0 0 14 17" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path d="M13.072 5.846c-.1.08-1.873 1.09-1.873 3.34 0 2.61 2.29 3.53 2.36 3.55-.04.1-.368 1.27-.766 2.52-.35 1.09-.72 2.18-1.28 2.18-.55 0-.73-.36-1.43-.36-.71 0-.93.37-1.48.37-.55 0-.93-.99-1.35-2.01-.5-1.2-.88-2.43-.88-3.85 0-2.26 1.47-3.46 2.91-3.46.57 0 1.11.38 1.49.38.37 0 .98-.45 1.7-.45.28 0 1.27.03 1.97 1.01ZM9.52 3.37c.3-.36.52-.86.52-1.36 0-.07 0-.14-.01-.2-.5.02-1.1.33-1.46.75-.28.32-.55.84-.55 1.35 0 .07.01.15.02.17.04.01.1.02.16.02.45 0 1.02-.3 1.32-.73Z"/></svg><span>Pay</span>`;let o=document.createElement(`p`);o.id=`amos-apple-pay-waiting-title`,Object.assign(o.style,{margin:`0 0 20px`,fontSize:`15px`,lineHeight:`1.45`,color:`#1a1a1a`}),o.textContent=`Complete your payment in the open Apple Pay window, or close Apple Pay to continue paying another way.`;let s=document.createElement(`button`);return s.type=`button`,s.textContent=`Cancel payment`,Object.assign(s.style,{display:`block`,width:`100%`,border:`none`,borderRadius:`8px`,padding:`12px 16px`,background:`#2c2c2e`,color:`#fff`,fontSize:`15px`,fontWeight:`500`,cursor:`pointer`}),s.addEventListener(`click`,t),i.append(a,o,s),r.append(i),document.body.append(r),r}function n(){document.querySelector(`[${e}]`)?.remove()}function r(e){let[t=``,n=``,r=``]=e?.split(`.`)??[],i=typeof atob==`function`?atob:e=>Buffer.from(e,`base64`).toString(`utf8`);return{header:JSON.parse(i(t)),payload:JSON.parse(i(n)),signature:r}}function i(e){let{env:t=`sandbox`}=r(e).payload;switch(t){case`production`:return`https://embed.amos.com`;case`sandbox`:return`https://embed-sandbox.amos.com`;default:return`https://embed-sandbox.amos.com`}}function a(e){return e}function o(e){e?.contentWindow?.postMessage(a({type:`PARENT_ACKNOWLEDGED_IFRAME_READY`}),`*`)}function s({iframe:e,appearance:t={}}){e?.contentWindow?.postMessage(a({type:`UPDATE_APPEARANCE`,appearance:t}),`*`)}function c({iframe:e,amount:t}){e?.contentWindow?.postMessage(a({type:`UPDATE_AMOUNT`,amount:t}),`*`)}function l({iframe:e,merchantName:t}){e?.contentWindow?.postMessage(a({type:`UPDATE_MERCHANT_NAME`,merchantName:t}),`*`)}function u({iframe:e}){let t=crypto.randomUUID();return new Promise(n=>{e?.contentWindow?.postMessage(a({type:`VALIDATE_FORM`,requestId:t}),`*`);let r=setTimeout(()=>{window.removeEventListener(`message`,i),n(!1)},5e3);function i(e){e.data.type===`VALIDATE_FORM`&&e.data.requestId===t&&(window.removeEventListener(`message`,i),clearTimeout(r),n(e.data.isValid??!1))}window.addEventListener(`message`,i)})}function d({iframe:e,token:t}){let{payment_intent_id:n}=r(t).payload;e?.contentWindow?.postMessage(a({type:`CONFIRM_PAYMENT_INTENT`,token:t,id:n??void 0}),`*`)}function f({iframe:e,token:t}){let{setup_intent_id:n}=r(t).payload;e?.contentWindow?.postMessage(a({type:`CONFIRM_SETUP_INTENT`,token:t,id:n??void 0}),`*`)}function p({iframe:e,result:t}){e?.contentWindow?.postMessage(a({type:`CONFIRMATION_RESULT`,result:t}),`*`)}function m(e){return`${i(e)}/iframe/apple-pay?token=${e}`}function h(){return`40px`}function g(e){e.contentWindow?.postMessage(a({type:`APPLE_PAY_CANCEL`}),`*`)}function _(e,r){let i={...r};function a(){c({iframe:e,amount:i.amount})}function u(){l({iframe:e,merchantName:i.merchantName})}function f(r){if(r.source===e.contentWindow)switch(r.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:i.appearance}),a(),u();break;case`UPDATE_HEIGHT`:i.onHeightChange?.(r.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:r.data.appearance});break;case`UPDATED_APPEARANCE`:i.onAppearanceReady?.();break;case`APPLE_PAY_WINDOW_OPEN`:t({onCancel:()=>{g(e),n()}});break;case`APPLE_PAY_WINDOW_CLOSE`:n();break;case`CREATE_PAYMENT_INTENT`:i.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:r.data.paymentIntentCreateAttributes,customerCreateAttributes:r.data.customerCreateAttributes}).then(t=>{d({iframe:e,token:t})}).catch(e=>{n(),i.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n(),i.onResult(r.data.result);break}}return window.addEventListener(`message`,f),{update(t){let n=`appearance`in t,r=`amount`in t,o=`merchantName`in t;i={...i,...t},n&&s({iframe:e,appearance:i.appearance}),r&&a(),o&&u()},destroy(){window.removeEventListener(`message`,f),n()}}}function v(e){return`${i(e)}/iframe/google-pay?token=${e}`}function y(){return`40px`}function b(e,t){let n={...t};function r(){c({iframe:e,amount:n.amount})}function i(){l({iframe:e,merchantName:n.merchantName})}function a(t){switch(t.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:n.appearance}),r(),i();break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CREATE_PAYMENT_INTENT`:n.onInitiatePaymentIntentRequest({paymentIntentCreateAttributes:t.data.paymentIntentCreateAttributes,customerCreateAttributes:t.data.customerCreateAttributes}).then(t=>{d({iframe:e,token:t})}).catch(e=>{n.onResult({status:`failed`,errorMessage:e instanceof Error?e.message:`Unknown error`})});break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result);break}}return window.addEventListener(`message`,a),{update(t){let a=`appearance`in t,o=`amount`in t,c=`merchantName`in t;n={...n,...t},a&&s({iframe:e,appearance:n.appearance}),o&&r(),c&&i()},destroy(){window.removeEventListener(`message`,a)}}}function x({paymentData:e}){return{paymentMethod:{type:`googlepay`,billing_address_attributes:{name:e.shippingAddress?.name,address_line1:e.shippingAddress?.address1,address_line2:e.shippingAddress?.address2,city:e.shippingAddress?.locality,state:e.shippingAddress?.administrativeArea,postal_code:e.shippingAddress?.postalCode,country:e.shippingAddress?.countryCode,email:e.email,phone:e.shippingAddress?.phoneNumber},card_profile_attributes:{wallet_provider:`googlepay`,wallet_payload:e.paymentMethodData.tokenizationData.token,wallet_last4:e.paymentMethodData.info?.cardDetails,wallet_brand:(()=>{switch(e.paymentMethodData.info?.cardNetwork){case`AMEX`:return`american_express`;case`VISA`:return`visa`;case`MASTERCARD`:return`master`;case`DISCOVER`:return`discover`;default:return}})()}}}}var S={country:212,full:452},C=80,w={country:400,full:640};function T(e,t={cardholderName:!1},n=`country`){let r=Object.entries(t).filter(([,e])=>e).map(([e])=>e).join(`,`),a=new URLSearchParams({token:e,additionalFields:r,billingAddressRequirement:n});return`${i(e)}/iframe/card?${a}`}function E(e,t=`country`){let n=new URLSearchParams({token:e,billingAddressRequirement:t});return`${i(e)}/iframe/bank?${n}`}function D(e={cardholderName:!1},t=`country`){return`${(S[t]??S.country)+(e.cardholderName?C:0)}px`}function O(e=`country`){return`${w[e]??w.country}px`}function k(e,t){let n={...t};function r(t){switch(t.data.type){case`IFRAME_READY`:o(e),s({iframe:e,appearance:n.appearance});break;case`UPDATE_HEIGHT`:n.onHeightChange?.(t.data.height);break;case`UPDATE_APPEARANCE`:s({iframe:e,appearance:t.data.appearance});break;case`UPDATED_APPEARANCE`:n.onAppearanceReady?.();break;case`CONFIRMATION_RESULT`:n.onResult(t.data.result);break}}return window.addEventListener(`message`,r),{update(t){let r=`appearance`in t;n={...n,...t},r&&s({iframe:e,appearance:n.appearance})},destroy(){window.removeEventListener(`message`,r)}}}function A(e){if(typeof e==`string`){let t=document.querySelector(e);if(!(t instanceof HTMLElement))throw Error(`[amos-js] Container "${e}" did not match any HTMLElement.`);return t}return e}var j={width:`calc(100% + 8px)`,transition:`opacity 150ms ease-in, height 200ms ease-in-out`,margin:`0 -4px`,opacity:`0`,border:`0`};function M({src:e,title:t,name:n,height:r,allow:i}){let a=document.createElement(`iframe`);return a.src=e,a.title=t,a.name=n,a.setAttribute(`role`,`presentation`),a.scrolling=`no`,i&&(a.allow=i),Object.assign(a.style,j,{height:r}),a}function N(e,t){let n=A(e),{renderToken:r,additionalFields:i={cardholderName:!1},billingAddressRequirement:a=`country`,...o}=t,s=M({src:T(r,i,a),title:`Secure credit card payment method form powered by Amos`,name:`amos-credit-card-payment-method-form`,height:D(i,a)});n.appendChild(s);let c=k(s,{...o,onHeightChange:e=>{s.style.height=e,o.onHeightChange?.(e)},onAppearanceReady:()=>{s.style.opacity=`1`,o.onAppearanceReady?.()}});return{iframe:s,update:c.update,destroy(){c.destroy(),s.remove()}}}function P(e,t){let n=A(e),{renderToken:r,billingAddressRequirement:i=`country`,...a}=t,o=M({src:E(r,i),title:`Secure bank account payment method form powered by Amos`,name:`amos-bank-account-payment-method-form`,height:O(i)});n.appendChild(o);let s=k(o,{...a,onHeightChange:e=>{o.style.height=e,a.onHeightChange?.(e)},onAppearanceReady:()=>{o.style.opacity=`1`,a.onAppearanceReady?.()}});return{iframe:o,update:s.update,destroy(){s.destroy(),o.remove()}}}function F(e,t){let n=A(e),{renderToken:r,...i}=t,a=M({src:v(r),title:`Secure Google Pay button powered by Amos`,name:`amos-google-pay-button`,height:y(),allow:`payment`});n.appendChild(a);let o=b(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}function I(e,t){let n=A(e),{renderToken:r,...i}=t,a=M({src:m(r),title:`Secure Apple Pay button powered by Amos`,name:`amos-apple-pay-button`,height:h(),allow:`payment`});n.appendChild(a);let o=_(a,{...i,onHeightChange:e=>{a.style.height=e,i.onHeightChange?.(e)},onAppearanceReady:()=>{a.style.opacity=`1`,i.onAppearanceReady?.()}});return{iframe:a,update:o.update,destroy(){o.destroy(),a.remove()}}}exports.attachApplePayButtonListeners=_,exports.attachGooglePayButtonListeners=b,exports.attachPaymentMethodFormListeners=k,exports.confirmPaymentIntent=d,exports.confirmSetupIntent=f,exports.createMessage=a,exports.decodeJwt=r,exports.formatGooglePayPaymentData=x,exports.getApplePayButtonInitialHeight=h,exports.getApplePayButtonSrc=m,exports.getBankAccountFormInitialHeight=O,exports.getBankAccountFormSrc=E,exports.getCreditCardFormInitialHeight=D,exports.getCreditCardFormSrc=T,exports.getEmbedOrigin=i,exports.getGooglePayButtonInitialHeight=y,exports.getGooglePayButtonSrc=v,exports.mountAmosApplePayButton=I,exports.mountAmosBankAccountPaymentMethodForm=P,exports.mountAmosCreditCardPaymentMethodForm=N,exports.mountAmosGooglePayButton=F,exports.sendConfirmationResult=p,exports.sendParentReadyMessage=o,exports.updateAmount=c,exports.updateAppearance=s,exports.updateMerchantName=l,exports.validateForm=u;

package/dist/index.mjs

@@ -142,10 +142,10 @@ function f({ iframe: e, token: t }) {
 		id: n ?? void 0
 	}), "*");
 }
-function p({ iframe: e, errorMessage: t }) {
+function p({ iframe: e, result: t }) {
 	e?.contentWindow?.postMessage(a({
-		type: "CONFIRMATION_FAILED",
-		errorMessage: t
+		type: "CONFIRMATION_RESULT",
+		result: t
 	}), "*");
 }
 //#endregion
@@ -210,18 +210,15 @@ function _(e, r) {
 						iframe: e,
 						token: t
 					});
-				}).catch((t) => {
-					p({
-						iframe: e,
-						errorMessage: t instanceof Error ? t.message : "Unknown error"
+				}).catch((e) => {
+					n(), i.onResult({
+						status: "failed",
+						errorMessage: e instanceof Error ? e.message : "Unknown error"
 					});
 				});
 				break;
-			case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-				n(), i.onPaymentIntentConfirmationSucceeded(r.data.paymentIntent);
-				break;
-			case "CONFIRMATION_FAILED":
-				n(), i.onConfirmationFailed(r.data.errorMessage);
+			case "CONFIRMATION_RESULT":
+				n(), i.onResult(r.data.result);
 				break;
 		}
 	}
@@ -292,18 +289,15 @@ function b(e, t) {
 						iframe: e,
 						token: t
 					});
-				}).catch((t) => {
-					p({
-						iframe: e,
-						errorMessage: t instanceof Error ? t.message : "Unknown error"
+				}).catch((e) => {
+					n.onResult({
+						status: "failed",
+						errorMessage: e instanceof Error ? e.message : "Unknown error"
 					});
 				});
 				break;
-			case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-				n.onPaymentIntentConfirmationSucceeded(t.data.paymentIntent);
-				break;
-			case "CONFIRMATION_FAILED":
-				n.onConfirmationFailed(t.data.errorMessage);
+			case "CONFIRMATION_RESULT":
+				n.onResult(t.data.result);
 				break;
 		}
 	}
@@ -405,14 +399,8 @@ function k(e, t) {
 			case "UPDATED_APPEARANCE":
 				n.onAppearanceReady?.();
 				break;
-			case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-				n.onPaymentIntentConfirmationSucceeded?.(t.data.paymentIntent);
-				break;
-			case "SETUP_INTENT_CONFIRMATION_SUCCEEDED":
-				n.onSetupIntentConfirmationSucceeded?.(t.data.setupIntent);
-				break;
-			case "CONFIRMATION_FAILED":
-				n.onConfirmationFailed(t.data.errorMessage);
+			case "CONFIRMATION_RESULT":
+				n.onResult(t.data.result);
 				break;
 		}
 	}
@@ -556,4 +544,4 @@ function I(e, t) {
 	};
 }
 //#endregion
-export { _ as attachApplePayButtonListeners, b as attachGooglePayButtonListeners, k as attachPaymentMethodFormListeners, d as confirmPaymentIntent, f as confirmSetupIntent, a as createMessage, r as decodeJwt, x as formatGooglePayPaymentData, h as getApplePayButtonInitialHeight, m as getApplePayButtonSrc, O as getBankAccountFormInitialHeight, E as getBankAccountFormSrc, D as getCreditCardFormInitialHeight, T as getCreditCardFormSrc, i as getEmbedOrigin, y as getGooglePayButtonInitialHeight, v as getGooglePayButtonSrc, I as mountAmosApplePayButton, P as mountAmosBankAccountPaymentMethodForm, N as mountAmosCreditCardPaymentMethodForm, F as mountAmosGooglePayButton, p as sendConfirmationFailed, o as sendParentReadyMessage, c as updateAmount, s as updateAppearance, l as updateMerchantName, u as validateForm };
+export { _ as attachApplePayButtonListeners, b as attachGooglePayButtonListeners, k as attachPaymentMethodFormListeners, d as confirmPaymentIntent, f as confirmSetupIntent, a as createMessage, r as decodeJwt, x as formatGooglePayPaymentData, h as getApplePayButtonInitialHeight, m as getApplePayButtonSrc, O as getBankAccountFormInitialHeight, E as getBankAccountFormSrc, D as getCreditCardFormInitialHeight, T as getCreditCardFormSrc, i as getEmbedOrigin, y as getGooglePayButtonInitialHeight, v as getGooglePayButtonSrc, I as mountAmosApplePayButton, P as mountAmosBankAccountPaymentMethodForm, N as mountAmosCreditCardPaymentMethodForm, F as mountAmosGooglePayButton, p as sendConfirmationResult, o as sendParentReadyMessage, c as updateAmount, s as updateAppearance, l as updateMerchantName, u as validateForm };

package/dist/messaging.d.ts

@@ -1,5 +1,5 @@
 import { components } from '@amos.com/node';
-import { Appearance } from './types';
+import { Appearance, Message } from './types';
 type Iframe = HTMLIFrameElement | null | undefined;
 /**
  * Notify the embedded iframe that the host page is ready to receive
@@ -65,11 +65,13 @@ export declare function confirmSetupIntent({ iframe, token, }: {
     iframe: Iframe;
 } & Pick<components["schemas"]["EmbedToken"], "token">): void;
 /**
- * Notify the iframe that confirmation failed (used by express-checkout
- * flows after `onInitiatePaymentIntentRequest` rejects).
+ * Notify the iframe that confirmation finished with a failure (used by
+ * express-checkout flows after `onInitiatePaymentIntentRequest` rejects).
  */
-export declare function sendConfirmationFailed({ iframe, errorMessage, }: {
+export declare function sendConfirmationResult({ iframe, result, }: {
     iframe: Iframe;
-    errorMessage: string;
+    result: Extract<Message, {
+        type: "CONFIRMATION_RESULT";
+    }>["result"];
 }): void;
 export {};

package/dist/payment-method-form.d.ts

@@ -1,5 +1,4 @@
-import { components } from '@amos.com/node';
-import { Appearance } from './types';
+import { Appearance, ConfirmationResult } from './types';
 /**
  * The additional fields beyond the standard card number, expiration
  * date, CVV, and billing address fields that are required to be filled
@@ -61,17 +60,11 @@ export type PaymentMethodFormListenerOptions = {
      */
     onAppearanceReady?: () => void;
     /**
-     * Called when payment intent confirmation succeeds.
+     * Called when the interactive confirmation flow finishes (success or
+     * terminal failure). Not settlement proof — verify via webhooks.
+     * Recoverable field errors stay in the iframe and do not invoke this.
      */
-    onPaymentIntentConfirmationSucceeded?: (paymentIntent: components["schemas"]["PaymentIntent"]) => void;
-    /**
-     * Called when setup intent confirmation succeeds.
-     */
-    onSetupIntentConfirmationSucceeded?: (setupIntent: components["schemas"]["SetupIntent"]) => void;
-    /**
-     * Called when payment or setup intent confirmation fails.
-     */
-    onConfirmationFailed: (errorMessage: string) => void;
+    onResult: (result: ConfirmationResult) => void;
 };
 /**
  * Controller returned by {@link attachPaymentMethodFormListeners} and

package/dist/types.d.ts

@@ -1,4 +1,35 @@
 import { components } from '@amos.com/node';
+/**
+ * Outcome of an interactive confirmation flow inside the Amos iframe.
+ *
+ * `onResult` / `CONFIRMATION_RESULT` means the host should stop waiting
+ * (e.g. dismiss a spinner). It is **not** proof that funds were
+ * received — verify settlement on your backend via webhooks (or by
+ * retrieving the PaymentIntent / SetupIntent with your secret key),
+ * the same way Stripe recommends.
+ *
+ * Recoverable field validation errors (e.g. bad expiration year) are
+ * shown inside the iframe and do **not** produce a result; the customer
+ * can fix the form and retry.
+ */
+export type ConfirmationResult = {
+    status: "succeeded";
+    intent: "payment";
+    paymentIntent: components["schemas"]["PaymentIntent"];
+} | {
+    status: "succeeded";
+    intent: "setup";
+    setupIntent: components["schemas"]["SetupIntent"];
+} | {
+    /**
+     * Recoverable validation was shown in the iframe. Unlock the host UI;
+     * the customer can fix fields and retry. Do not treat as settlement.
+     */
+    status: "incomplete";
+} | {
+    status: "failed";
+    errorMessage: string;
+};
 /**
  * CSS custom properties that control the appearance of the embedded
  * Amos iframe UI. Only the variables you provide are sent; omitted
@@ -58,14 +89,13 @@ export type Message = {
 } & Pick<components["schemas"]["PaymentIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | ({
     type: "CONFIRM_SETUP_INTENT";
 } & Pick<components["schemas"]["SetupIntent"], "id"> & Pick<components["schemas"]["EmbedToken"], "token">) | {
-    type: "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED";
-    paymentIntent: components["schemas"]["PaymentIntent"];
-} | {
-    type: "SETUP_INTENT_CONFIRMATION_SUCCEEDED";
-    setupIntent: components["schemas"]["SetupIntent"];
-} | {
-    type: "CONFIRMATION_FAILED";
-    errorMessage: string;
+    /**
+     * Embed → parent: the interactive confirmation flow finished.
+     * Not settlement proof — verify payment/setup success on your
+     * backend via webhooks (or by retrieving the intent).
+     */
+    type: "CONFIRMATION_RESULT";
+    result: ConfirmationResult;
 } | {
     type: "UPDATED_APPEARANCE";
 } | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/amos-js",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -44,7 +44,7 @@
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/node": "0.1.33",
+    "@amos.com/node": "0.1.34",
     "@types/googlepay": "0.7.11"
   }
 }

package/src/apple-pay.ts

@@ -6,13 +6,17 @@ import {
 import { getEmbedOrigin } from "./jwt";
 import {
   confirmPaymentIntent,
-  sendConfirmationFailed,
   sendParentReadyMessage,
   updateAmount as sendUpdateAmount,
   updateAppearance as sendUpdateAppearance,
   updateMerchantName as sendUpdateMerchantName,
 } from "./messaging";
-import { type Appearance, createMessage, type Message } from "./types";
+import {
+  type Appearance,
+  type ConfirmationResult,
+  createMessage,
+  type Message,
+} from "./types";
 
 /**
  * Build the iframe `src` URL for the embedded Apple Pay button.
@@ -64,15 +68,10 @@ export type ApplePayButtonListenerOptions = {
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
   }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
   /**
-   * Called when payment intent confirmation succeeds.
-   */
-  onPaymentIntentConfirmationSucceeded: (
-    paymentIntent: components["schemas"]["PaymentIntent"],
-  ) => void;
-  /**
-   * Called when payment intent confirmation fails.
+   * Called when the interactive confirmation flow finishes (success or
+   * terminal failure). Not settlement proof — verify via webhooks.
    */
-  onConfirmationFailed: (errorMessage: string) => void;
+  onResult: (result: ConfirmationResult) => void;
 };
 
 /**
@@ -176,22 +175,18 @@ export function attachApplePayButtonListeners(
             confirmPaymentIntent({ iframe, token });
           })
           .catch((error: unknown) => {
-            sendConfirmationFailed({
-              iframe,
+            hideApplePayWaitingOverlay();
+            current.onResult({
+              status: "failed",
               errorMessage:
                 error instanceof Error ? error.message : "Unknown error",
             });
           });
         break;
 
-      case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-        hideApplePayWaitingOverlay();
-        current.onPaymentIntentConfirmationSucceeded(event.data.paymentIntent);
-        break;
-
-      case "CONFIRMATION_FAILED":
+      case "CONFIRMATION_RESULT":
         hideApplePayWaitingOverlay();
-        current.onConfirmationFailed(event.data.errorMessage);
+        current.onResult(event.data.result);
         break;
     }
   }

package/src/google-pay.ts

@@ -4,13 +4,12 @@ import type { components } from "@amos.com/node";
 import { getEmbedOrigin } from "./jwt";
 import {
   confirmPaymentIntent,
-  sendConfirmationFailed,
   sendParentReadyMessage,
   updateAmount as sendUpdateAmount,
   updateAppearance as sendUpdateAppearance,
   updateMerchantName as sendUpdateMerchantName,
 } from "./messaging";
-import type { Appearance, Message } from "./types";
+import type { Appearance, ConfirmationResult, Message } from "./types";
 
 /**
  * Build the iframe `src` URL for the embedded Google Pay button.
@@ -62,15 +61,10 @@ export type GooglePayButtonListenerOptions = {
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
   }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
   /**
-   * Called when payment intent confirmation succeeds.
+   * Called when the interactive confirmation flow finishes (success or
+   * terminal failure). Not settlement proof — verify via webhooks.
    */
-  onPaymentIntentConfirmationSucceeded: (
-    paymentIntent: components["schemas"]["PaymentIntent"],
-  ) => void;
-  /**
-   * Called when payment intent confirmation fails.
-   */
-  onConfirmationFailed: (errorMessage: string) => void;
+  onResult: (result: ConfirmationResult) => void;
 };
 
 /**
@@ -144,20 +138,16 @@ export function attachGooglePayButtonListeners(
             confirmPaymentIntent({ iframe, token });
           })
           .catch((error: unknown) => {
-            sendConfirmationFailed({
-              iframe,
+            current.onResult({
+              status: "failed",
               errorMessage:
                 error instanceof Error ? error.message : "Unknown error",
             });
           });
         break;
 
-      case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-        current.onPaymentIntentConfirmationSucceeded(event.data.paymentIntent);
-        break;
-
-      case "CONFIRMATION_FAILED":
-        current.onConfirmationFailed(event.data.errorMessage);
+      case "CONFIRMATION_RESULT":
+        current.onResult(event.data.result);
         break;
     }
   }

package/src/index.ts

@@ -27,7 +27,7 @@ export { decodeJwt, getEmbedOrigin } from "./jwt";
 export {
   confirmPaymentIntent,
   confirmSetupIntent,
-  sendConfirmationFailed,
+  sendConfirmationResult,
   sendParentReadyMessage,
   updateAmount,
   updateAppearance,
@@ -65,6 +65,7 @@ export {
 export type {
   Appearance,
   AppearanceLabels,
+  ConfirmationResult,
   Message,
   ThemeVariable,
 } from "./types";

package/src/messaging.ts

@@ -157,20 +157,20 @@ export function confirmSetupIntent({
 }
 
 /**
- * Notify the iframe that confirmation failed (used by express-checkout
- * flows after `onInitiatePaymentIntentRequest` rejects).
+ * Notify the iframe that confirmation finished with a failure (used by
+ * express-checkout flows after `onInitiatePaymentIntentRequest` rejects).
  */
-export function sendConfirmationFailed({
+export function sendConfirmationResult({
   iframe,
-  errorMessage,
+  result,
 }: {
   iframe: Iframe;
-  errorMessage: string;
+  result: Extract<Message, { type: "CONFIRMATION_RESULT" }>["result"];
 }): void {
   iframe?.contentWindow?.postMessage(
     createMessage({
-      type: "CONFIRMATION_FAILED",
-      errorMessage,
+      type: "CONFIRMATION_RESULT",
+      result,
     }),
     "*",
   );

package/src/payment-method-form.ts

@@ -1,10 +1,9 @@
-import type { components } from "@amos.com/node";
 import { getEmbedOrigin } from "./jwt";
 import {
   sendParentReadyMessage,
   updateAppearance as sendUpdateAppearance,
 } from "./messaging";
-import type { Appearance, Message } from "./types";
+import type { Appearance, ConfirmationResult, Message } from "./types";
 
 /**
  * The additional fields beyond the standard card number, expiration
@@ -128,21 +127,11 @@ export type PaymentMethodFormListenerOptions = {
    */
   onAppearanceReady?: () => void;
   /**
-   * Called when payment intent confirmation succeeds.
+   * Called when the interactive confirmation flow finishes (success or
+   * terminal failure). Not settlement proof — verify via webhooks.
+   * Recoverable field errors stay in the iframe and do not invoke this.
    */
-  onPaymentIntentConfirmationSucceeded?: (
-    paymentIntent: components["schemas"]["PaymentIntent"],
-  ) => void;
-  /**
-   * Called when setup intent confirmation succeeds.
-   */
-  onSetupIntentConfirmationSucceeded?: (
-    setupIntent: components["schemas"]["SetupIntent"],
-  ) => void;
-  /**
-   * Called when payment or setup intent confirmation fails.
-   */
-  onConfirmationFailed: (errorMessage: string) => void;
+  onResult: (result: ConfirmationResult) => void;
 };
 
 /**
@@ -196,18 +185,8 @@ export function attachPaymentMethodFormListeners(
         current.onAppearanceReady?.();
         break;
 
-      case "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED":
-        current.onPaymentIntentConfirmationSucceeded?.(
-          event.data.paymentIntent,
-        );
-        break;
-
-      case "SETUP_INTENT_CONFIRMATION_SUCCEEDED":
-        current.onSetupIntentConfirmationSucceeded?.(event.data.setupIntent);
-        break;
-
-      case "CONFIRMATION_FAILED":
-        current.onConfirmationFailed(event.data.errorMessage);
+      case "CONFIRMATION_RESULT":
+        current.onResult(event.data.result);
         break;
     }
   }

package/src/types.ts

@@ -1,5 +1,41 @@
 import type { components } from "@amos.com/node";
 
+/**
+ * Outcome of an interactive confirmation flow inside the Amos iframe.
+ *
+ * `onResult` / `CONFIRMATION_RESULT` means the host should stop waiting
+ * (e.g. dismiss a spinner). It is **not** proof that funds were
+ * received — verify settlement on your backend via webhooks (or by
+ * retrieving the PaymentIntent / SetupIntent with your secret key),
+ * the same way Stripe recommends.
+ *
+ * Recoverable field validation errors (e.g. bad expiration year) are
+ * shown inside the iframe and do **not** produce a result; the customer
+ * can fix the form and retry.
+ */
+export type ConfirmationResult =
+  | {
+      status: "succeeded";
+      intent: "payment";
+      paymentIntent: components["schemas"]["PaymentIntent"];
+    }
+  | {
+      status: "succeeded";
+      intent: "setup";
+      setupIntent: components["schemas"]["SetupIntent"];
+    }
+  | {
+      /**
+       * Recoverable validation was shown in the iframe. Unlock the host UI;
+       * the customer can fix fields and retry. Do not treat as settlement.
+       */
+      status: "incomplete";
+    }
+  | {
+      status: "failed";
+      errorMessage: string;
+    };
+
 /**
  * CSS custom properties that control the appearance of the embedded
  * Amos iframe UI. Only the variables you provide are sent; omitted
@@ -178,16 +214,13 @@ export type Message =
     } & Pick<components["schemas"]["SetupIntent"], "id"> &
       Pick<components["schemas"]["EmbedToken"], "token">)
   | {
-      type: "PAYMENT_INTENT_CONFIRMATION_SUCCEEDED";
-      paymentIntent: components["schemas"]["PaymentIntent"];
-    }
-  | {
-      type: "SETUP_INTENT_CONFIRMATION_SUCCEEDED";
-      setupIntent: components["schemas"]["SetupIntent"];
-    }
-  | {
-      type: "CONFIRMATION_FAILED";
-      errorMessage: string;
+      /**
+       * Embed → parent: the interactive confirmation flow finished.
+       * Not settlement proof — verify payment/setup success on your
+       * backend via webhooks (or by retrieving the intent).
+       */
+      type: "CONFIRMATION_RESULT";
+      result: ConfirmationResult;
     }
   | {
       type: "UPDATED_APPEARANCE";