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

# Browser SDK (@ionicfi/js)

> Thin loader for the evergreen browser runtime; mounts embedded checkout.

The browser package is a thin loader: it injects the runtime from
`https://js.ionicfi.com/v1/ionic.js` at mount time and never bundles
card-handling code into your app, so security updates reach every integration
with no redeploy on your side. See the
[embedded checkout guide](/guides/embedded-checkout) for the full
integration walkthrough including domain registration and CSP.

## Install

```bash theme={null}
npm install @ionicfi/js
```

## Embedded checkout

Create a checkout session on your server with `ui_mode: "embedded"`, return it
to your frontend, and mount it:

```ts theme={null}
import { loadIonicCheckout } from "@ionicfi/js";

const IonicCheckout = await loadIonicCheckout();

const checkout = IonicCheckout.mountSession("#checkout", {
  session,
  onComplete: ({ sessionId }) => {
    window.location.href = `/success?session_id=${encodeURIComponent(sessionId)}`;
  },
  onError: (error) => {
    console.error(error.message);
  },
});

// When the host view unmounts:
checkout.destroy();
```

The SDK reads `id`, `client_secret`, and `embed_url` from the session your
backend returns. It keeps the client secret out of the iframe URL and sends it
only after the checkout document reports that it is ready.

### Apple Pay

Pass `applePay: true` to render an Apple Pay button above the card form:

```ts theme={null}
const checkout = IonicCheckout.mountSession("#checkout", {
  session,
  applePay: true,
});
```

The button renders in your page rather than inside the iframe, because Apple
validates the top-level page's domain when the payment sheet opens. It stays
hidden, with no layout impact, until the session supports Apple Pay on the
current device.

Apple Pay requires your domain to be registered with Ionic, HTTPS on the page
and every ancestor frame, and Safari 17 or later for cross-origin iframe
checkouts. If your page sets a Content-Security-Policy, see the integration
guide for the entries to allow.

## Script tag

The SDK is also available without a bundler:

```html theme={null}
<script src="https://js.ionicfi.com/v1/ionic.js"></script>
<script>
  const checkout = window.Ionic.IonicCheckout.mountSession("#checkout", {
    session,
  });
</script>
```

## Versioning

`0.x` releases may introduce breaking changes without a major version bump.