Components

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.

OrderIntentVerification

Runs the card network’s allowance verification for an order intent. Render it when the intent’s agentic-token rail reports status: "pending_verification"; it renders nothing itself and opens the network’s verification UI on mount.

Props

VerificationAppearance

Show properties

VerificationAppearanceRules

Show properties

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

Show properties

{ background?: string }

{ colors?: { background?: string } }

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

Show properties

string

{ background?: string; border?: string }

Show properties

string

{ border?: string }

{ colors?: { background?: string } }

Show properties

{ background?: string }

object

Show properties

string

{ background?: string; text?: string }

{ colors?: { background?: string } }

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

Show properties

{ border?: string }

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

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

Show properties

{ background?: string; text?: string }

{ colors?: { background?: string } }

VerificationAppearanceVariables

Show properties

string

object

Show properties

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

Name of the agent shown to the user in the card network’s verification UI.

() => void

Called once the user has approved the allowance. Refetch the order intent afterwards.

(error: unknown) => void

OrderIntentWithVerification

required

The order intent returned by the API, including its verificationConfig.

Show properties

{ available: string; currency: string; reserved: string; spent: string; total: string }

required

Show properties

string

required

string

required

string

required

string

required

string

required

string

required

string

required

OrderIntentMerchant

Show properties

string

required

ISO 3166-1 alpha-2, upper case.

string

required

string

required

http or https URL of the merchant.

string

required

string

required

OrderIntentRail[]

required

Show properties

OrderIntentCredentialFormat[]

required

OrderIntentProvider

"agentic-token"

required

OrderIntentStatus

required

OrderIntentVerificationConfig

required

Show properties

string

required

"production" | "test"

required

string

required

Usage

import { OrderIntentVerification, type OrderIntentVerificationProps } from "@crossmint/client-sdk-react-ui";

function VerifyOrderIntent({
    orderIntent,
}: {
    orderIntent: OrderIntentVerificationProps["orderIntent"];
}) {
    return (
        <OrderIntentVerification
            orderIntent={orderIntent}
            displayName="Acme Shopping Agent"
            onVerificationComplete={() => {
                console.log("Allowance verified");
            }}
            onVerificationError={(error) => {
                console.error("Allowance verification failed", error);
            }}
        />
    );
}

Note: After onVerificationComplete, fetch the order intent again and wait for the agentic-token rail to report status: "active" before creating a credential.

CrossmintCvcRecollection

Asks the user to enter a saved card’s CVC again. Render it when an order intent’s encrypted-card rail reports status: "pending_cvc_recollection", then refetch the order intent from onComplete.

Props

PaymentMethodManagementAppearance

Same appearance model as CrossmintPaymentMethodManagement and the embedded checkout, not the one of the verification modal: variables.fontSizeUnit / spacingUnit are multiplier units (defaults "4px" / "3.33px"), not base sizes. See EmbeddedCheckoutV3AppearanceVariables.

Show properties

EmbeddedCheckoutV3Appearance["fonts"]

EmbeddedCheckoutV3Appearance["rules"]

EmbeddedCheckoutV3Appearance["variables"]

string

required

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

() => void

Called once Crossmint has stored the new CVC. Receives no CVC and no token payload.

(error: object) => void

string

required

The saved card whose CVC has to be entered again.

Usage

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

function RefreshCardCvc({ jwt, paymentMethodId }: { jwt: string; paymentMethodId: string }) {
    return (
        <CrossmintCvcRecollection
            jwt={jwt}
            paymentMethodId={paymentMethodId}
            onComplete={() => {
                console.log("CVC stored, refetch the order intent");
            }}
            onError={(error) => {
                if (!error.retriable) {
                    console.error("CVC recollection failed", error);
                }
            }}
        />
    );
}

Note: Render it when an order intent’s encrypted-card rail reports status: "pending_cvc_recollection", or when creating a credential is refused with HTTP 409 ORDER_INTENT_CVC_RECOLLECTION_REQUIRED. Retriable errors keep the form mounted; non-retriable ones unmount it, so show your own message.

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.

Introduction

Agent Cards

Agent Wallets

Agent Checkouts

API Reference

CrossmintPaymentMethodManagement

Props

Usage

OrderIntentVerification

Props

Usage

CrossmintCvcRecollection

Props

Usage

CrossmintProtectedInput

Props

Usage

​CrossmintPaymentMethodManagement

​Props

​Usage

​OrderIntentVerification

​Props

​Usage

​CrossmintCvcRecollection

​Props

​Usage

​CrossmintProtectedInput

​Props

​Usage

CrossmintPaymentMethodManagement

Props

Usage

OrderIntentVerification

Props

Usage

CrossmintCvcRecollection

Props

Usage

CrossmintProtectedInput

Props

Usage