> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

> Configuration and data models for the Flutter SDK reference for Crossmint checkout

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

<ResponseField name="order" type="CrossmintCheckoutOrder" required>
  Order to check out — either a \[CrossmintCheckoutNewOrder] built from line items, or a \[CrossmintCheckoutExistingOrder] referencing an already-created order by id.
</ResponseField>

<ResponseField name="payment" type="CrossmintCheckoutPayment" required>
  Payment method configuration — fiat, crypto, and default method.

  <Expandable title="properties">
    <ResponseField name="fiat" type="CrossmintCheckoutFiatPayment?">
      Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

      <Expandable title="properties">
        <ResponseField name="enabled" type="bool" required>
          Whether fiat payments are enabled.
        </ResponseField>

        <ResponseField name="defaultCurrency" type="String?">
          ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
        </ResponseField>

        <ResponseField name="allowCard" type="bool?">
          When `false`, hides the credit-card payment method. `null` keeps the project default.
        </ResponseField>

        <ResponseField name="allowApplePay" type="bool?">
          When `false`, hides Apple Pay. `null` keeps the project default.
        </ResponseField>

        <ResponseField name="allowGooglePay" type="bool?">
          When `false`, hides Google Pay. `null` keeps the project default.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
      Crypto payment configuration — null disables the crypto tab.

      <Expandable title="properties">
        <ResponseField name="enabled" type="bool" required>
          Whether crypto payments are enabled.
        </ResponseField>

        <ResponseField name="defaultChain" type="String?">
          Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
        </ResponseField>

        <ResponseField name="defaultCurrency" type="String?">
          Currency preselected in the crypto tab (e.g. `"USDC"`).
        </ResponseField>

        <ResponseField name="payer" type="CrossmintCheckoutPayer?">
          Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="defaultMethod" type="String?">
      Raw default payment method string. Prefer \[defaultMethodType] for compile-time safety. When both are set, \[defaultMethodType] wins.
    </ResponseField>

    <ResponseField name="defaultMethodType" type="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].
    </ResponseField>

    <ResponseField name="receiptEmail" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="appearance" type="CrossmintCheckoutAppearance?">
  Optional appearance customization — CSS variables, rules, fonts.

  <Expandable title="properties">
    <ResponseField name="variables" type="Map<String, Object?>?">
      CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).
    </ResponseField>

    <ResponseField name="rules" type="Map<String, Object?>?">
      CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).
    </ResponseField>

    <ResponseField name="fonts" type="List<Map<String, String>>?">
      Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="jwt" type="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.
</ResponseField>

***

## CrossmintCheckoutNewOrder / CrossmintCheckoutExistingOrder

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

### Props

<ResponseField name="lineItems" type="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.
</ResponseField>

<ResponseField name="recipient" type="CrossmintCheckoutRecipient?">
  Optional recipient for the order. When omitted, the hosted checkout collects recipient details from the buyer.
</ResponseField>

<ResponseField name="locale" type="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.
</ResponseField>

<ResponseField name="metadata" type="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.
</ResponseField>

### Usage

```dart theme={null}
// 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

```dart theme={null}
// 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

<ResponseField name="fiat" type="CrossmintCheckoutFiatPayment?">
  Fiat (card, Apple Pay, Google Pay) configuration — null disables the fiat tab entirely.

  <Expandable title="properties">
    <ResponseField name="enabled" type="bool" required>
      Whether fiat payments are enabled.
    </ResponseField>

    <ResponseField name="defaultCurrency" type="String?">
      ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
    </ResponseField>

    <ResponseField name="allowCard" type="bool?">
      When `false`, hides the credit-card payment method. `null` keeps the project default.
    </ResponseField>

    <ResponseField name="allowApplePay" type="bool?">
      When `false`, hides Apple Pay. `null` keeps the project default.
    </ResponseField>

    <ResponseField name="allowGooglePay" type="bool?">
      When `false`, hides Google Pay. `null` keeps the project default.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
  Crypto payment configuration — null disables the crypto tab.

  <Expandable title="properties">
    <ResponseField name="enabled" type="bool" required>
      Whether crypto payments are enabled.
    </ResponseField>

    <ResponseField name="defaultChain" type="String?">
      Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
    </ResponseField>

    <ResponseField name="defaultCurrency" type="String?">
      Currency preselected in the crypto tab (e.g. `"USDC"`).
    </ResponseField>

    <ResponseField name="payer" type="CrossmintCheckoutPayer?">
      Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="defaultMethod" type="String?">
  Raw default payment method string. Prefer \[defaultMethodType] for compile-time safety. When both are set, \[defaultMethodType] wins.
</ResponseField>

<ResponseField name="defaultMethodType" type="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].
</ResponseField>

<ResponseField name="receiptEmail" type="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.
</ResponseField>

***

## CrossmintCheckoutFiatPayment

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

### Props

<ResponseField name="enabled" type="bool" required>
  Whether fiat payments are enabled.
</ResponseField>

<ResponseField name="defaultCurrency" type="String?">
  ISO 4217 currency code preselected in the fiat tab (e.g. `"USD"`).
</ResponseField>

<ResponseField name="allowCard" type="bool?">
  When `false`, hides the credit-card payment method. `null` keeps the project default.
</ResponseField>

<ResponseField name="allowApplePay" type="bool?">
  When `false`, hides Apple Pay. `null` keeps the project default.
</ResponseField>

<ResponseField name="allowGooglePay" type="bool?">
  When `false`, hides Google Pay. `null` keeps the project default.
</ResponseField>

***

## CrossmintCheckoutCryptoPayment

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

### Props

<ResponseField name="enabled" type="bool" required>
  Whether crypto payments are enabled.
</ResponseField>

<ResponseField name="defaultChain" type="String?">
  Chain preselected in the crypto tab (e.g. `"base"`, `"solana"`). Must appear in the payer's \[CrossmintCheckoutPayer.supportedChains] when a payer is attached.
</ResponseField>

<ResponseField name="defaultCurrency" type="String?">
  Currency preselected in the crypto tab (e.g. `"USDC"`).
</ResponseField>

<ResponseField name="payer" type="CrossmintCheckoutPayer?">
  Optional app-side signer bridge. When null, the hosted page presents its own wallet-connect flow.
</ResponseField>

***

## 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

<ResponseField name="address" type="String">
  Current wallet address.
</ResponseField>

<ResponseField name="initialChain" type="String">
  Chain the wallet is initially connected on.
</ResponseField>

<ResponseField name="supportedChains" type="List<String>">
  Chains the wallet can sign transactions on. The hosted checkout only offers chains that appear here.
</ResponseField>

<ResponseField name="walletProviderKey" type="String?">
  Optional wallet provider identifier (e.g. "metamask", "coinbase"). Returns null if not applicable.
</ResponseField>

### Methods

<ResponseField name="signAndSendTransaction(serializedTransaction)" type="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.

  <Expandable title="parameters">
    <ResponseField name="serializedTransaction" type="String" required />
  </Expandable>
</ResponseField>

<ResponseField name="switchChain(chain)" type="Future<void>">
  Switches the wallet to \[chain]. Called by the hosted page when the user changes chain in the UI.

  <Expandable title="parameters">
    <ResponseField name="chain" type="String" required />
  </Expandable>
</ResponseField>

<ResponseField name="signMessage(message)" type="Future<String>?">
  Optional — return null if message signing is not supported.

  <Expandable title="parameters">
    <ResponseField name="message" type="String" required />
  </Expandable>
</ResponseField>

***

## CrossmintEvmWalletCheckoutPayer

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

### Props

<ResponseField name="wallet" type="CrossmintEvmWallet" required />

<ResponseField name="supportedChains" type="List<String>?" />

<ResponseField name="initialChain" type="String?" />

### Usage

```dart theme={null}
// 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

```dart theme={null}
// 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

<ResponseField name="variables" type="Map<String, Object?>?">
  CSS custom properties for theming (e.g. `{'colorPrimary': '#0F172A'}`).
</ResponseField>

<ResponseField name="rules" type="Map<String, Object?>?">
  CSS rules for specific checkout elements (e.g. `{'.Input': {'borderColor': '#CBD5E1'}}`).
</ResponseField>

<ResponseField name="fonts" type="List<Map<String, String>>?">
  Custom font definitions (e.g. `[{'cssSrc': 'https://fonts.googleapis.com/...'}]`).
</ResponseField>

### Usage

```dart theme={null}
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

<ResponseField name="code" type="String" required>
  Short machine-readable identifier (e.g. `"navigation.blocked"`, `"message.parse_failed"`).
</ResponseField>

<ResponseField name="message" type="String" required>
  Human-readable description of the diagnostic.
</ResponseField>

<ResponseField name="severity" type="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.
</ResponseField>

<ResponseField name="event" type="String?">
  Hosted-page event associated with this diagnostic, if any (e.g. the original postMessage event name that failed to parse).
</ResponseField>

<ResponseField name="uri" type="Uri?">
  URL associated with this diagnostic — set for navigation-related diagnostics (blocked navigations, resource errors).
</ResponseField>

<ResponseField name="details" type="Map<String, Object?>">
  Extra structured context for the diagnostic. Keys are stable — safe to forward to logging.
</ResponseField>