Skip to main content
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

order
CrossmintCheckoutOrder
required
Order to check out — either a [CrossmintCheckoutNewOrder] built from line items, or a [CrossmintCheckoutExistingOrder] referencing an already-created order by id.
payment
CrossmintCheckoutPayment
required
Payment method configuration — fiat, crypto, and default method.
appearance
CrossmintCheckoutAppearance?
Optional appearance customization — CSS variables, rules, fonts.
jwt
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

lineItems
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.
recipient
CrossmintCheckoutRecipient?
Optional recipient for the order. When omitted, the hosted checkout collects recipient details from the buyer.
locale
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.
metadata
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

fiat
CrossmintCheckoutFiatPayment?
Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.
crypto
CrossmintCheckoutCryptoPayment?
Crypto payment configuration — null disables the crypto tab.
defaultMethod
String?
Raw default payment method string. Prefer [defaultMethodType] for compile-time safety. When both are set, [defaultMethodType] wins.
defaultMethodType
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].
receiptEmail
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

enabled
bool
required
Whether fiat payments are enabled.
defaultCurrency
String?
ISO 4217 currency code preselected in the fiat tab (e.g. "USD").
allowCard
bool?
When false, hides the credit-card payment method. null keeps the project default.
allowApplePay
bool?
When false, hides Apple Pay. null keeps the project default.
allowGooglePay
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

enabled
bool
required
Whether crypto payments are enabled.
defaultChain
String?
Chain preselected in the crypto tab (e.g. "base", "solana"). Must appear in the payer’s [CrossmintCheckoutPayer.supportedChains] when a payer is attached.
defaultCurrency
String?
Currency preselected in the crypto tab (e.g. "USDC").
payer
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

address
String
Current wallet address.
initialChain
String
Chain the wallet is initially connected on.
supportedChains
List<String>
Chains the wallet can sign transactions on. The hosted checkout only offers chains that appear here.
walletProviderKey
String?
Optional wallet provider identifier (e.g. “metamask”, “coinbase”). Returns null if not applicable.

Methods

signAndSendTransaction(serializedTransaction)
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.
switchChain(chain)
Future<void>
Switches the wallet to [chain]. Called by the hosted page when the user changes chain in the UI.
signMessage(message)
Future<String>?
Optional — return null if message signing is not supported.

CrossmintEvmWalletCheckoutPayer

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

Props

wallet
CrossmintEvmWallet
required
supportedChains
List<String>?
initialChain
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

variables
Map<String, Object?>?
CSS custom properties for theming (e.g. {'colorPrimary': '#0F172A'}).
rules
Map<String, Object?>?
CSS rules for specific checkout elements (e.g. {'.Input': {'borderColor': '#CBD5E1'}}).
fonts
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

code
String
required
Short machine-readable identifier (e.g. "navigation.blocked", "message.parse_failed").
message
String
required
Human-readable description of the diagnostic.
severity
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.
event
String?
Hosted-page event associated with this diagnostic, if any (e.g. the original postMessage event name that failed to parse).
uri
Uri?
URL associated with this diagnostic — set for navigation-related diagnostics (blocked navigations, resource errors).
details
Map<String, Object?>
Extra structured context for the diagnostic. Keys are stable — safe to forward to logging.