Browser SDK (@ionicfi/js)

Use the browser SDK to build a payment form with Ionic Blocks or to mount a complete embedded checkout. Your server creates the PaymentIntent or checkout session; the browser collects the customer’s payment details through Ionic.

Ionic Blocks

Use a Payment Block when you own the checkout page and the Pay button. Your backend creates a PaymentIntent, and the browser receives its client secret and confirms it through Ionic. The Ionic Blocks guide covers intent ownership, mounting, confirmation results, consent, and events.

<script src="https://js.ionicfi.com/v1/ionic.js"></script>

const ionic = Ionic(publishableKey);
const blocks = ionic.blocks({ clientSecret });
await blocks.create("payment").mount("#payment");
// When the customer submits:
const { paymentIntent, error } = await ionic.confirmPayment({ blocks });

For Connect, create the client with your platform publishable key and the connected account’s ID:

const ionic = Ionic(platformPublishableKey, { account: connectedMerchantId });
const blocks = ionic.blocks({ clientSecret });
await blocks.create("payment").mount("#payment");
const { paymentIntent, error } = await ionic.confirmPayment({ blocks });

connectedMerchantId is the receiving merchant’s Ionic mer_… ID, returned by your backend, which created the PaymentIntent for the same merchant with Ionic-Account or the server SDK’s { account } option. The client keeps that merchant for mounting, confirmation, and status checks; create a separate client to collect for another merchant. See both sides in Accept payments for connected accounts. Build with test keys, then follow Going live when the flow works end to end. mountPaymentFields remains available for tokenization-only integrations; see Advanced card fields.

Install

Install @ionicfi/js with npm, which is included with Node.js:

npm install @ionicfi/js@^0.2.1

A page without a build step can use the script tag instead.

Use Blocks with npm

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 });

Your backend returns the publishable key and client secret. Use confirmSetup with a SetupIntent to save a card without charging. Call blocks.destroy() when your payment view unmounts. The Blocks reference lists every option, event, and error code.

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 error 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 Embedded checkout: Content Security Policy 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.

What’s next

Build a payment page

Mount a Payment Block and confirm a PaymentIntent.

Embed checkout

Mount a complete checkout session in your page.

Use the React component

Render embedded checkout with <CheckoutEmbed>.

SDKs

Webhooks

Resources

Browser SDK (@ionicfi/js)

Ionic Blocks

Install

Use Blocks with npm

Embedded checkout

Apple Pay

Script tag

Versioning

What’s next

Build a payment page

Embed checkout

Use the React component

​Ionic Blocks

​Install

​Use Blocks with npm

​Embedded checkout

​Apple Pay

​Script tag

​Versioning

​What’s next

Build a payment page

Embed checkout

Use the React component

Ionic Blocks

Install

Use Blocks with npm

Embedded checkout

Apple Pay

Script tag

Versioning

What’s next