React (@ionicfi/react)

React bindings over the browser SDK: one component that mounts an embedded checkout session and manages the iframe’s lifecycle across re-renders. It depends on @ionicfi/js and bundles no payment logic of its own. Install @ionicfi/react for React 18 or 19:

npm install @ionicfi/react@^0.2.1

CheckoutEmbed renders a complete checkout session. For a custom form with your own Pay button, mount an Ionic Block from @ionicfi/js in an effect and destroy it when the view unmounts.

Usage

Create a checkout session on your server with ui_mode: "embedded", hand the response to the component, and render it where the payment form should appear:

import { CheckoutEmbed, type EmbeddedCheckoutSession } from "@ionicfi/react";

function PayPage({ session }: { session: EmbeddedCheckoutSession }) {
  return <CheckoutEmbed session={session} />;
}

session is the create-session API response ({ id, client_secret, embed_url }). The component loads the Ionic SDK from Ionic’s CDN on first mount (an existing window.Ionic, for example from a hand-placed script tag, is reused), so the card-handling runtime is never bundled into your app. onComplete is a browser display signal. Your backend determines payment state from the API or verified events, including the expected merchant, mode, and session identity. Your application owns fulfillment policy. A completed payment session has status: "complete" and payment_status: "paid". Pass onError if you want to own the failure UI. Without it, the two failures that leave nothing on the page (the SDK script not loading, and mount rejecting its options) render a built-in message. Everything the checkout itself reports (expired session, terminal payment failure) is already displayed inside the iframe, so the component does not add a second message for those. Digital wallets are on by default (wallets defaults to "auto"): if the buyer’s device and your account support one, it appears above the card form once Apple Pay setup is complete. Don’t render the component inside another iframe: the checkout document controls who may frame it, and payment methods that redirect can’t complete inside a nested frame. In a Next.js App Router project, import it from a client component. The published bundle carries the "use client" directive, so importing it from a server component tree works without extra annotation, but the surrounding page logic (state, callbacks) must itself be client-side.

Props

Prop	Type	Description
`session`	`EmbeddedCheckoutSession`	Required. The create-session response.
`wallets`	`"auto" \| WalletId[]`	Which digital wallets to offer above the card form. Defaults to `"auto"`: every wallet the server reports eligible for the session. Pass an array to restrict the offer, or `[]` for card only. Eligibility (device, domain registration, amount) is decided server-side, so pass a static value; don’t compute it from an async capability check. Changing which wallets are offered remounts the iframe.
`timeoutMs`	`number`	How long to wait for checkout to become ready. Read at mount time; changing it later doesn’t remount.
`iframeTitle`	`string`	Accessible title for the checkout iframe. Applied in place; changing it doesn’t remount.
`className`	`string`	Applied to the host `div` the iframe mounts into.
`onReady`	`() => void`	The form is visible and interactive.
`onComplete`	`(e) => void`	Payment succeeded. Fulfill on your server via webhooks; use this to update the UI.
`onCancel`	`(e) => void`	The buyer backed out. Not terminal; the form stays live.
`onError`	`(e) => void`	A failure was reported. See the code list below for which ones are terminal.

Error codes

onError receives { code, message, terminal }. Branch on terminal, not on code. terminal: false means the iframe is still live and may yet succeed, so replacing it with an error screen would take a working checkout away from the buyer. New codes are added over time, so a switch on code needs a default branch; terminal never needs updating.

Code	Source	`terminal`
`sdk_load_failed`	This package: the CDN script failed to load	`true`; remount to retry (see below)
`mount_failed`	This package: `mount()` rejected its options	`true`
`checkout_timeout`	SDK: the iframe didn’t become ready in `timeoutMs`	`false`; the iframe stays live and may still become ready on a slow connection
`init_timeout`	Checkout: the handshake inside the iframe timed out	`true`
`payment_failed`	Checkout: terminal payment failure	`true`
`expired`	Checkout: the session expired	`true`; create a new session
`not_found`	Checkout: the session doesn’t exist	`true`
`tokenization_failed`	Checkout: card tokenization failed terminally	`true`

Retryable declines (an issuer saying no) never reach onError; the checkout handles them in the iframe and the buyer can try another card. New codes may be added over time; always handle unknown codes in a default branch rather than treating the list as closed.

Retrying after a load failure

After sdk_load_failed, remount the component to retry: the loader clears the failed load before retrying, so a fresh mount injects a fresh script.

Re-render behavior

The iframe holds the buyer’s in-progress card entry, so the component tears it down and remounts only when the values that define the mount change: the session’s fields (id, client_secret, embed_url) or the set of wallets offered. New callback identities (inline arrow functions), new session object identities with unchanged values, timeoutMs, and iframeTitle never remount. Callbacks always fire with their latest render’s identity, and never after the component unmounts.

Content Security Policy

If your page sends a Content-Security-Policy, it needs script-src https://js.ionicfi.com (the SDK is loaded at runtime, never bundled) and frame-src set to the origin of the session’s embed_url. A blocked script renders no payment form. Wallets need additional origins; see Embedded checkout: Content Security Policy.

Module format

This package and @ionicfi/js are ESM-only. The build and test environment must support ES modules.

Security notes

The component passes session.client_secret to the SDK and never logs or stores it. It does live in React props, so tooling that captures props (React DevTools, error reporters configured to serialize component trees) can see it. The secret authorizes completing this one checkout session only.

What’s next

Embed checkout

Create the session on your server and set up wallets and Content Security Policy.

Build a payment page

Mount an Ionic Block in an effect for a custom form with your own Pay button.

Handle webhook events

Verify each event’s signature and fulfill orders from it.

SDKs

Webhooks

Resources

React (@ionicfi/react)

Usage

Props

Error codes

Retrying after a load failure

Re-render behavior

Content Security Policy

Module format

Security notes

What’s next

Embed checkout

Build a payment page

Handle webhook events

​Usage

​Props

​Error codes

​Retrying after a load failure

​Re-render behavior

​Content Security Policy

​Module format

​Security notes

​What’s next

Embed checkout

Build a payment page

Handle webhook events

Usage

Props

Error codes

Retrying after a load failure

Re-render behavior

Content Security Policy

Module format

Security notes

What’s next