Embedded checkout

Embedded checkout renders the Ionic-hosted payment form inside an iframe on your page. Card details are collected inside the frame, so they never touch your page or your servers, and your buyer completes the purchase without leaving your site. If a hosted redirect works for your product, start with Checkout instead — it is less integration surface. Choose embedded when the buyer staying on your domain matters.

How it works

One-time setup. Ionic only allows registered domains to embed checkout.

Create a session on your server

POST /v1/checkout/sessions with ui_mode: "embedded", using your secret key. Compute prices server-side.

Mount the checkout on your page

The browser SDK frames the session and manages the secure handshake, sizing, and lifecycle callbacks. React apps use the <CheckoutEmbed> component; everything else uses the JavaScript SDK directly.

Fulfill on the webhook

Fulfill after a verified checkout.session.completed webhook. The browser callback is a UX signal only.

1. Register your website’s domain

Register each origin that will embed checkout. Until an origin is registered, the frame refuses to render on it — this is what prevents another site from embedding checkout as your store.

curl https://api.ionicfi.com/v1/web_domains \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "https://shop.example.com"}'

The domain field accepts a bare domain (shop.example.com, treated as https://) or a full origin with scheme and port. For local development, register your localhost origin — http:// is allowed for localhost only:

  -d '{"domain": "http://localhost:3000"}'

Domains registered with a test key apply to test mode only; register production domains again with your live key when you go live.

2. Create a session on your server

Create the session from your server with your secret key. Always compute prices server-side; never trust amounts sent from the browser.

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const session = await ionic.checkout.sessions.create({
  "Idempotency-Key": "order-8241-checkout",
  mode: "payment",
  ui_mode: "embedded",
  line_items: [
    { name: "House Blend, 12oz", amount: 1800, currency: "usd", quantity: 2 },
  ],
});

curl https://api.ionicfi.com/v1/checkout/sessions \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8241-checkout" \
  -d '{
    "mode": "payment",
    "ui_mode": "embedded",
    "line_items": [
      {"name": "House Blend, 12oz", "amount": 1800, "currency": "usd", "quantity": 2}
    ]
  }'

Return exactly three response fields to your page:

Field	Purpose
`id`	The session identifier (`cs_...`)
`client_secret`	Grants the browser the right to drive this one session
`embed_url`	The URL the SDK frames — pass it through untouched

The client_secret is scoped to this single session and expires with it. It’s safe to send to the buyer’s browser — don’t log it or reuse it across sessions.

3. Mount the checkout on your page

Three ways in, one integration underneath. All three load the same runtime from https://js.ionicfi.com/v1/ionic.js at mount time — the card-handling code is never bundled into your app. The /v1 URL stays current, so checkout updates reach your integration without requiring an SDK upgrade.

React
JavaScript
Script tag

npm install @ionicfi/react

Fetch the session from your server and hand it to <CheckoutEmbed>:

import { useEffect, useState } from "react";
import { CheckoutEmbed } from "@ionicfi/react";

export function CheckoutPage() {
  const [session, setSession] = useState(null);

  useEffect(() => {
    fetch("/api/checkout", { method: "POST" })
      .then((res) => res.json())
      .then(setSession);
  }, []);

  if (!session) return <p>Preparing checkout…</p>;

  return (
    <CheckoutEmbed
      session={session}
      onComplete={({ sessionId }) => {
        // Show your confirmation page. Do not fulfill here — see step 4.
        window.location.href = `/order/confirmation?session_id=${sessionId}`;
      }}
      onCancel={() => {
        window.location.href = "/cart";
      }}
    />
  );
}

The component manages the iframe’s lifecycle for you: the frame holds the buyer’s in-progress card entry, so it is torn down and remounted only when the session itself changes — never because a parent re-render produced new callback identities. Passing a new session object with the same values does not remount.Digital wallets are offered automatically when the session is eligible; pass wallets={[]} for card only, or a specific list to restrict the offer. See Apple Pay below.

npm install @ionicfi/js

@ionicfi/js is a thin loader — it injects the runtime from Ionic’s CDN and returns the same IonicCheckout the script tag exposes:

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

const session = await fetch("/api/checkout", { method: "POST" }).then((res) =>
  res.json(),
);

const IonicCheckout = await loadIonicCheckout();
const checkout = IonicCheckout.mountSession("#checkout", {
  session,
  onComplete: ({ sessionId }) => {
    // Show your confirmation page. Do not fulfill here — see step 4.
    window.location.href = "/order/confirmation?session_id=" + sessionId;
  },
  onCancel: () => {
    window.location.href = "/cart";
  },
});

When your view unmounts (an SPA route change, for example), call checkout.destroy().

No build step required. Add the SDK:

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

Do not pin an integrity hash on this tag — the file’s contents change as new versions ship, so a pinned hash will eventually break the tag.Mount the session into a container element:

<div id="checkout"></div>
<script>
  const session = /* {id, client_secret, embed_url} from your server */;
  const checkout = window.Ionic.IonicCheckout.mountSession("#checkout", {
    session,
    onComplete: ({ sessionId }) => {
      // Show your confirmation page. Do not fulfill here — see step 4.
      window.location.href = "/order/confirmation?session_id=" + sessionId;
    },
    onCancel: () => {
      window.location.href = "/cart";
    },
  });
</script>

When your view unmounts, call checkout.destroy().

The frame sizes itself to its content and resizes as the buyer moves through the flow. Give the container your page’s content width. What the SDK handles, and what you handle:

The SDK handles	You handle
Creating and sizing the frame	Creating sessions on your server
The secure `client_secret` handshake	Passing the session object through untouched
Card fields, validation, decline retry UX	Navigation on `onComplete` / `onCancel`
Wallet eligibility and the payment sheet	Fulfillment — from the webhook, never the browser

Handling errors

Recoverable problems — network blips, card declines — keep their own retry UI inside the frame and never reach your code. What does reach your onError carries a terminal flag, and that flag is what you branch on, not the code:

onError: (error: EmbeddedCheckoutError) => {
  if (error.terminal) {
    // This frame will not change state on its own. Create a fresh session
    // on your server and mount it, or route the buyer back to the cart.
  } else {
    // The frame may still succeed (today: only "checkout_timeout", the
    // SDK's own readiness deadline). Leave it in place; consider logging.
  }
}

Codes you may see today: expired, not_found, init_timeout, payment_failed, tokenization_failed (all terminal) and checkout_timeout (not terminal). New codes can appear as the product grows — an unrecognized code still carries terminal, so handlers written against the flag keep working. terminal is a statement about this mounted frame, never about the payment. A payment can succeed and the frame still die afterward — fulfillment stays keyed to the webhook regardless of what onError reports. In React, recovering from a terminal error is a remount: create a new session on your server and pass it down (a changed session remounts on its own), or bump a key on <CheckoutEmbed> to retry the same session after a load failure:

<CheckoutEmbed key={attempt} session={session} onError={handleError} />

4. Fulfill on the webhook

Do not fulfill orders from onComplete or from your confirmation page loading. Buyers close tabs after paying, and connections drop before callbacks run. Fulfillment triggered only from the browser will miss paid orders.

Fulfill from the verified checkout.session.completed webhook delivered to your server, idempotently, keyed by the session id. See Webhooks for receiver setup — on Node, webhooks.unwrap() from @ionicfi/sdk verifies and types the event in one call. To check a payment without waiting for a webhook — on your confirmation page’s server route, or in local development where webhooks cannot reach you — read the session directly:

const session = await ionic.checkout.sessions.retrieve({ id: "cs_..." });
const paid = session.status === "complete" && session.payment_status === "paid";

curl https://api.ionicfi.com/v1/checkout/sessions/cs_... \
  -H "Authorization: Bearer sk_v1_test_..."

status: "complete" with payment_status: "paid" means the payment succeeded. The webhook drives fulfillment; the read answers whether one specific session paid, on demand.

Local development

Ionic cannot deliver webhooks to localhost. During local development, either retrieve the session as shown above, or expose your receiver with a tunnel (for example ngrok http 3000) and register the tunnel URL as a webhook endpoint. Remember to update the endpoint URL when the tunnel address changes.

Handling declines

A declined card keeps the session open and the form interactive — the buyer sees the decline inside the frame and can retry with another card. No onError fires; a decline is not a terminal state. To see why a payment declined, follow the session to its payment intent:

GET /v1/checkout/sessions/{id}        -> payment_intent_id
GET /v1/payment_intents/{id}          -> charges[0].decline_code

Content Security Policy

If your page sends a Content-Security-Policy header, it must allow the checkout to load. A blocked script leaves a page with no payment form, so check this before debugging anything else. The same directives apply to all three integration paths — the npm packages load the runtime from the CDN too.

Directive	Value	Why
`script-src`	`https://js.ionicfi.com`	The SDK loads from here at runtime rather than being bundled into your app, so security fixes reach every integration without a redeploy on your side.
`frame-src`	the origin of the session’s `embed_url`	The checkout document itself.

A minimal policy for a page that embeds checkout:

Content-Security-Policy:
  script-src 'self' https://js.ionicfi.com;
  frame-src https://api.ionicfi.com;

Apple Pay needs two further origins, because the wallet button renders in your page rather than inside the frame. The Apple Pay guide lists them alongside the rest of the wallet setup.

Take frame-src from the embed_url in your create-session response rather than copying a hostname from these docs. The value is issued per session, and reading it from the response keeps your policy correct if it changes.

Testing

Use the test card numbers in test mode. Two behaviors worth knowing before your first test purchase:

Repeating the same card and amount within about 20 minutes is declined as a duplicate. Vary the amount between repeated test runs.
Any amount under $1.00 always declines — useful for testing your decline handling.

Apple Pay

Eligible buyers see an Apple Pay button above the card form, in your page — never inside the frame — with an “Or pay with card” divider. Wallet payments complete through the same onComplete and the same webhook as card payments. Eligibility is decided server-side per session (device capability, domain registration, amount and currency), so you never compute it in the browser:

React: wallets are offered automatically. Restrict them with the wallets prop — wallets={["apple_pay"]} offers only Apple Pay, wallets={[]} is card only. When a requested wallet can’t be offered, the form still renders and the console names the exact setup step that’s missing.
JavaScript / script tag: pass applePay: true to mountSession.

Because embedded checkout runs on your domain, Apple Pay needs a one-time domain setup (registration + an association file) that hosted surfaces don’t. The Apple Pay guide covers the requirements, the reasons behind them, and how to test on a real device.

Start here

Accept payments

Recurring billing

After the payment

Build commerce

Concepts

How it works

1. Register your website’s domain

2. Create a session on your server

3. Mount the checkout on your page

Handling errors

4. Fulfill on the webhook

Local development

Handling declines

Content Security Policy

Testing

Apple Pay

​How it works

​1. Register your website’s domain

​2. Create a session on your server

​3. Mount the checkout on your page

​Handling errors

​4. Fulfill on the webhook

​Local development

​Handling declines

​Content Security Policy

​Testing

​Apple Pay

How it works

1. Register your website’s domain

2. Create a session on your server

3. Mount the checkout on your page

Handling errors

4. Fulfill on the webhook

Local development

Handling declines

Content Security Policy

Testing

Apple Pay