> ## Documentation Index
> Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# client.setupApplePay()

> Render the Apple Pay frame and start a transaction.

Render the Apple Pay frame into your UI and initiate a transaction with a quote signature. The quote must have `executable: true`.

```ts Setup Apple Pay focus={5-30} theme={null}
import { createClient, type ApplePayEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const applePayResult = await client.setupApplePay({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#applePayContainer"),
  onEvent: (event: ApplePayEvent) => {
    switch (event.kind) {
      case "ready":
        break;
      case "complete":
        console.log(event.payload.transaction);
        break;
      case "quoteExpired":
        // Fetch a new quote, then update the frame:
        // event.payload.setQuote(newQuote.signature);
        break;
      case "error":
        console.error(event.payload.kind, event.payload.message);
        break;
      case "unsupported":
        // Apple Pay isn't available in this environment — fall back to another method.
        break;
    }
  },
});

if (!applePayResult.ok) {
  // Handle error
  console.error(applePayResult.error.kind, applePayResult.error.message);
  return;
}

const applePay = applePayResult.value;
```

***

## Parameters

| Property    | Type                             | Required | Description                                                                              |
| ----------- | -------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `quote`     | `string`                         | ✅        | The quote `signature` returned from [`getQuote`](/platform/sdk-reference/web/get-quote). |
| `container` | `HTMLElement`                    | ✅        | A DOM element to render the Apple Pay frame into.                                        |
| `onEvent`   | `(event: ApplePayEvent) => void` |          | Callback invoked for Apple Pay flow events. See [`ApplePayEvent`](#applepayevent).       |

This method does not require a separate auth token. The client uses stored credentials from an active connection.

### `ApplePayEvent`

`onEvent` receives events as the Apple Pay flow progresses. Use `event.kind` to decide how to handle each event.

| kind             | Payload                                                      | When you receive it                                                                                                                            |
| ---------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `"ready"`        | —                                                            | The Apple Pay UI is rendered and ready to be shown.                                                                                            |
| `"complete"`     | `{ transaction:` [`FrameTransaction`](#frametransaction) `}` | The Apple Pay flow finished. Inspect the `FrameTransaction` for the outcome.                                                                   |
| `"challenge"`    | `{ kind: "frame"; url: string }`                             | Verification required. Render the challenge frame at the provided URL using [`setupChallenge()`](/platform/sdk-reference/web/setup-challenge). |
| `"quoteExpired"` | `{ setQuote: (signature: string) => void }`                  | The quote signature expired. Fetch a new quote and call `payload.setQuote(...)`.                                                               |
| `"error"`        | [`ApplePayEventError`](#applepayeventerror)                  | The flow encountered an error.                                                                                                                 |
| `"unsupported"`  | —                                                            | Apple Pay isn't available in the user's current environment.                                                                                   |

#### `FrameTransaction`

The transaction object returned on `"complete"`. `FrameTransaction` is a discriminated union — the failure variant carries `failureReason`, the non-failure variant always carries `id`.

| Field           | Type     | Required | Description                                                                                                                   |
| --------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `status`        | `string` | ✅        | The transaction status. On the failure variant, `"failed"`.                                                                   |
| `id`            | `string` |          | Required on the non-failure variant; optional when `status` is `"failed"` (a transaction may not exist yet on early failure). |
| `failureReason` | `string` |          | Present only on the failure variant (`status === "failed"`).                                                                  |

#### `ApplePayEventError`

| Field     | Type                                                                                                                         | Required | Description                 |
| --------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------- |
| `kind`    | `"configurationError"` \| `"invalidQuote"` \| `"quoteExpired"` \| `"oneTapApplePaySecondFactorRequired"` \| `"genericError"` | ✅        | The error category.         |
| `message` | `string`                                                                                                                     | ✅        | Developer-friendly details. |

`"oneTapApplePaySecondFactorRequired"` is emitted on the 1TAP Apple Pay flow when MoonPay needs a second authentication factor — typically because the device is new or the customer hasn't completed a recent challenge. Hand off to the full connect flow with [`client.connect()`](/platform/sdk-reference/web/connect), then retry.

Apple Pay being unavailable in the environment (for example, the browser doesn't support it) is signalled separately through the `"unsupported"` event, not as an error.

## Result

`client.setupApplePay()` returns a `Result<ApplePayFrame, SetupApplePayError>`.

### Result envelope

`Result<ApplePayFrame, SetupApplePayError>`

| Field   | Type                                        | Required | Description                      |
| ------- | ------------------------------------------- | -------- | -------------------------------- |
| `ok`    | `boolean`                                   | ✅        | Whether the operation succeeded. |
| `value` | [`ApplePayFrame`](#applepayframe)           |          | Present when `ok` is `true`.     |
| `error` | [`SetupApplePayError`](#setupapplepayerror) |          | Present when `ok` is `false`.    |

### `ApplePayFrame`

| Field      | Type                          | Required | Description                                                                                           |
| ---------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `setQuote` | `(signature: string) => void` | ✅        | Updates the quote signature used by the frame. Use this in response to `quoteExpired`.                |
| `dispose`  | `() => void`                  | ✅        | Unmounts the frame. After you call this, no further events are dispatched to your `onEvent` callback. |

### `SetupApplePayError`

| Field     | Type                                       | Required | Description                 |
| --------- | ------------------------------------------ | -------- | --------------------------- |
| `kind`    | `"configurationError"` \| `"genericError"` | ✅        | The error category.         |
| `message` | `string`                                   | ✅        | Developer-friendly details. |

Setup errors cover frame initialization only (for example, a handshake
timeout). Quote problems, second-factor requirements, and Apple Pay
availability are reported through `onEvent` after setup succeeds — as the
`"error"`, `"quoteExpired"`, and `"unsupported"` events respectively.

<Accordion title="TS Definitions">
  ```ts types.ts theme={null}
  type ApplePayFrame = {
    setQuote: (signature: string) => void;
    dispose: () => void;
  };

  type FrameTransaction =
    | { id: string; status: string }
    | { id?: string; status: "failed"; failureReason: string };

  type ApplePayEvent =
    | { kind: "ready" }
    | {
        kind: "complete";
        payload: { transaction: FrameTransaction };
      }
    | {
        kind: "challenge";
        payload: {
          kind: "frame";
          url: string;
        };
      }
    | {
        kind: "quoteExpired";
        payload: { setQuote: (signature: string) => void };
      }
    | { kind: "error"; payload: ApplePayEventError }
    | { kind: "unsupported" };

  type ApplePayEventError = {
    kind:
      | "configurationError"
      | "invalidQuote"
      | "quoteExpired"
      | "oneTapApplePaySecondFactorRequired"
      | "genericError";
    message: string;
  };

  type SetupApplePayError = {
    kind: "configurationError" | "genericError";
    message: string;
  };
  ```
</Accordion>