@ionicfi/js

Browser SDK loader for Ionic payments. It loads the Ionic SDK from https://js.ionicfi.com so card entry stays inside Ionic-hosted iframes and never enters your application bundle.

Install

npm install @ionicfi/js

Ionic Blocks

Use Blocks when your application owns the payment page and Pay button. Your server creates a PaymentIntent and returns its client secret with your publishable key.

import { loadIonic } from "@ionicfi/js";

const ionic = await loadIonic("pk_v1_test_...");
const blocks = ionic.blocks({ clientSecret: "pi_..._secret_..." });
await blocks.create("payment").mount("#payment");
// In your Pay handler:
const result = await ionic.confirmPayment({ blocks });

Use confirmSetup with a SetupIntent to save a card without charging. For Connect, pass { account: connectedMerchantId } to loadIonic and create the intent for the same merchant on your server. Call blocks.destroy() when the view unmounts.

See Build a payment page and How Connect works for complete walkthroughs.

Loading and errors

loadIonic and loadIonicCheckout share one script load. Loading rejects after 30 seconds or on a script error. Call again to retry. If you supplied a script tag yourself, remove or replace a failed tag before retrying. A conflicting window.Ionic value must be removed or renamed before loading. This includes unrelated functions; an existing v1 SDK factory is recognized by its original checkout helpers, including bundles from before session helpers were added.

For tokenization-only integrations using mountPaymentFields, catch errors with isPaymentFieldsError(error). PaymentFieldsError is a TypeScript type; use the guard instead of constructing it or checking instanceof:

import { isPaymentFieldsError } from "@ionicfi/js";

try {
  await fields.tokenize();
} catch (error) {
  if (isPaymentFieldsError(error)) {
    console.error(error.code, error.message);
    // If error.terminal is true, obtain a fresh session and mount again.
  } else {
    throw error;
  }
}

Module format

This package ships ES modules. CommonJS applications can use require() on Node 20.19+ or 22.12+, or dynamic import() on older Node versions. Jest setups using CommonJS transforms must also transform the Ionic packages; an export fallback alone does not transform ES modules.

Embedded checkout

Create a checkout session on your server with ui_mode: "embedded", return it to your frontend, and mount it. Include an element with id="payment-message" and role="status" next to the checkout for messages:

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) => {
    const message = document.querySelector("#payment-message");
    if (message) message.textContent = 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.

License

MIT