Browser SDK (@ionicfi/js)

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 for the full integration walkthrough including domain registration and CSP.

Install

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:

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:

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:

<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.

​Install

​Embedded checkout

​Apple Pay

​Script tag

​Versioning

Install

Embedded checkout

Apple Pay

Script tag

Versioning