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

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).

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"]

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

Collects the password of the buyer’s account on a merchant site inside a Crossmint-hosted iframe and returns an opaque protectedInputId to hand to Universal Checkout. The password never reaches this component, the developer’s JavaScript, or the agent. Takes the buyer’s JWT as a prop, like CrossmintPaymentMethodManagement.

Props

ProtectedInputAppearance

string

ISO 8601 datetime. Server default is 24 hours from creation; the maximum is 7 days.

string

required

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

string

Text shown above the field, for example the merchant name. At most 120 characters.

string

required

The merchant sign-in page the password is for. Its host becomes the input’s merchant domain; Universal Checkout may only use the input on that host or a subdomain of it.

(created: { expiresAt: string; merchant: object; protectedInputId: string; purpose: "password" }) => void

Called once with the opaque protectedInputId to hand to Universal Checkout.

(error: { code: string; message: string }) => void

Usage

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

function MerchantPassword({ jwt, onProtectedInputId }: { jwt: string; onProtectedInputId: (id: string) => void }) {
    return (
        <CrossmintProtectedInput
            jwt={jwt}
            merchantUrl="https://shop.example.com/login"
            label="Example Shop"
            onCreated={({ protectedInputId }) => onProtectedInputId(protectedInputId)}
            onError={({ code, message }) => console.error(code, message)}
        />
    );
}

Note: CrossmintProtectedInput collects the password of the buyer’s account on a merchant site inside a Crossmint-hosted iframe and returns only an opaque protectedInputId. Pass that id to Universal Checkout as the protected input response; the password never reaches your JavaScript. Pass the buyer’s JWT as jwt, like CrossmintPaymentMethodManagement. Lifecycle: the hosted page posts exactly one terminal event per mount, so after onCreated or onError remount the component (change its key) to collect again; the page posts invalid_params when it rejects the props.

CrossmintAgentCardAuthorization

Lets a buyer authorize a bounded card spend for Universal Checkout 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. Pass that id to Universal Checkout as the run’s payment: { orderIntentId } or as the 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

CrossmintPaymentMethodManagement

Props

Usage

CrossmintProtectedInput

Props

Usage

CrossmintAgentCardAuthorization

Props

Usage

​CrossmintEmbeddedCheckout

​Props

​Usage

​CrossmintHostedCheckout

​Props

​Usage

​CrossmintPaymentMethodManagement

​Props

​Usage

​CrossmintProtectedInput

​Props

​Usage

​CrossmintAgentCardAuthorization

​Props

​Usage

CrossmintEmbeddedCheckout

Props

Usage

CrossmintHostedCheckout

Props

Usage

CrossmintPaymentMethodManagement

Props

Usage

CrossmintProtectedInput

Props

Usage

CrossmintAgentCardAuthorization

Props

Usage