Components

CrossmintEmbeddedCheckout

Props

EmbeddedCheckoutV3Appearance

Show properties

{ cssSrc: string }[]

Show properties

string

required

EmbeddedCheckoutV3AppearanceRules

Show properties

{ display?: "hidden" }

Show properties

"hidden"

{ display?: "hidden" | "visible" }

Show properties

"hidden" | "visible"

object

Show properties

string

{ background?: string; border?: string; boxShadow?: string; placeholder?: string; text?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string } }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }

{ colors?: { text?: string }; font?: { family?: string; size?: string; weight?: string } }

Show properties

{ text?: string }

{ family?: string; size?: string; weight?: string }

object

Show properties

string

{ background?: string; text?: string }

{ colors?: { background?: string; text?: string } }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; text?: string } }

{ display?: "hidden" }

Show properties

"hidden"

object

Show properties

string

{ background?: string; border?: string; boxShadow?: string; text?: string }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }

EmbeddedCheckoutV3AppearanceVariables

Show properties

string

object

Show properties

string

Multiplier unit for font sizes, not a base font size. Default "4px": labels render at fontSizeUnit * 3.75 (15px), inputs at * 4 (16px), the primary button at * 4.25 (17px). Passing a body size such as "14px" (the VerificationAppearance convention) yields ~52px labels.

string

Multiplier unit for paddings and gaps, not a base spacing. Default "3.33px"; each spacing is calc(spacingUnit * k) with k between 3.6 and 4.42.

string

"external"

"external": you mount CrossmintIdentityVerification from getIdentityVerificationCredentials(order), or the buyer cannot finish.

string

EmbeddedCheckoutV3Payment

required

Show properties

EmbeddedCheckoutV3CryptoPayment

required

Show properties

BlockchainIncludingTestnet

CryptoCurrency

boolean

required

EmbeddedCheckoutPayer

Show properties

string

required

PayerSupportedBlockchains

required

PayerSupportedBlockchains[]

unknown

required

unknown

required

unknown

"fiat" | "crypto"

EmbeddedCheckoutV3FiatPayment

required

Show properties

{ applePay?: boolean; card?: boolean; googlePay?: boolean }

Show properties

boolean

FiatCurrency

boolean

required

string

EmbeddedCheckoutV3LineItem | EmbeddedCheckoutV3LineItem[]

Show properties

Record<string, any>

string

Record<string, any>

string

Locale

JSONObject

EmbeddedCheckoutV3Recipient

Show properties

string

EmbeddedCheckoutV3PhysicalAddress

Show properties

string

required

"US"

required

string

required

string

required

string

required

string

required

string

Usage

import { CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";

function Checkout() {
    return (
        <CrossmintEmbeddedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "base-sepolia",
                    defaultCurrency: "usdc",
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                    allowedMethods: {
                        card: true,
                        applePay: true,
                        googlePay: true,
                    },
                },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
            locale="en-US"
        />
    );
}

CrossmintHostedCheckout

Props

CrossmintHostedCheckoutV3Appearance

Show properties

"popup" | "new-tab" | "same-tab"

CrossmintHostedCheckoutV3OverlayOptions

Show properties

boolean

required

HostedCheckoutV3AppearanceRules

Show properties

{ display?: "hidden" }

Show properties

"hidden"

{ display?: "hidden" }

Show properties

"hidden"

{ button?: CrossmintHostedCheckoutV3ButtonTheme; checkout?: CrossmintHostedCheckoutV3Theme }

Show properties

CrossmintHostedCheckoutV3ButtonTheme

CrossmintHostedCheckoutV3Theme

CrossmintHostedCheckoutV3AppearanceVariables

Show properties

{ accent?: string }

Show properties

string

EmbeddedCheckoutV3LineItem | EmbeddedCheckoutV3LineItem[]

Show properties

Record<string, any>

string

Record<string, any>

string

Locale

JSONObject

HostedCheckoutV3Payment

required

Show properties

HostedCheckoutV3CryptoPayment

required

Show properties

BlockchainIncludingTestnet

CryptoCurrency

boolean

required

"fiat" | "crypto"

HostedCheckoutV3FiatPayment

required

Show properties

FiatCurrency

boolean

required

string

EmbeddedCheckoutV3Recipient

Show properties

string

EmbeddedCheckoutV3PhysicalAddress

Show properties

string

required

"US"

required

string

required

string

required

string

required

string

required

string

Usage

import { CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

function BuyButton() {
    return (
        <CrossmintHostedCheckout
            lineItems={{
                collectionLocator: "crossmint:YOUR_COLLECTION_ID",
                callData: {
                    totalPrice: "0.001",
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "base-sepolia",
                    defaultCurrency: "usdc",
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd",
                },
                receiptEmail: "buyer@example.com",
            }}
            recipient={{ email: "buyer@example.com" }}
            appearance={{
                display: "popup",
                overlay: { enabled: true },
                theme: {
                    button: "dark",
                    checkout: "light",
                },
            }}
            locale="en-US"
        />
    );
}

CrossmintIdentityVerification

Props

EmbeddedCheckoutV3Appearance

Show properties

{ cssSrc: string }[]

Show properties

string

required

EmbeddedCheckoutV3AppearanceRules

Show properties

{ display?: "hidden" }

Show properties

"hidden"

{ display?: "hidden" | "visible" }

Show properties

"hidden" | "visible"

object

Show properties

string

{ background?: string; border?: string; boxShadow?: string; placeholder?: string; text?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string } }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }

{ colors?: { text?: string }; font?: { family?: string; size?: string; weight?: string } }

Show properties

{ text?: string }

{ family?: string; size?: string; weight?: string }

object

Show properties

string

{ background?: string; text?: string }

{ colors?: { background?: string; text?: string } }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; text?: string } }

{ display?: "hidden" }

Show properties

"hidden"

object

Show properties

string

{ background?: string; border?: string; boxShadow?: string; text?: string }

{ family?: string; size?: string; weight?: string }

{ colors?: { background?: string; border?: string; boxShadow?: string; text?: string } }

EmbeddedCheckoutV3AppearanceVariables

Show properties

string

object

Show properties

string

Multiplier unit for paddings and gaps, not a base spacing. Default "3.33px"; each spacing is calc(spacingUnit * k) with k between 3.6 and 4.42.

IdentityVerificationCredentials

required

Show properties

string

"persona"

string

Locale

() => void

The user closed the flow: Done on a blocked screen, or closing document capture. Without it, Done does nothing.

(result: { status: "expired" | "unknown" | "failed" | "verified" | "pending-review" | "pending-manual-review" | "declined" }) => void

The flow ended with a result. Unmount here, not when the credentials go away: the order moves on first.

(error: object) => void

() => void

Usage

import { useRef, useState } from "react";
import {
    CrossmintIdentityVerification,
    type IdentityVerificationAppearance,
    useIdentityVerificationCredentials,
} from "@crossmint/client-sdk-react-ui";

// Mount one step per order, for example with key={order.orderId}, so the next order starts open.
function VerificationStep({ appearance }: { appearance?: IdentityVerificationAppearance }) {
    const credentials = useIdentityVerificationCredentials();
    // The order moves on before the flow shows its result, so keep the last credentials
    // and close the step on onComplete or onCancel.
    const lastCredentials = useRef(credentials);
    lastCredentials.current = credentials ?? lastCredentials.current;
    const [closed, setClosed] = useState(false);

    if (closed || lastCredentials.current == null) {
        return null;
    }

    return (
        <CrossmintIdentityVerification
            credentials={lastCredentials.current}
            appearance={appearance}
            onComplete={({ status }) => {
                console.log(status);
                setClosed(true);
            }}
            onCancel={() => setClosed(true)}
        />
    );
}

Note: Keep the component mounted until onComplete or onCancel: the order leaves requires-kyc, and the hook returns undefined, before the flow shows its result. Handle onCancel, or the Done button on blocked screens does nothing. Pass the appearance object you give embedded checkout, so both look the same.

CrossmintPaymentMethodManagement

Lets the user save a new card or bank account, or pick one of their saved payment methods. Rendered in a Crossmint-hosted iframe, so payment details never touch your app. Takes the user’s Crossmint jwt. onPaymentMethodSelected receives the chosen method; its paymentMethodId is what your backend uses to pay (for example to create order intents). To use your own button instead of the component’s, pass hideSubmitButton and a ref, and call ref.current.submit() from your button: it resolves with the selected or saved method, or with why the submit could not complete.

Props

"new" | "existing"[]

Which sections the management UI renders. ["new"] (default) shows only the “add new” section: no saved-methods fetch, no auto-open/auto-select of an existing method. Include "existing" to also show the saved-methods section.

PaymentMethodManagementAllowedType[]

Filter array of which method types the “add new” section offers (default ["card"]). LM0 renders the first supported entry; passing more than one type does not yet render a type picker.

PaymentMethodManagementAppearance

Show properties

EmbeddedCheckoutV3Appearance["fonts"]

EmbeddedCheckoutV3Appearance["rules"]

EmbeddedCheckoutV3Appearance["variables"]

boolean

Render no Save/Continue button inside the component (default false). Pair it with a ref and call ref.current.submit() from your own button.

string

required

(paymentMethod: CrossmintPaymentMethod) => void | Promise<void>

Usage

import { CrossmintPaymentMethodManagement } from "@crossmint/client-sdk-react-ui";

function PaymentMethods({ jwt }: { jwt: string }) {
    return (
        <CrossmintPaymentMethodManagement
            jwt={jwt}
            allowedModes={["new", "existing"]}
            allowedPaymentMethodTypes={["card"]}
            onPaymentMethodSelected={(paymentMethod) => {
                if (paymentMethod.type === "card") {
                    console.log("Card selected:", paymentMethod.card.last4);
                }
            }}
        />
    );
}

Note: CrossmintPaymentMethodManagement renders an iframe-based UI for managing saved payment methods. Requires a valid JWT for authentication. The onPaymentMethodSelected callback receives a discriminated union — narrow on type before accessing variant-specific fields.

CrossmintProtectedInput

Collect a protected text or numeric field in a Crossmint-hosted iframe. Call ref.collect() from your submit action to receive a protected reference or a collection error. Your page renders the label, button, and error message; collection keeps the entered value out of application JavaScript.

Props

ProtectedInputAppearance

boolean

string

ISO 8601; server default is 24 hours, maximum is 7 days.

ProtectedInputField

required

Show properties

"protected"

required

object | { kind: "number" | "integer" }

required

Show properties

"masked"

"text"

required

false

string

required

string

required

boolean

required

boolean

Controls the visual invalid state; the developer renders the error message.

string

required

Buyer’s JWT from the application’s external auth integration.

Usage

import { useRef, useState } from "react";
import {
    CrossmintProvider,
    CrossmintProtectedInput,
    type CrossmintProtectedInputRef,
    type ProtectedInputField,
} from "@crossmint/client-sdk-react-ui";

type Props = {
    apiKey: string;
    jwt: string;
    field: ProtectedInputField;
    onCollected: (answer: { protectedInputId: string }) => Promise<void>;
};

export function ProtectedField({ apiKey, jwt, field, onCollected }: Props) {
    const ref = useRef<CrossmintProtectedInputRef>(null);
    const [busy, setBusy] = useState(false);
    const [error, setError] = useState("");

    async function collect() {
        if (busy || ref.current === null) {
            return;
        }
        setBusy(true);
        setError("");
        try {
            const result = await ref.current.collect();
            if (result.status !== "collected") {
                setError(result.message);
                return;
            }
            await onCollected(result.input);
        } catch {
            setError("Could not confirm submission. Retry the same message.");
        } finally {
            setBusy(false);
        }
    }

    return (
        <CrossmintProvider apiKey={apiKey}>
            <div>{field.label}</div>
            <CrossmintProtectedInput
                ref={ref}
                jwt={jwt}
                field={field}
                disabled={busy}
                invalid={error !== ""}
            />
            {error !== "" && <p role="alert">{error}</p>}
            <button type="button" disabled={busy} onClick={collect}>
                Continue
            </button>
        </CrossmintProvider>
    );
}

Note: Pass the protected field descriptor from an Agent Checkout form as field, your browser client API key to CrossmintProvider, and the buyer JWT as jwt. The iframe renders only an input; your page owns the button and errors. ref.collect() returns collected, invalid, unavailable, or superseded. Submit result.input under the field key in response.answers alongside ordinary answers. Unchanged successful collections reuse the reference; edits invalidate that reuse. Use one ref per protected field. display: “masked” controls presentation independently of handling. Collection keeps plaintext out of application JavaScript; it does not mask merchant-page screenshots or recordings.

CrossmintAgentCardAuthorization

Lets a buyer authorize a bounded card spend for Agent Checkouts and hands back an orderIntentId. Composes card selection, order-intent registration, order-intent creation and rail verification; the rail is chosen by a fixed policy, never by the model or the buyer. The card number, CVC and vault token id never reach this component’s callbacks.

Props

"new" | "existing"[]

Sections of the payment-method UI to render. Defaults to ["existing", "new"].

{ currency: string; value: string }

required

value is a decimal string with up to 4 places, greater than 0; currency is a 3-letter code.

Show properties

string

required

string

required

AgentCardAuthorizationAppearance

Show properties

PaymentMethodManagementAppearance

Styles the card selection and the CVC recollection form, which share this appearance model.

Show properties

EmbeddedCheckoutV3Appearance["fonts"]

EmbeddedCheckoutV3Appearance["rules"]

EmbeddedCheckoutV3Appearance["variables"]

VerificationAppearance

Styles the card-network verification modal.

Show properties

VerificationAppearanceRules

Show properties

{ colors?: { background?: string }; hover?: { colors?: object } }

{ borderRadius?: string; colors?: { background?: string; border?: string } }

{ colors?: { background?: string } }

object

{ colors?: { border?: string }; selected?: { colors?: object } }

{ colors?: { background?: string; text?: string }; hover?: { colors?: object } }

VerificationAppearanceVariables

Show properties

string

object

string

Not applied by OrderIntentVerification: only colors (and the button / input colors under rules) reach the verification modal. Not the multiplier unit of EmbeddedCheckoutV3AppearanceVariables.fontSizeUnit, so do not share one object between the two.

string

Not applied by OrderIntentVerification; see fontSizeUnit.

string

required

string

required

Shown to the buyer by the rail verification UI.

string

ISO 8601 datetime in the future. Defaults to 24 hours from mount.

string

required

The buyer’s Crossmint auth token, the same one CrossmintPaymentMethodManagement takes.

OrderIntentMerchant

required

Show properties

string

required

ISO 3166-1 alpha-2, upper case.

string

required

string

required

http or https URL of the merchant.

(result: AgentCardAuthorizationResult) => void

required

(error: AgentCardAuthorizationError) => void

required

Usage

import { CrossmintAgentCardAuthorization } from "@crossmint/client-sdk-react-ui";

function AuthorizeCard({ jwt, onOrderIntentId }: { jwt: string; onOrderIntentId: (id: string) => void }) {
    return (
        <CrossmintAgentCardAuthorization
            jwt={jwt}
            amount={{ value: "120.00", currency: "USD" }}
            merchant={{ name: "Example Shop", url: "https://shop.example.com", countryCode: "US" }}
            description="Running shoes, order placed by your shopping agent"
            displayName="Example Shop"
            onAuthorized={({ orderIntentId }) => onOrderIntentId(orderIntentId)}
            onError={({ code, message }) => console.error(code, message)}
        />
    );
}

Note: CrossmintAgentCardAuthorization composes card selection, order-intent registration, order-intent creation and rail verification, and calls onAuthorized once with an orderIntentId. Submit that ID as response.orderIntentId in the Agent Checkout’s payment input response. The rail is chosen by the same policy the server applies (vic, then agentpay, then encrypted-card, preferring a rail that is already active); card numbers, CVCs and vault token ids never reach your JavaScript. Lifecycle: after onAuthorized the component renders nothing; after onError it returns to card selection so the buyer can try again; state lives for one mount, so a remount (a key or route change) creates a new order intent for the same spend and your app must store the orderIntentId from onAuthorized. Pass the buyer’s JWT as jwt, like CrossmintPaymentMethodManagement. appearance.paymentMethodManagement styles the card selection and the CVC recollection form, appearance.verification the card-network verification modal.

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

CrossmintEmbeddedCheckout

Props

Usage

CrossmintHostedCheckout

Props

Usage

CrossmintIdentityVerification

Props

Usage

CrossmintPaymentMethodManagement

Props

Usage

CrossmintProtectedInput

Props

Usage

CrossmintAgentCardAuthorization

Props

Usage

​CrossmintEmbeddedCheckout

​Props

​Usage

​CrossmintHostedCheckout

​Props

​Usage

​CrossmintIdentityVerification

​Props

​Usage

​CrossmintPaymentMethodManagement

​Props

​Usage

​CrossmintProtectedInput

​Props

​Usage

​CrossmintAgentCardAuthorization

​Props

​Usage

CrossmintEmbeddedCheckout

Props

Usage

CrossmintHostedCheckout

Props

Usage

CrossmintIdentityVerification

Props

Usage

CrossmintPaymentMethodManagement

Props

Usage

CrossmintProtectedInput

Props

Usage

CrossmintAgentCardAuthorization

Props

Usage