@amos.com/react-amos-js 0.10.6 → 0.11.1

package/README.md

@@ -15,8 +15,8 @@ npm install @amos.com/react-amos-js @amos.com/node
 ## What it gives you
 
 - React components for the iframe payment method forms: `AmosCreditCardPaymentMethodForm`, `AmosBankAccountPaymentMethodForm`, `AmosGooglePayButton`, `AmosApplePayButton`.
-- React-flavoured iframe message helpers that accept a React `ref`: `validateForm({ iframeRef })`, `confirmPaymentIntent({ iframeRef, token })`, `confirmSetupIntent({ iframeRef, token })`, `resetForm({ iframeRef })`.
-- Re-exports of the `@amos.com/amos-js` helpers and types that come up in client code: `createMessage`, `decodeJwt`, `getEmbedOrigin`, `formatGooglePayPaymentData`, `resetForm`, `ConfirmationResult`, `ConfirmationIncompleteReason`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
+- React-flavoured iframe message helpers that accept a React `ref`: `validateForm({ iframeRef })`, `confirmPayment({ iframeRef, token })`, `confirmSetup({ iframeRef, token })`, `resetForm({ iframeRef })`.
+- Re-exports of the `@amos.com/amos-js` helpers and types that come up in client code: `createMessage`, `decodeJwt`, `getEmbedOrigin`, `formatGooglePayPaymentData`, `resetForm`, `ConfirmResult`, `ConfirmationResult`, `ConfirmationIncompleteReason`, `FormattedGooglePayPaymentData`, `Appearance`, `Message`, etc.
 
 > **Note:** `@amos.com/react-amos-js` is the client-side half of the Amos integration. For end-to-end payment processing you also need `@amos.com/node` on your server (creating payment intents, handling webhooks, etc.). The same `@amos.com/node` package is listed as a peer dependency so you can import its OpenAPI types in client-side TypeScript code.
 
@@ -39,12 +39,12 @@ 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`) along with the required `onResult` prop. 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.
+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.
 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({ iframeRef, token })` to continue the payment flow.
-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"` with `reason`: `"field_errors"` or `"validation_failed"`).
+6. **Confirm the payment intent from the client**: `await confirmPayment({ iframeRef, token })`. Deprecated alias: `confirmPaymentIntent`.
+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; `confirmPayment` still resolves `{ status: "failed" }`. Legacy hosts can keep optional `onResult`.
 
 ### Google Pay & Apple Pay
 
@@ -52,17 +52,17 @@ Google Pay and Apple Pay are forms of express checkout. Their buttons are altern
 
 The key differences between the express and non-express payment flows are:
 
-- The express payment method components accept a prop called `onInitiatePaymentIntentRequest` which will be called when you should create the payment intent on your server.
+- The express payment method components accept `onConfirm`. Create a payment intent, then `await confirmPayment(token)`.
 - You do not call `validateForm` in an express flow.
-- You do not call `confirmPaymentIntent` in an express flow (this is done after `onInitiatePaymentIntentRequest` returns a token).
+- You call `confirmPayment` inside `onConfirm` (the SDK no longer auto-confirms).
 
 ## Understanding the flow for creating and confirming setup intents
 
 Setup intents are used to save payment methods for future use (e.g. recurring payments, subscriptions) without charging the customer immediately. The flow is identical to a payment intent, except:
 
 - On the server, call `POST /setup_intents` instead of `POST /payment_intents`.
-- On the client, call `confirmSetupIntent({ iframeRef, token })` instead of `confirmPaymentIntent({ iframeRef, token })`.
-- The same `onResult` callback is used; succeeded setup intents arrive as `{ status: "succeeded", intent: "setup", setupIntent }`.
+- On the client, `await confirmSetup({ iframeRef, token })` instead of `confirmPayment({ iframeRef, token })`. Deprecated alias: `confirmSetupIntent`.
+- Both resolve `{ status: "succeeded" | "failed" }`.
 
 The same `AmosCreditCardPaymentMethodForm` / `AmosBankAccountPaymentMethodForm` components support both payment intents and setup intents — they are differentiated by which confirmation function you call. For bank setup, pass `intent="setup"` so Connect / Plaid is always shown (no merchant ACH threshold lookup).
 
@@ -75,8 +75,8 @@ Why this matters:
 - The payment method UI is rendered inside Amos-hosted iframes, so sensitive input fields are not part of your DOM.
 - Raw payment details are submitted from the iframe directly to Amos-controlled infrastructure.
 - Your backend only creates payment intents (or setup intents) and returns a short-lived token used to continue the iframe flow.
-- `confirmPaymentIntent` / `confirmSetupIntent` sends the token back to the iframe to complete confirmation; it does not pass full payment method payloads through your app server.
-- In express flows (Google Pay / Apple Pay), the iframe component handles payment data exchange and only asks your server to create a payment intent token.
+- `confirmPayment` / `confirmSetup` send the token back to the iframe to complete confirmation; they do not pass full payment method payloads through your app server.
+- In express flows (Google Pay / Apple Pay), the iframe handles payment data exchange and calls `onConfirm` so your server can create a payment intent token, then you `await confirmPayment(token)`.
 
 In short, your app orchestrates the payment flow, while sensitive payment data stays within Amos-controlled components and APIs.
 
@@ -94,10 +94,6 @@ Card and bank components accept an optional `appearance` prop that controls the
       "--radius": "0.25rem",
     },
   }}
-  onResult={(result) => {
-    if (result.status === "failed") setError(result.errorMessage);
-    if (result.status === "incomplete") setError(null);
-  }}
 />
 ```
 
@@ -167,7 +163,7 @@ Radio groups (e.g. account type) always use an above-style group label regardles
 import { useRef, useState } from "react";
 import {
   AmosCreditCardPaymentMethodForm,
-  confirmPaymentIntent,
+  confirmPayment,
   validateForm,
 } from "@amos.com/react-amos-js";
 import type { components } from "@amos.com/node";
@@ -212,7 +208,10 @@ function CheckoutForm() {
       }
 
       const { token } = await response.json();
-      confirmPaymentIntent({ iframeRef, token });
+      const result = await confirmPayment({ iframeRef, token });
+      if (result.status !== "succeeded") {
+        setError("Payment failed. Please try again.");
+      }
     } catch (error) {
       setError(error instanceof Error ? error.message : "Unknown error");
     } finally {
@@ -227,16 +226,6 @@ function CheckoutForm() {
         renderToken="the-render-token-that-you-created-on-dashboard.amos.com"
         additionalFields={{ cardholderName: true }}
         onValidityChange={({ isValid }) => setIsValid(isValid)}
-        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);
-          } else if (result.status === "incomplete") {
-            console.log("Recoverable:", result.reason);
-          }
-        }}
       />
       {error ? <p>{error}</p> : null}
       <button type="submit" disabled={!isValid || isProcessing}>
@@ -254,7 +243,7 @@ import { useState } from "react";
 import {
   AmosApplePayButton,
   AmosGooglePayButton,
-  type ConfirmationResult,
+  type ConfirmResult,
 } from "@amos.com/react-amos-js";
 import type { components } from "@amos.com/node";
 
@@ -283,13 +272,28 @@ async function createPaymentIntentToken({
 function CheckoutWallets({ renderToken }: { renderToken: string }) {
   const [error, setError] = useState<string | null>(null);
 
-  function handleResult(result: ConfirmationResult) {
-    if (result.status === "succeeded") {
-      console.log("Confirm returned:", result);
-    } else if (result.status === "failed") {
-      setError(result.errorMessage);
-    } else if (result.status === "incomplete") {
-      console.log("Recoverable:", result.reason);
+  async function handleConfirm({
+    paymentIntentCreateAttributes,
+    customerCreateAttributes,
+    confirmPayment,
+  }: {
+    paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
+    customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
+    confirmPayment: (token: string) => Promise<ConfirmResult>;
+  }): Promise<ConfirmResult> {
+    try {
+      const token = await createPaymentIntentToken({
+        paymentIntentCreateAttributes,
+        customerCreateAttributes,
+      });
+      const result = await confirmPayment(token);
+      if (result.status === "failed") {
+        setError("Payment failed. Please try again.");
+      }
+      return result;
+    } catch (error) {
+      setError(error instanceof Error ? error.message : "Unknown error");
+      return { status: "failed" };
     }
   }
 
@@ -301,8 +305,7 @@ function CheckoutWallets({ renderToken }: { renderToken: string }) {
             renderToken={renderToken}
             amount="50.00"
             merchantName="Example Store"
-            onInitiatePaymentIntentRequest={createPaymentIntentToken}
-            onResult={handleResult}
+            onConfirm={handleConfirm}
           />
         </div>
         <div style={{ flex: "1 1 0", minWidth: 0 }}>
@@ -310,8 +313,7 @@ function CheckoutWallets({ renderToken }: { renderToken: string }) {
             renderToken={renderToken}
             amount="50.00"
             merchantName="Example Store"
-            onInitiatePaymentIntentRequest={createPaymentIntentToken}
-            onResult={handleResult}
+            onConfirm={handleConfirm}
           />
         </div>
       </div>
@@ -321,7 +323,7 @@ function CheckoutWallets({ renderToken }: { renderToken: string }) {
 }
 ```
 
-Do not call `validateForm` or `confirmPaymentIntent` — return the embed token from `onInitiatePaymentIntentRequest` and the SDK confirms. Size the mount slot; omitted `buttonProps` keep paint defaults and fill the iframe.
+Do not call `validateForm` from the host in an express flow — create a payment intent inside `onConfirm`, then `await confirmPayment(token)`. Size the mount slot; omitted `buttonProps` keep paint defaults and fill the iframe.
 
 On Safari, Apple Pay uses the native payment sheet. On other browsers, Apple's QR handoff opens in a popup (`pay.apple.com`); while that popup is open, the SDK shows a waiting overlay with **Cancel payment**.
 
@@ -335,8 +337,7 @@ Optional visuals:
   height="48px"
   buttonProps={{ buttonType: "donate", buttonBorderType: "no_border" }}
   iframeProps={{ style: { borderRadius: "8px" } }}
-  onInitiatePaymentIntentRequest={createPaymentIntentToken}
-  onResult={handleResult}
+  onConfirm={handleConfirm}
 />
 
 <AmosApplePayButton
@@ -346,8 +347,7 @@ Optional visuals:
   height="48px"
   buttonProps={{ type: "donate" }}
   iframeProps={{ style: { borderRadius: "8px" } }}
-  onInitiatePaymentIntentRequest={createPaymentIntentToken}
-  onResult={handleResult}
+  onConfirm={handleConfirm}
 />
 ```
 
@@ -357,7 +357,7 @@ Optional visuals:
 import { useRef, useState } from "react";
 import {
   AmosCreditCardPaymentMethodForm,
-  confirmSetupIntent,
+  confirmSetup,
   validateForm,
 } from "@amos.com/react-amos-js";
 
@@ -393,7 +393,10 @@ function SavePaymentMethodForm() {
       }
 
       const { token } = await response.json();
-      confirmSetupIntent({ iframeRef, token });
+      const result = await confirmSetup({ iframeRef, token });
+      if (result.status !== "succeeded") {
+        setError("Failed to save the payment method.");
+      }
     } catch (error) {
       setError(error instanceof Error ? error.message : "Unknown error");
     } finally {
@@ -406,15 +409,6 @@ function SavePaymentMethodForm() {
       <AmosCreditCardPaymentMethodForm
         ref={iframeRef}
         renderToken="the-render-token-that-you-created-on-dashboard.amos.com"
-        onResult={(result) => {
-          if (result.status === "succeeded") {
-            console.log("Confirm returned:", result);
-          } else if (result.status === "failed") {
-            console.error("Confirm failed:", result.errorMessage);
-          } else if (result.status === "incomplete") {
-            console.log("Recoverable:", result.reason);
-          }
-        }}
       />
       {error ? <p>{error}</p> : null}
       <button type="submit" disabled={isProcessing}>
@@ -437,31 +431,31 @@ Validates the embedded card/bank iframe form before payment confirmation.
 
 **Returns:** `Promise<boolean>` (resolves to `false` after 5 seconds if the iframe does not respond).
 
-### `confirmPaymentIntent({ iframeRef, token })`
+### `confirmPayment({ iframeRef, token })`
 
-Confirms a payment intent in the embedded iframe flow.
+Confirms a payment intent in the embedded iframe flow. Resolves `{ status: "succeeded" }` or `{ status: "failed" }`. Deprecated alias: `confirmPaymentIntent`.
 
 **Parameters:**
 
 - `iframeRef` (`React.RefObject<HTMLIFrameElement | null> | undefined`, required)
 - `token` (typed as `Pick<components["schemas"]["EmbedToken"], "token">` — the embed JWT string returned by your server)
 
-**Returns:** `void`
+**Returns:** `Promise<ConfirmResult>`
 
-### `confirmSetupIntent({ iframeRef, token })`
+### `confirmSetup({ iframeRef, token })`
 
-Confirms a setup intent in the embedded iframe flow. Use this when saving a payment method for future use.
+Confirms a setup intent in the embedded iframe flow. Use this when saving a payment method for future use. Deprecated alias: `confirmSetupIntent`.
 
 **Parameters:**
 
 - `iframeRef` (`React.RefObject<HTMLIFrameElement | null> | undefined`, required)
 - `token` (same `Pick<components["schemas"]["EmbedToken"], "token">` embed JWT string as for payment confirmation)
 
-**Returns:** `void`
+**Returns:** `Promise<ConfirmResult>`
 
 ### `resetForm({ iframeRef })`
 
-Clears all field values and API errors in the embedded card/bank iframe form. Call after `onResult` when the customer wants to try again (for example, after a successful payment when starting a new one).
+Clears all field values and API errors in the embedded card/bank iframe form. Call after a failed or incomplete confirm when the customer wants to try again (for example, after a successful payment when starting a new one).
 
 **Parameters:**
 
@@ -476,7 +470,6 @@ Renders the secure credit card iframe form. A field-shaped skeleton is shown imm
 **Required props:**
 
 - `renderToken` (`string`)
-- `onResult` (`(result: ConfirmationResult) => void`) — required. Called when the interactive confirmation attempt finishes (`succeeded`, `failed`, or `incomplete` with `reason`). Not settlement proof; verify via webhooks.
 
 **Optional props:**
 
@@ -484,6 +477,7 @@ Renders the secure credit card iframe form. A field-shaped skeleton is shown imm
 
 - `additionalFields` (`{ cardholderName: boolean }`) — set `additionalFields={{ cardholderName: true }}` to render the cardholder name field in the iframe (`false` by default)
 - `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.
+- `onResult` (`(result: ConfirmationResult) => void`) — **deprecated.** Prefer `await confirmPayment()` / `await confirmSetup()`. Still fired for existing hosts (`succeeded`, `failed`, or `incomplete` with `reason`). Not settlement proof; verify via webhooks.
 - `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.
 
@@ -495,7 +489,7 @@ Renders the secure bank account iframe form. A field-shaped skeleton is shown im
 
 When the charge meets the merchant’s ACH verification threshold, the SDK hides the routing/account iframe and renders a **Connect bank account** button in the parent page. The button follows the same outline/focus defaults as Amos UI (`--ring`, `--border`, `--radius`, `--input-height`, …): it inherits those CSS variables from the host page when present, and `appearance.themeVariables` overrides them the same way as the iframe. Clicking it asks the iframe to mint a Plaid Link token, then opens [Plaid Link](https://plaid.com/docs/link/web/). 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`, `onResult` — plus:
+**Required props:** same as `AmosCreditCardPaymentMethodForm` — `renderToken` — plus:
 
 - `amount` (`string`, major-currency decimal, e.g. `"50.00"`, defaults to `"0"`) — same format as Google Pay / Apple Pay. Compared to the threshold the iframe fetches (cents). Pass `"0"` (the default) on open-amount forms until the customer enters a charge — 0 is typically under the threshold, so Connect stays hidden. Pass a new `amount` when the customer changes the charge.
 - `intent` (`"payment" | "setup"`, defaults to `"payment"`) — `"setup"` always shows Connect / Plaid (no merchant ACH threshold lookup), unless the render token disables verification. Use this when saving a bank account for later charges.
@@ -508,7 +502,6 @@ Compare locally once the iframe posts `ACH_THRESHOLD`: Plaid when `requireVerifi
 <AmosBankAccountPaymentMethodForm
   renderToken={renderToken}
   amount="50.00" // defaults to "0" (manual form until the charge meets the threshold)
-  onResult={onResult}
 />
 ```
 
@@ -518,11 +511,10 @@ Setup (always Connect, no merchant lookup):
 <AmosBankAccountPaymentMethodForm
   renderToken={renderToken}
   intent="setup"
-  onResult={onResult}
 />
 ```
 
-`validateForm` / `confirmPaymentIntent` / `confirmSetupIntent` stay iframe-based. When Plaid succeeded, confirm sends `payment_method.plaid` (`public_token`, `account_id`) and does not require typed account numbers.
+`validateForm` / `confirmPayment` / `confirmSetup` stay iframe-based. When Plaid succeeded, confirm sends `payment_method.plaid` (`public_token`, `account_id`) and does not require typed account numbers.
 
 **CSP:** the parent page must allow Plaid’s script and frames, for example `script-src https://cdn.plaid.com` and `frame-src https://cdn.plaid.com https://*.plaid.com`. Amos never loads `PLAID_SECRET` / `PLAID_CLIENT_ID` in the SDK or embed iframe.
 
@@ -537,9 +529,7 @@ Renders the secure Google Pay iframe button (express checkout flow). A button-sh
 - `renderToken` (`string`)
 - `amount` (`string`) — major-currency decimal string shown in the wallet sheet (e.g. `"50.00"` for $50.00). The iframe converts this to cents in `paymentIntentCreateAttributes.amount`.
 - `merchantName` (`string`)
-- `onInitiatePaymentIntentRequest` (callback receiving `{ paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"]; customerCreateAttributes: components["schemas"]["CreateCustomerInput"] }`, returns `Promise<components["schemas"]["EmbedToken"]["token"]>` — the embed JWT string for confirmation)
-
-- `onResult` (`(result: ConfirmationResult) => void`) — required. Called when the interactive confirmation attempt finishes (`succeeded`, `failed`, or `incomplete` with `reason`). Not settlement proof; verify via webhooks.
+- `onConfirm` (callback receiving `{ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment }`. Create a payment intent, then `return confirmPayment(token)` — `Promise<ConfirmResult>`)
 
 **Optional props:**
 
@@ -595,14 +585,14 @@ Re-exports of the same advanced helpers exposed by `@amos.com/amos-js`. Most int
 
 ### Exported types
 
-`@amos.com/react-amos-js` re-exports everything from `@amos.com/amos-js`, including `ConfirmationResult`, `ConfirmationIncompleteReason`, `PaymentMethodFormValidityChangeEvent`, `CardBrand`, `PaymentMethodFormCardBrandChangeEvent`, `FormattedGooglePayPaymentData`, `Message`, `Appearance`, `ThemeVariable`, and the per-form `*Options` / `*Controller` types. For OpenAPI schema types (e.g. `PaymentIntent`, `CreatePaymentIntentInput`), import `components` from `@amos.com/node`.
+`@amos.com/react-amos-js` re-exports everything from `@amos.com/amos-js`, including `ConfirmResult`, `ConfirmationResult` (deprecated), `ConfirmationIncompleteReason`, `PaymentMethodFormValidityChangeEvent`, `CardBrand`, `PaymentMethodFormCardBrandChangeEvent`, `FormattedGooglePayPaymentData`, `Message`, `Appearance`, `ThemeVariable`, and the per-form `*Options` / `*Controller` types. For OpenAPI schema types (e.g. `PaymentIntent`, `CreatePaymentIntentInput`), import `components` from `@amos.com/node`.
 
 ## 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`, `confirmPaymentIntent`, `confirmSetupIntent`, or `resetForm`. The component forwards the ref to the inner iframe.
-- **`onResult` is not settlement proof**: `onResult` tells you when to stop waiting (e.g. dismiss a spinner). Verify payment or setup success on your backend via webhooks. On `status: "incomplete"`, unlock your UI — the customer can fix fields in the iframe and retry. Use `result.reason` (`"field_errors"` or `"validation_failed"`) to distinguish recoverable states.
-- **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 (`confirmPaymentIntent` vs `confirmSetupIntent`). Handle both payment and setup outcomes via `onResult`.
-- **Amount format**: for `AmosGooglePayButton`, `AmosApplePayButton`, and `AmosBankAccountPaymentMethodForm`, `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 `onInitiatePaymentIntentRequest`), `amount` is a number in cents (e.g. `5000`).
+- **`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`, or `resetForm`. 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; the Promise still resolves `{ status: "failed" }`. Deprecated `onResult` still receives `incomplete` with `reason` (`"field_errors"` or `"validation_failed"`).
+- **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`, `AmosApplePayButton`, and `AmosBankAccountPaymentMethodForm`, `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`).
 - **Plaid Link (ACH verification)**: load `cdn.plaid.com` from the **parent** document (see CSP on `AmosBankAccountPaymentMethodForm`). Merchants do not proxy Pay API; the bank iframe fetches the ACH threshold for payment intents and mints link tokens. Setup intents skip the merchant lookup and always require Plaid unless the render token disables verification. Confirm still goes through the bank iframe so Amos can attach `plaid` to the payment method.
 - **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 until payment completes, the popup closes, or the user clicks **Cancel payment**. 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

@@ -1,5 +1,5 @@
 /// <reference types="googlepay" />
-import { Appearance, ApplePayButtonElementProps, BillingAddressRequirement, ConfirmationResult, CreditCardAdditionalFields, GooglePayButtonElementProps } from '@amos.com/amos-js';
+import { Appearance, ApplePayButtonElementProps, BillingAddressRequirement, ConfirmationResult, ConfirmResult, CreditCardAdditionalFields, GooglePayButtonElementProps } from '@amos.com/amos-js';
 import { components } from '@amos.com/node';
 import { ComponentProps, Ref, RefObject } from 'react';
 export * from '@amos.com/amos-js';
@@ -20,9 +20,9 @@ export declare function validateForm({ iframeRef, }: {
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /payment_intents` call.
  */
-export declare function confirmPaymentIntent({ iframeRef, token, }: {
+export declare function confirmPayment({ iframeRef, token, }: {
     iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): void;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
 /**
  * Confirm a setup intent in the embedded iframe flow. Use this when
  * saving a payment method for future use.
@@ -30,9 +30,21 @@ export declare function confirmPaymentIntent({ iframeRef, token, }: {
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /setup_intents` call.
  */
+export declare function confirmSetup({ iframeRef, token, }: {
+    iframeRef: IframeRef;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
+/**
+ * @deprecated Use {@link confirmPayment}.
+ */
+export declare function confirmPaymentIntent({ iframeRef, token, }: {
+    iframeRef: IframeRef;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
+/**
+ * @deprecated Use {@link confirmSetup}.
+ */
 export declare function confirmSetupIntent({ iframeRef, token, }: {
     iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): void;
+} & Pick<components["schemas"]["EmbedToken"], "token">): Promise<ConfirmResult>;
 /**
  * Clear all field values and API errors in the embedded card/bank iframe
  * form. Call after `onResult` when the customer wants to try again.
@@ -45,7 +57,10 @@ type IframePassthroughProps = Omit<ComponentProps<"iframe">, "src" | "title" | "
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
-    onResult: (result: ConfirmationResult) => void;
+    /**
+     * @deprecated Prefer `await confirmPayment()` / `await confirmSetup()`.
+     */
+    onResult?: (result: ConfirmationResult) => void;
     /**
      * Called when form validity changes. `isValid` is true when all
      * required fields are present and valid. Does not include PCI data.
@@ -68,7 +83,10 @@ export declare function AmosCreditCardPaymentMethodForm({ ref, renderToken, appe
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
     renderToken: string;
     appearance?: Appearance;
-    onResult: (result: ConfirmationResult) => void;
+    /**
+     * @deprecated Prefer `await confirmPayment()` / `await confirmSetup()`.
+     */
+    onResult?: (result: ConfirmationResult) => void;
     /**
      * Called when form validity changes. `isValid` is true when all
      * required fields are present and valid, or when Plaid Link has
@@ -126,18 +144,22 @@ type AmosGooglePayButtonProps = {
     buttonProps?: GooglePayButtonElementProps;
     /** Props applied to the host-page `<iframe>` element. */
     iframeProps?: IframePassthroughProps;
-    onInitiatePaymentIntentRequest: ({ paymentIntentCreateAttributes, customerCreateAttributes, }: {
+    /**
+     * Called when the buyer authorizes in the Google Pay sheet. Create a
+     * payment intent on your server, then `await confirmPayment(token)`.
+     */
+    onConfirm: ({ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment, }: {
         paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-    }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
-    onResult: (result: ConfirmationResult) => void;
+        confirmPayment: (token: string) => Promise<ConfirmResult>;
+    }) => Promise<ConfirmResult>;
 };
 /**
  * Renders the secure Google Pay iframe button. A button-shaped
  * skeleton is painted in the parent document on first render (including
  * SSR) so the slot height is reserved before the iframe loads.
  */
-export declare function AmosGooglePayButton({ ref, renderToken, amount, merchantName, height, buttonProps, iframeProps, onInitiatePaymentIntentRequest, onResult, }: AmosGooglePayButtonProps): import("react").JSX.Element;
+export declare function AmosGooglePayButton({ ref, renderToken, amount, merchantName, height, buttonProps, iframeProps, onConfirm, }: AmosGooglePayButtonProps): import("react").JSX.Element;
 type AmosApplePayButtonProps = {
     ref?: ForwardedIframeRef;
     renderToken: string;
@@ -162,15 +184,19 @@ type AmosApplePayButtonProps = {
     buttonProps?: ApplePayButtonElementProps;
     /** Props applied to the host-page `<iframe>` element. */
     iframeProps?: IframePassthroughProps;
-    onInitiatePaymentIntentRequest: ({ paymentIntentCreateAttributes, customerCreateAttributes, }: {
+    /**
+     * Called when the buyer authorizes in the Apple Pay sheet. Create a
+     * payment intent on your server, then `await confirmPayment(token)`.
+     */
+    onConfirm: ({ paymentIntentCreateAttributes, customerCreateAttributes, confirmPayment, }: {
         paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
         customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-    }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
-    onResult: (result: ConfirmationResult) => void;
+        confirmPayment: (token: string) => Promise<ConfirmResult>;
+    }) => Promise<ConfirmResult>;
 };
 /**
  * Renders the secure Apple Pay iframe button. A button-shaped
  * skeleton is painted in the parent document on first render (including
  * SSR) so the slot height is reserved before the iframe loads.
  */
-export declare function AmosApplePayButton({ ref, renderToken, amount, merchantName, height, buttonProps, iframeProps, onInitiatePaymentIntentRequest, onResult, }: AmosApplePayButtonProps): import("react").JSX.Element;
+export declare function AmosApplePayButton({ ref, renderToken, amount, merchantName, height, buttonProps, iframeProps, onConfirm, }: AmosApplePayButtonProps): import("react").JSX.Element;

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}){(0,e.confirmPaymentIntent)({iframe:r(t),token:n})}function o({iframeRef:t,token:n}){(0,e.confirmSetupIntent)({iframe:r(t),token:n})}function s({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function c(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function l(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 u({containerRef:e,iframeRef:n,mount:r,options:i,remountDeps:a,iframePassthrough:o,updateDeps:s}){let u=(0,t.useRef)(null);(0,t.useLayoutEffect)(()=>{let t=e.current;if(!t)return;let a=r(t,i);return u.current=a,c(n,a.iframe),l(a.iframe,o),()=>{a.destroy(),u.current=null,c(n,null)}},[...a]),(0,t.useEffect)(()=>{u.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=u.current?.iframe;e&&l(e,o)})}var d=`oklch(0.97 0 0)`;function f({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:d,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 p({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,onCardBrandChanged:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:d=`country`,style:f,...p}){let m=(0,t.useRef)(null);return u({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:d,onResult:o,onValidityChange:s,onCardBrandChanged:c},remountDeps:[i,l.cardholderName,d],iframePassthrough:{style:f,...p},updateDeps:[a,l,d,o,s,c]}),(0,n.jsx)(`div`,{ref:m})}function m({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,billingAddressRequirement:c=`country`,amount:l=`0`,intent:d=`payment`,style:f,...p}){let m=(0,t.useRef)(null);return u({containerRef:m,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,amount:l,intent:d,onResult:o,onValidityChange:s},remountDeps:[i,c,d],iframePassthrough:{style:f,...p},updateDeps:[a,c,l,d,o,s]}),(0,n.jsx)(`div`,{ref:m})}function h({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosGooglePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}function g({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onInitiatePaymentIntentRequest:d,onResult:p}){let m=(0,t.useRef)(null),h=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return u({containerRef:m,iframeRef:r,mount:e.mountAmosApplePayButton,options:{renderToken:i,amount:a,merchantName:o,height:s,buttonProps:c,onInitiatePaymentIntentRequest:d,onResult:p},remountDeps:[i],iframePassthrough:l??{},updateDeps:[a,o,s,c,d,p]}),(0,n.jsx)(f,{height:s,borderRadius:h,containerRef:m})}exports.AmosApplePayButton=g,exports.AmosBankAccountPaymentMethodForm=m,exports.AmosCreditCardPaymentMethodForm=p,exports.AmosGooglePayButton=h,exports.confirmPaymentIntent=a,exports.confirmSetupIntent=o,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}){return(0,e.confirmPayment)({iframe:r(t),token:n})}function o({iframeRef:t,token:n}){return(0,e.confirmSetup)({iframe:r(t),token:n})}function s({iframeRef:t,token:n}){return(0,e.confirmPaymentIntent)({iframe:r(t),token:n})}function c({iframeRef:t,token:n}){return(0,e.confirmSetupIntent)({iframe:r(t),token:n})}function l({iframeRef:t}){(0,e.resetForm)({iframe:r(t)})}function u(e,t){typeof e==`function`?e(t):e&&(e.current=t)}function d(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 f({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,u(n,a.iframe),d(a.iframe,o),()=>{a.destroy(),c.current=null,u(n,null)}},[...a]),(0,t.useEffect)(()=>{c.current?.update(i)},[...s]),(0,t.useEffect)(()=>{let e=c.current?.iframe;e&&d(e,o)})}var p=`oklch(0.97 0 0)`;function m({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:p,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 h({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,onCardBrandChanged:c,additionalFields:l={cardholderName:!1},billingAddressRequirement:u=`country`,style:d,...p}){let m=(0,t.useRef)(null);return f({containerRef:m,iframeRef:r,mount:e.mountAmosCreditCardPaymentMethodForm,options:{renderToken:i,appearance:a,additionalFields:l,billingAddressRequirement:u,onResult:o,onValidityChange:s,onCardBrandChanged:c},remountDeps:[i,l.cardholderName,u],iframePassthrough:{style:d,...p},updateDeps:[a,l,u,o,s,c]}),(0,n.jsx)(`div`,{ref:m})}function g({ref:r,renderToken:i,appearance:a,onResult:o,onValidityChange:s,billingAddressRequirement:c=`country`,amount:l=`0`,intent:u=`payment`,style:d,...p}){let m=(0,t.useRef)(null);return f({containerRef:m,iframeRef:r,mount:e.mountAmosBankAccountPaymentMethodForm,options:{renderToken:i,appearance:a,billingAddressRequirement:c,amount:l,intent:u,onResult:o,onValidityChange:s},remountDeps:[i,c,u],iframePassthrough:{style:d,...p},updateDeps:[a,c,l,u,o,s]}),(0,n.jsx)(`div`,{ref:m})}function _({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let d=(0,t.useRef)(null),p=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return f({containerRef:d,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)(m,{height:s,borderRadius:p,containerRef:d})}function v({ref:r,renderToken:i,amount:a,merchantName:o,height:s=`48px`,buttonProps:c,iframeProps:l,onConfirm:u}){let d=(0,t.useRef)(null),p=(0,e.resolveWalletButtonSkeletonBorderRadius)({iframeStyle:l?.style,buttonProps:c});return f({containerRef:d,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)(m,{height:s,borderRadius:p,containerRef:d})}exports.AmosApplePayButton=v,exports.AmosBankAccountPaymentMethodForm=g,exports.AmosCreditCardPaymentMethodForm=h,exports.AmosGooglePayButton=_,exports.confirmPayment=a,exports.confirmPaymentIntent=s,exports.confirmSetup=o,exports.confirmSetupIntent=c,exports.resetForm=l,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

@@ -1,57 +1,69 @@
-import { confirmPaymentIntent as e, confirmSetupIntent as t, ensureSkeletonStyles as n, mountAmosApplePayButton as r, mountAmosBankAccountPaymentMethodForm as i, mountAmosCreditCardPaymentMethodForm as a, mountAmosGooglePayButton as o, resetForm as s, resolveWalletButtonSkeletonBorderRadius as c, validateForm as l } from "@amos.com/amos-js";
-import { useEffect as u, useLayoutEffect as d, useRef as f } from "react";
-import { jsx as p, jsxs as m } from "react/jsx-runtime";
+import { confirmPayment as e, confirmPaymentIntent as t, confirmSetup as n, confirmSetupIntent as r, ensureSkeletonStyles as i, mountAmosApplePayButton as a, mountAmosBankAccountPaymentMethodForm as o, mountAmosCreditCardPaymentMethodForm as s, mountAmosGooglePayButton as c, resetForm as l, resolveWalletButtonSkeletonBorderRadius as u, validateForm as d } from "@amos.com/amos-js";
+import { useEffect as f, useLayoutEffect as p, useRef as m } from "react";
+import { jsx as h, jsxs as g } from "react/jsx-runtime";
 export * from "@amos.com/amos-js";
 //#region src/index.tsx
-function h(e) {
+function _(e) {
 	return e ? e.current ?? null : null;
 }
-function g({ iframeRef: e }) {
-	return l({ iframe: h(e) });
+function v({ iframeRef: e }) {
+	return d({ iframe: _(e) });
 }
-function _({ iframeRef: t, token: n }) {
-	e({
-		iframe: h(t),
+function y({ iframeRef: t, token: n }) {
+	return e({
+		iframe: _(t),
 		token: n
 	});
 }
-function v({ iframeRef: e, token: n }) {
-	t({
-		iframe: h(e),
+function b({ iframeRef: e, token: t }) {
+	return n({
+		iframe: _(e),
+		token: t
+	});
+}
+function x({ iframeRef: e, token: n }) {
+	return t({
+		iframe: _(e),
 		token: n
 	});
 }
-function y({ iframeRef: e }) {
-	s({ iframe: h(e) });
+function S({ iframeRef: e, token: t }) {
+	return r({
+		iframe: _(e),
+		token: t
+	});
+}
+function C({ iframeRef: e }) {
+	l({ iframe: _(e) });
 }
-function b(e, t) {
+function w(e, t) {
 	typeof e == "function" ? e(t) : e && (e.current = t);
 }
-function x(e, { style: t, className: n, id: r, ...i }) {
+function T(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 S({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
-	let s = f(null);
-	d(() => {
+function E({ containerRef: e, iframeRef: t, mount: n, options: r, remountDeps: i, iframePassthrough: a, updateDeps: o }) {
+	let s = m(null);
+	p(() => {
 		let i = e.current;
 		if (!i) return;
 		let o = n(i, r);
-		return s.current = o, b(t, o.iframe), x(o.iframe, a), () => {
-			o.destroy(), s.current = null, b(t, null);
+		return s.current = o, w(t, o.iframe), T(o.iframe, a), () => {
+			o.destroy(), s.current = null, w(t, null);
 		};
-	}, [...i]), u(() => {
+	}, [...i]), f(() => {
 		s.current?.update(r);
-	}, [...o]), u(() => {
+	}, [...o]), f(() => {
 		let e = s.current?.iframe;
-		e && x(e, a);
+		e && T(e, a);
 	});
 }
-var C = "oklch(0.97 0 0)";
-function w({ height: e, borderRadius: t, containerRef: r }) {
-	return d(() => {
-		n();
-	}, []), /* @__PURE__ */ m("div", {
+var D = "oklch(0.97 0 0)";
+function O({ height: e, borderRadius: t, containerRef: n }) {
+	return p(() => {
+		i();
+	}, []), /* @__PURE__ */ g("div", {
 		style: {
 			boxSizing: "border-box",
 			position: "relative",
@@ -60,20 +72,20 @@ function w({ height: e, borderRadius: t, containerRef: r }) {
 			minHeight: e,
 			overflow: "hidden"
 		},
-		children: [/* @__PURE__ */ p("div", {
+		children: [/* @__PURE__ */ h("div", {
 			className: "amos-js-form-skeleton-input amos-js-wallet-skeleton",
 			style: {
 				position: "absolute",
 				inset: 0,
 				height: e,
 				borderRadius: t,
-				background: C,
+				background: D,
 				pointerEvents: "none",
 				zIndex: 0
 			},
 			"aria-hidden": !0
-		}), /* @__PURE__ */ p("div", {
-			ref: r,
+		}), /* @__PURE__ */ h("div", {
+			ref: n,
 			style: {
 				position: "absolute",
 				inset: 0,
@@ -84,24 +96,24 @@ function w({ height: e, borderRadius: t, containerRef: r }) {
 		})]
 	});
 }
-function T({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: i, onCardBrandChanged: o, additionalFields: s = { cardholderName: !1 }, billingAddressRequirement: c = "country", style: l, ...u }) {
-	let d = f(null);
-	return S({
+function k({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: i, onCardBrandChanged: a, additionalFields: o = { cardholderName: !1 }, billingAddressRequirement: c = "country", style: l, ...u }) {
+	let d = m(null);
+	return E({
 		containerRef: d,
 		iframeRef: e,
-		mount: a,
+		mount: s,
 		options: {
 			renderToken: t,
 			appearance: n,
-			additionalFields: s,
+			additionalFields: o,
 			billingAddressRequirement: c,
 			onResult: r,
 			onValidityChange: i,
-			onCardBrandChanged: o
+			onCardBrandChanged: a
 		},
 		remountDeps: [
 			t,
-			s.cardholderName,
+			o.cardholderName,
 			c
 		],
 		iframePassthrough: {
@@ -110,32 +122,32 @@ function T({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChang
 		},
 		updateDeps: [
 			n,
-			s,
+			o,
 			c,
 			r,
 			i,
-			o
+			a
 		]
-	}), /* @__PURE__ */ p("div", { ref: d });
+	}), /* @__PURE__ */ h("div", { ref: d });
 }
-function E({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: a, billingAddressRequirement: o = "country", amount: s = "0", intent: c = "payment", style: l, ...u }) {
-	let d = f(null);
-	return S({
+function A({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChange: i, billingAddressRequirement: a = "country", amount: s = "0", intent: c = "payment", style: l, ...u }) {
+	let d = m(null);
+	return E({
 		containerRef: d,
 		iframeRef: e,
-		mount: i,
+		mount: o,
 		options: {
 			renderToken: t,
 			appearance: n,
-			billingAddressRequirement: o,
+			billingAddressRequirement: a,
 			amount: s,
 			intent: c,
 			onResult: r,
-			onValidityChange: a
+			onValidityChange: i
 		},
 		remountDeps: [
 			t,
-			o,
+			a,
 			c
 		],
 		iframePassthrough: {
@@ -144,81 +156,77 @@ function E({ ref: e, renderToken: t, appearance: n, onResult: r, onValidityChang
 		},
 		updateDeps: [
 			n,
-			o,
+			a,
 			s,
 			c,
 			r,
-			a
+			i
 		]
-	}), /* @__PURE__ */ p("div", { ref: d });
+	}), /* @__PURE__ */ h("div", { ref: d });
 }
-function D({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: s, onInitiatePaymentIntentRequest: l, onResult: u }) {
-	let d = f(null), m = c({
-		iframeStyle: s?.style,
+function j({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: a, iframeProps: o, onConfirm: s }) {
+	let l = m(null), d = u({
+		iframeStyle: o?.style,
 		buttonProps: a
 	});
-	return S({
-		containerRef: d,
+	return E({
+		containerRef: l,
 		iframeRef: e,
-		mount: o,
+		mount: c,
 		options: {
 			renderToken: t,
 			amount: n,
 			merchantName: r,
 			height: i,
 			buttonProps: a,
-			onInitiatePaymentIntentRequest: l,
-			onResult: u
+			onConfirm: s
 		},
 		remountDeps: [t],
-		iframePassthrough: s ?? {},
+		iframePassthrough: o ?? {},
 		updateDeps: [
 			n,
 			r,
 			i,
 			a,
-			l,
-			u
+			s
 		]
-	}), /* @__PURE__ */ p(w, {
+	}), /* @__PURE__ */ h(O, {
 		height: i,
-		borderRadius: m,
-		containerRef: d
+		borderRadius: d,
+		containerRef: l
 	});
 }
-function O({ ref: e, renderToken: t, amount: n, merchantName: i, height: a = "48px", buttonProps: o, iframeProps: s, onInitiatePaymentIntentRequest: l, onResult: u }) {
-	let d = f(null), m = c({
+function M({ ref: e, renderToken: t, amount: n, merchantName: r, height: i = "48px", buttonProps: o, iframeProps: s, onConfirm: c }) {
+	let l = m(null), d = u({
 		iframeStyle: s?.style,
 		buttonProps: o
 	});
-	return S({
-		containerRef: d,
+	return E({
+		containerRef: l,
 		iframeRef: e,
-		mount: r,
+		mount: a,
 		options: {
 			renderToken: t,
 			amount: n,
-			merchantName: i,
-			height: a,
+			merchantName: r,
+			height: i,
 			buttonProps: o,
-			onInitiatePaymentIntentRequest: l,
-			onResult: u
+			onConfirm: c
 		},
 		remountDeps: [t],
 		iframePassthrough: s ?? {},
 		updateDeps: [
 			n,
+			r,
 			i,
-			a,
 			o,
-			l,
-			u
+			c
 		]
-	}), /* @__PURE__ */ p(w, {
-		height: a,
-		borderRadius: m,
-		containerRef: d
+	}), /* @__PURE__ */ h(O, {
+		height: i,
+		borderRadius: d,
+		containerRef: l
 	});
 }
 //#endregion
-export { O as AmosApplePayButton, E as AmosBankAccountPaymentMethodForm, T as AmosCreditCardPaymentMethodForm, D as AmosGooglePayButton, _ as confirmPaymentIntent, v as confirmSetupIntent, y as resetForm, g as validateForm };
+export { M as AmosApplePayButton, A as AmosBankAccountPaymentMethodForm, k as AmosCreditCardPaymentMethodForm, j as AmosGooglePayButton, y as confirmPayment, x as confirmPaymentIntent, b as confirmSetup, S as confirmSetupIntent, C as resetForm, v as validateForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amos.com/react-amos-js",
-  "version": "0.10.6",
+  "version": "0.11.1",
   "main": "dist/index.js",
   "repository": {
     "type": "git",
@@ -37,22 +37,22 @@
   "license": "MIT",
   "description": "React SDK for embedding Amos payment methods via iframes. Wraps @amos.com/amos-js.",
   "devDependencies": {
-    "@amos.com/node": "0.1.50",
-    "@biomejs/biome": "2.5.7",
+    "@amos.com/node": "0.1.53",
+    "@biomejs/biome": "2.5.10",
     "@changesets/cli": "2.31.1",
-    "@types/node": "26.1.2",
+    "@types/node": "26.3.0",
     "@types/react": "19.2.18",
     "@typescript/typescript6": "6.0.2",
     "typescript": "7.0.2",
-    "vite": "8.2.0",
+    "vite": "8.2.2",
     "vite-plugin-dts": "5.0.3"
   },
   "dependencies": {
-    "@amos.com/amos-js": "0.10.6",
-    "@types/googlepay": "0.7.11"
+    "@amos.com/amos-js": "0.11.2",
+    "@types/googlepay": "0.7.12"
   },
   "peerDependencies": {
     "react": "^17 || ^18 || ^19",
-    "@amos.com/node": ">=0.1.50"
+    "@amos.com/node": ">=0.1.53"
   }
 }

package/src/index.tsx

@@ -3,12 +3,15 @@
 import {
   type Appearance,
   type ApplePayButtonElementProps,
+  confirmPayment as amosConfirmPayment,
   confirmPaymentIntent as amosConfirmPaymentIntent,
+  confirmSetup as amosConfirmSetup,
   confirmSetupIntent as amosConfirmSetupIntent,
   resetForm as amosResetForm,
   validateForm as amosValidateForm,
   type BillingAddressRequirement,
   type ConfirmationResult,
+  type ConfirmResult,
   type CreditCardAdditionalFields,
   ensureSkeletonStyles,
   type GooglePayButtonElementProps,
@@ -60,13 +63,16 @@ export function validateForm({
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /payment_intents` call.
  */
-export function confirmPaymentIntent({
+export function confirmPayment({
   iframeRef,
   token,
 }: {
   iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): void {
-  amosConfirmPaymentIntent({ iframe: resolveIframe(iframeRef), token });
+} & Pick<
+  components["schemas"]["EmbedToken"],
+  "token"
+>): Promise<ConfirmResult> {
+  return amosConfirmPayment({ iframe: resolveIframe(iframeRef), token });
 }
 
 /**
@@ -76,13 +82,46 @@ export function confirmPaymentIntent({
  * Pass the embed JWT (`token`) returned by your server's
  * `POST /setup_intents` call.
  */
+export function confirmSetup({
+  iframeRef,
+  token,
+}: {
+  iframeRef: IframeRef;
+} & Pick<
+  components["schemas"]["EmbedToken"],
+  "token"
+>): Promise<ConfirmResult> {
+  return amosConfirmSetup({ iframe: resolveIframe(iframeRef), token });
+}
+
+/**
+ * @deprecated Use {@link confirmPayment}.
+ */
+export function confirmPaymentIntent({
+  iframeRef,
+  token,
+}: {
+  iframeRef: IframeRef;
+} & Pick<
+  components["schemas"]["EmbedToken"],
+  "token"
+>): Promise<ConfirmResult> {
+  return amosConfirmPaymentIntent({ iframe: resolveIframe(iframeRef), token });
+}
+
+/**
+ * @deprecated Use {@link confirmSetup}.
+ */
 export function confirmSetupIntent({
   iframeRef,
   token,
 }: {
   iframeRef: IframeRef;
-} & Pick<components["schemas"]["EmbedToken"], "token">): void {
-  amosConfirmSetupIntent({ iframe: resolveIframe(iframeRef), token });
+} & Pick<
+  components["schemas"]["EmbedToken"],
+  "token"
+>): Promise<ConfirmResult> {
+  return amosConfirmSetupIntent({ iframe: resolveIframe(iframeRef), token });
 }
 
 /**
@@ -247,7 +286,10 @@ function WalletButtonSlot({
 type AmosCreditCardPaymentMethodFormProps = IframePassthroughProps & {
   renderToken: string;
   appearance?: Appearance;
-  onResult: (result: ConfirmationResult) => void;
+  /**
+   * @deprecated Prefer `await confirmPayment()` / `await confirmSetup()`.
+   */
+  onResult?: (result: ConfirmationResult) => void;
   /**
    * Called when form validity changes. `isValid` is true when all
    * required fields are present and valid. Does not include PCI data.
@@ -321,7 +363,10 @@ export function AmosCreditCardPaymentMethodForm({
 type AmosBankAccountPaymentMethodFormProps = IframePassthroughProps & {
   renderToken: string;
   appearance?: Appearance;
-  onResult: (result: ConfirmationResult) => void;
+  /**
+   * @deprecated Prefer `await confirmPayment()` / `await confirmSetup()`.
+   */
+  onResult?: (result: ConfirmationResult) => void;
   /**
    * Called when form validity changes. `isValid` is true when all
    * required fields are present and valid, or when Plaid Link has
@@ -419,14 +464,19 @@ type AmosGooglePayButtonProps = {
   buttonProps?: GooglePayButtonElementProps;
   /** Props applied to the host-page `<iframe>` element. */
   iframeProps?: IframePassthroughProps;
-  onInitiatePaymentIntentRequest: ({
+  /**
+   * Called when the buyer authorizes in the Google Pay sheet. Create a
+   * payment intent on your server, then `await confirmPayment(token)`.
+   */
+  onConfirm: ({
     paymentIntentCreateAttributes,
     customerCreateAttributes,
+    confirmPayment,
   }: {
     paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-  }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
-  onResult: (result: ConfirmationResult) => void;
+    confirmPayment: (token: string) => Promise<ConfirmResult>;
+  }) => Promise<ConfirmResult>;
 };
 
 /**
@@ -442,8 +492,7 @@ export function AmosGooglePayButton({
   height = "48px",
   buttonProps,
   iframeProps,
-  onInitiatePaymentIntentRequest,
-  onResult,
+  onConfirm,
 }: AmosGooglePayButtonProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const borderRadius = resolveWalletButtonSkeletonBorderRadius({
@@ -461,19 +510,11 @@ export function AmosGooglePayButton({
       merchantName,
       height,
       buttonProps,
-      onInitiatePaymentIntentRequest,
-      onResult,
+      onConfirm,
     },
     remountDeps: [renderToken],
     iframePassthrough: iframeProps ?? {},
-    updateDeps: [
-      amount,
-      merchantName,
-      height,
-      buttonProps,
-      onInitiatePaymentIntentRequest,
-      onResult,
-    ],
+    updateDeps: [amount, merchantName, height, buttonProps, onConfirm],
   });
 
   return (
@@ -509,14 +550,19 @@ type AmosApplePayButtonProps = {
   buttonProps?: ApplePayButtonElementProps;
   /** Props applied to the host-page `<iframe>` element. */
   iframeProps?: IframePassthroughProps;
-  onInitiatePaymentIntentRequest: ({
+  /**
+   * Called when the buyer authorizes in the Apple Pay sheet. Create a
+   * payment intent on your server, then `await confirmPayment(token)`.
+   */
+  onConfirm: ({
     paymentIntentCreateAttributes,
     customerCreateAttributes,
+    confirmPayment,
   }: {
     paymentIntentCreateAttributes: components["schemas"]["CreatePaymentIntentInput"];
     customerCreateAttributes: components["schemas"]["CreateCustomerInput"];
-  }) => Promise<components["schemas"]["EmbedToken"]["token"]>;
-  onResult: (result: ConfirmationResult) => void;
+    confirmPayment: (token: string) => Promise<ConfirmResult>;
+  }) => Promise<ConfirmResult>;
 };
 
 /**
@@ -532,8 +578,7 @@ export function AmosApplePayButton({
   height = "48px",
   buttonProps,
   iframeProps,
-  onInitiatePaymentIntentRequest,
-  onResult,
+  onConfirm,
 }: AmosApplePayButtonProps) {
   const containerRef = useRef<HTMLDivElement | null>(null);
   const borderRadius = resolveWalletButtonSkeletonBorderRadius({
@@ -551,19 +596,11 @@ export function AmosApplePayButton({
       merchantName,
       height,
       buttonProps,
-      onInitiatePaymentIntentRequest,
-      onResult,
+      onConfirm,
     },
     remountDeps: [renderToken],
     iframePassthrough: iframeProps ?? {},
-    updateDeps: [
-      amount,
-      merchantName,
-      height,
-      buttonProps,
-      onInitiatePaymentIntentRequest,
-      onResult,
-    ],
+    updateDeps: [amount, merchantName, height, buttonProps, onConfirm],
   });
 
   return (