Models

Configuration classes used to set up the embedded checkout widget. All models are imported from crossmint_flutter_ui.dart.

CrossmintCheckoutConfig

Top-level configuration for CrossmintEmbeddedCheckout. Combines an order, payment method configuration, and optional appearance customization.

Props

CrossmintCheckoutOrder

required

Order to check out — either a [CrossmintCheckoutNewOrder] built from line items, or a [CrossmintCheckoutExistingOrder] referencing an already-created order by id.

CrossmintCheckoutPayment

required

Payment method configuration — fiat, crypto, and default method.

Show properties

CrossmintCheckoutFiatPayment?

Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

Show properties

bool

required

Whether fiat payments are enabled.

String?

ISO 4217 currency code preselected in the fiat tab (e.g. "USD").

bool?

When false, hides the credit-card payment method. null keeps the project default.

bool?

When false, hides Apple Pay. null keeps the project default.

bool?

When false, hides Google Pay. null keeps the project default.

CrossmintCheckoutCryptoPayment?

Crypto payment configuration — null disables the crypto tab.

Show properties

bool

required

Whether crypto payments are enabled.

String?

Chain preselected in the crypto tab (e.g. "base", "solana"). Must appear in the payer’s [CrossmintCheckoutPayer.supportedChains] when a payer is attached.

String?

Currency preselected in the crypto tab (e.g. "USDC").

CrossmintCheckoutPayer?

Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.

String?

Raw default payment method string. Prefer [defaultMethodType] for compile-time safety. When both are set, [defaultMethodType] wins.

CrossmintCheckoutDefaultMethod?

Typed default payment method — one of [CrossmintCheckoutDefaultMethod]: fiat (open on credit card / Apple Pay / Google Pay) or crypto (open on on-chain payment). Takes precedence over [defaultMethod].

String?

Email to receive the order receipt. Leave null to use the recipient email (for [CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.

CrossmintCheckoutAppearance?

Optional appearance customization — CSS variables, rules, fonts.

Show properties

Map<String, Object?>?

CSS custom properties for theming (e.g. {'colorPrimary': '#0F172A'}).

Map<String, Object?>?

CSS rules for specific checkout elements (e.g. {'.Input': {'borderColor': '#CBD5E1'}}).

List<Map<String, String>>?

Custom font definitions (e.g. [{'cssSrc': 'https://fonts.googleapis.com/...'}]).

String?

Optional JWT for authenticated checkouts — attaches the user’s Crossmint session to the hosted page so the experience is signed-in when the user lands. Pass client.auth.state.session?.jwt when you want the checkout to inherit the current app session.

CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

Order configuration — either create a new order inline with line items, or resume an existing order by ID.

Props

List<Map<String, Object?>>

required

Line items in the order, each represented as a raw JSON map. Prefer the [CrossmintCheckoutNewOrder.typed] constructor and pass typed [CrossmintCheckoutLineItem] values; use the raw map shape only when a new API field is not yet modeled by the SDK.

CrossmintCheckoutRecipient?

Optional recipient for the order. When omitted, the hosted checkout collects recipient details from the buyer.

String?

Optional BCP 47 locale tag (for example en-US, es, pt-BR) used to localize the hosted checkout UI. Defaults to the buyer’s browser locale when null.

Map<String, Object?>?

Optional opaque metadata attached to the order. Forwarded verbatim to the Crossmint orders API and returned on order webhooks and status reads.

Usage

// New order with typed line items
CrossmintCheckoutNewOrder.typed(
  lineItems: [
    CrossmintCheckoutLineItem.collection(
      collectionLocator: 'crossmint:YOUR_COLLECTION_ID',
      callData: {'quantity': 1},
    ),
  ],
  recipient: CrossmintCheckoutEmailRecipient(
    email: 'buyer@example.com',
  ),
  locale: 'en-US',
)

// Resume an existing order
CrossmintCheckoutExistingOrder(
  orderId: 'ORDER_ID',
  clientSecret: 'CLIENT_SECRET',
)

CrossmintCheckoutLineItem

A single asset to purchase in a checkout order. Use the named factory constructors: .collection(), .token(), .tokenWithExecutionParameters(), .product(), or .raw() for forward-compatible escape hatches.

Usage

// Collection (primary sale)
CrossmintCheckoutLineItem.collection(
  collectionLocator: 'crossmint:YOUR_COLLECTION_ID',
  callData: {'quantity': 2},
)

// Token (secondary sale)
CrossmintCheckoutLineItem.token(
  tokenLocator: 'crossmint:YOUR_TOKEN_ID',
)

// Token with execution parameters (e.g. memecoin swap)
CrossmintCheckoutLineItem.tokenWithExecutionParameters(
  tokenLocator: 'crossmint:YOUR_TOKEN_ID',
  executionParameters: {
    'amount': '1000000',
    'mode': 'exact-in',
    'maxSlippageBps': 100,
  },
)

// Product (catalog-managed)
CrossmintCheckoutLineItem.product(
  productLocator: 'crossmint:YOUR_PRODUCT_ID',
)

CrossmintCheckoutPayment

Payment method configuration — at least one of fiat or crypto must be enabled. Controls which payment methods are shown and which is selected by default.

Props

CrossmintCheckoutFiatPayment?

Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

Show properties

bool

required

Whether fiat payments are enabled.

String?

ISO 4217 currency code preselected in the fiat tab (e.g. "USD").

bool?

When false, hides the credit-card payment method. null keeps the project default.

bool?

When false, hides Apple Pay. null keeps the project default.

bool?

When false, hides Google Pay. null keeps the project default.

CrossmintCheckoutCryptoPayment?

Crypto payment configuration — null disables the crypto tab.

Show properties

bool

required

Whether crypto payments are enabled.

String?

Chain preselected in the crypto tab (e.g. "base", "solana"). Must appear in the payer’s [CrossmintCheckoutPayer.supportedChains] when a payer is attached.

String?

Currency preselected in the crypto tab (e.g. "USDC").

CrossmintCheckoutPayer?

Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.

String?

Raw default payment method string. Prefer [defaultMethodType] for compile-time safety. When both are set, [defaultMethodType] wins.

CrossmintCheckoutDefaultMethod?

String?

Email to receive the order receipt. Leave null to use the recipient email (for [CrossmintCheckoutEmailRecipient]) or rely on the user entering an email inside the hosted page.

CrossmintCheckoutFiatPayment

Fiat payment configuration — credit card, Apple Pay, Google Pay. Set enabled: false to hide the fiat tab entirely.

Props

bool

required

Whether fiat payments are enabled.

String?

ISO 4217 currency code preselected in the fiat tab (e.g. "USD").

bool?

When false, hides the credit-card payment method. null keeps the project default.

bool?

When false, hides Apple Pay. null keeps the project default.

bool?

When false, hides Google Pay. null keeps the project default.

CrossmintCheckoutCryptoPayment

Crypto payment configuration — on-chain payment via a connected wallet. Set enabled: false to hide the crypto tab.

Props

bool

required

Whether crypto payments are enabled.

String?

Chain preselected in the crypto tab (e.g. "base", "solana"). Must appear in the payer’s [CrossmintCheckoutPayer.supportedChains] when a payer is attached.

String?

Currency preselected in the crypto tab (e.g. "USDC").

CrossmintCheckoutPayer?

Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.

CrossmintCheckoutPayer

Interface for apps to provide crypto wallet signing capabilities. Implement this to bridge your wallet into the checkout. Use CrossmintEvmWalletCheckoutPayer for a ready-made EVM adapter.

Properties

String

Current wallet address.

String

Chain the wallet is initially connected on.

List<String>

Chains the wallet can sign transactions on. The hosted checkout only offers chains that appear here.

String?

Optional wallet provider identifier (e.g. “metamask”, “coinbase”). Returns null if not applicable.

Methods

Future<CrossmintCheckoutTransactionResult>

Signs and broadcasts a serialized transaction. Return [CrossmintCheckoutTransactionSuccess] with the transaction id on success, or [CrossmintCheckoutTransactionFailure] with a user-facing message on failure.

Show parameters

String

required

Future<void>

Switches the wallet to [chain]. Called by the hosted page when the user changes chain in the UI.

Show parameters

String

required

Future<String>?

Optional — return null if message signing is not supported.

Show parameters

String

required

CrossmintEvmWalletCheckoutPayer

Ready-made adapter that bridges a CrossmintEvmWallet into the checkout payer contract. Handles transaction signing and chain switching automatically.

Props

CrossmintEvmWallet

required

List<String>?

String?

Usage

// Bridge a CrossmintEvmWallet into the checkout payer contract.
// `walletController` is a CrossmintWalletController with a loaded wallet.
final wallet = walletController.createEvmWallet();

final payer = CrossmintEvmWalletCheckoutPayer(
  wallet: wallet,
  supportedChains: ['base', 'ethereum', 'polygon'],
);

CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: yourOrder,
    payment: CrossmintCheckoutPayment(
      crypto: CrossmintCheckoutCryptoPayment(
        enabled: true,
        payer: payer,
      ),
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
    ),
  ),
)

Recipients

Sealed type for who receives the purchased asset. Three variants: CrossmintCheckoutEmailRecipient, CrossmintCheckoutWalletRecipient, and CrossmintCheckoutPhysicalRecipient.

Usage

// Email recipient (mints to Crossmint-managed wallet)
CrossmintCheckoutEmailRecipient(
  email: 'buyer@example.com',
)

// External wallet recipient
CrossmintCheckoutWalletRecipient(
  walletAddress: '0x1234...abcd',
)

// Physical-only recipient (no on-chain asset)
CrossmintCheckoutPhysicalRecipient(
  email: 'buyer@example.com',
  physicalAddress: CrossmintCheckoutPhysicalAddress(
    name: 'Jane Doe',
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94105',
    country: 'US',
  ),
)

CrossmintCheckoutAppearance

UI customization for the hosted checkout page — CSS custom properties, rules targeting specific elements, and custom web fonts.

Props

Map<String, Object?>?

CSS custom properties for theming (e.g. {'colorPrimary': '#0F172A'}).

Map<String, Object?>?

CSS rules for specific checkout elements (e.g. {'.Input': {'borderColor': '#CBD5E1'}}).

List<Map<String, String>>?

Custom font definitions (e.g. [{'cssSrc': 'https://fonts.googleapis.com/...'}]).

Usage

CrossmintCheckoutAppearance(
  variables: {
    'colorPrimary': '#0F172A',
    'borderRadius': '8px',
    'fontFamily': 'Inter, sans-serif',
  },
  rules: {
    '.Input': {'borderColor': '#CBD5E1'},
    '.Tab--selected': {'backgroundColor': '#0F172A'},
  },
  fonts: [
    {'cssSrc': 'https://fonts.googleapis.com/css2?family=Inter'},
  ],
)

CrossmintCheckoutTransactionResult

Sealed result type from CrossmintCheckoutPayer.signAndSendTransaction() — either CrossmintCheckoutTransactionSuccess (with txId) or CrossmintCheckoutTransactionFailure (with errorMessage).

CrossmintCheckoutDiagnostic

Structured runtime signal emitted by the embedded checkout widget. Covers blocked navigations, malformed messages, WebView resource errors, and console warnings/errors from the hosted page.

Props

String

required

Short machine-readable identifier (e.g. "navigation.blocked", "message.parse_failed").

String

required

Human-readable description of the diagnostic.

CrossmintCheckoutDiagnosticSeverity

required

Severity classification — one of [CrossmintCheckoutDiagnosticSeverity]: info (interesting but not a problem, e.g. user closed the hosted modal), warning (likely recoverable — surface in dev / staging), error (hosted flow hit a problem that may affect checkout). Pass to logging infrastructure accordingly.

String?

Hosted-page event associated with this diagnostic, if any (e.g. the original postMessage event name that failed to parse).

Uri?

URL associated with this diagnostic — set for navigation-related diagnostics (blocked navigations, resource errors).

Map<String, Object?>

Extra structured context for the diagnostic. Keys are stable — safe to forward to logging.

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

CrossmintCheckoutConfig

Props

CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

Props

Usage

CrossmintCheckoutLineItem

Usage

CrossmintCheckoutPayment

Props

CrossmintCheckoutFiatPayment

Props

CrossmintCheckoutCryptoPayment

Props

CrossmintCheckoutPayer

Properties

Methods

CrossmintEvmWalletCheckoutPayer

Props

Usage

Recipients

Usage

CrossmintCheckoutAppearance

Props

Usage

CrossmintCheckoutTransactionResult

CrossmintCheckoutDiagnostic

Props

​CrossmintCheckoutConfig

​Props

​CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

​Props

​Usage

​CrossmintCheckoutLineItem

​Usage

​CrossmintCheckoutPayment

​Props

​CrossmintCheckoutFiatPayment

​Props

​CrossmintCheckoutCryptoPayment

​Props

​CrossmintCheckoutPayer

​Properties

​Methods

​CrossmintEvmWalletCheckoutPayer

​Props

​Usage

​Recipients

​Usage

​CrossmintCheckoutAppearance

​Props

​Usage

​CrossmintCheckoutTransactionResult

​CrossmintCheckoutDiagnostic

​Props

CrossmintCheckoutConfig

Props

CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

Props

Usage

CrossmintCheckoutLineItem

Usage

CrossmintCheckoutPayment

Props

CrossmintCheckoutFiatPayment

Props

CrossmintCheckoutCryptoPayment

Props

CrossmintCheckoutPayer

Properties

Methods

CrossmintEvmWalletCheckoutPayer

Props

Usage

Recipients

Usage

CrossmintCheckoutAppearance

Props

Usage

CrossmintCheckoutTransactionResult

CrossmintCheckoutDiagnostic

Props