> ## Documentation Index
> Fetch the complete documentation index at: https://crossmint-devin-1787949784-wallet-docs-two-concept-model.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

> Flutter widgets for the Flutter SDK reference for Crossmint checkout

The Flutter SDK provides a WebView-based checkout widget that renders the Crossmint embedded checkout experience. Import it from `crossmint_flutter_ui.dart`.

***

## CrossmintEmbeddedCheckout

WebView-based checkout widget that renders the Crossmint embedded checkout experience inline. Communicates bidirectionally with the hosted checkout page for dynamic sizing, order updates, and crypto transaction signing.

### Props

<ResponseField name="apiKey" type="String" required>
  Crossmint API key.
</ResponseField>

<ResponseField name="config" type="CrossmintCheckoutConfig" required>
  Checkout configuration (order, payment, appearance).

  <Expandable title="properties">
    <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.
        </ResponseField>

        <ResponseField name="crypto" type="CrossmintCheckoutCryptoPayment?">
          Crypto payment configuration — null disables the crypto tab.
        </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>

    <ResponseField name="identityVerificationHandling" type="CrossmintIdentityVerificationHandling?">
      Optional takeover of the identity verification step. Requires a Crossmint deployment that understands the flag; against an older one it is ignored and checkout renders verification itself.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payer" type="CrossmintCheckoutPayer?">
  Optional crypto payer override for signing transactions within checkout.
</ResponseField>

<ResponseField name="checkoutController" type="CrossmintCheckoutController?">
  Optional reactive controller for checkout order state.
</ResponseField>

<ResponseField name="onOrderUpdated" type="void Function(Map<String, Object?> order)?">
  Called when the order state changes.
</ResponseField>

<ResponseField name="onOrderCreationFailed" type="void Function(String errorMessage)?">
  Called when order creation fails.
</ResponseField>

<ResponseField name="onDiagnostic" type="void Function(CrossmintCheckoutDiagnostic diagnostic)?">
  Called when the hosted checkout emits a runtime diagnostic.
</ResponseField>

<ResponseField name="loadingBuilder" type="CrossmintCheckoutLoadingBuilder?">
  Optional builder for the loading overlay rendered on top of the hosted checkout WebView while the page is loading. When `null`, the widget falls back to a Material `CircularProgressIndicator` inside a themed background container (the React Native Crossmint SDK parity default).
</ResponseField>

<ResponseField name="defaultHeight" type="double">
  Initial height before the hosted page reports its actual height.
</ResponseField>

### Usage

```dart theme={null}
final checkoutController = CrossmintCheckoutController();

CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: CrossmintCheckoutNewOrder.typed(
      lineItems: [
        CrossmintCheckoutLineItem.collection(
          collectionLocator: 'crossmint:collection-id',
          callData: {'quantity': 1},
        ),
      ],
    ),
    payment: CrossmintCheckoutPayment(
      fiat: CrossmintCheckoutFiatPayment(enabled: true),
      crypto: CrossmintCheckoutCryptoPayment(enabled: false),
    ),
  ),
  checkoutController: checkoutController,
  onOrderUpdated: (order) => print('Order: ${order['status']}'),
  onOrderCreationFailed: (error) => print('Error: $error'),
)
```

***

## CrossmintCheckoutController

Reactive controller for checkout order state, matching the official Crossmint RN SDK's `useCrossmintCheckout()` hook. Pass this to `CrossmintEmbeddedCheckout` to receive order updates as observable state.

### Properties

<ResponseField name="order" type="Map<String, Object?>?">
  The current order object from the checkout, or `null` if no order yet.
</ResponseField>

<ResponseField name="orderClientSecret" type="String?">
  The server-assigned client secret for the current order.
</ResponseField>

<ResponseField name="identityVerificationCredentials" type="CrossmintIdentityVerificationCredentials?">
  Verification credentials for the current order, or `null` when the order does not need identity verification. Pass these to `CrossmintIdentityVerification` when checkout runs with `identityVerificationHandling` set to external.

  <Expandable title="properties">
    <ResponseField name="inquiryId" type="String" required>
      Provider-side inquiry identifier.
    </ResponseField>

    <ResponseField name="sessionToken" type="String?">
      Optional provider session token.
    </ResponseField>
  </Expandable>
</ResponseField>

### Methods

<ResponseField name="updateOrder(data)" type="void">
  Updates the order state from a checkout `order:updated` event.

  <Expandable title="parameters">
    <ResponseField name="data" type="Map<String, Object?>" required />
  </Expandable>
</ResponseField>

<ResponseField name="clear()" type="void">
  Clears the order state.
</ResponseField>

### Usage

```dart theme={null}
final controller = CrossmintCheckoutController();

// Pass to the widget:
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: yourCheckoutConfig,
  checkoutController: controller,
)

// Listen reactively:
ListenableBuilder(
  listenable: controller,
  builder: (context, _) {
    final order = controller.order;
    if (order == null) return const Text('No order yet');
    return Text('Status: ${order['status']}');
  },
)
```

***

## CrossmintIdentityVerification

WebView-based widget that renders Crossmint's hosted identity verification step in your own route. Use it when checkout runs with `identityVerificationHandling: CrossmintIdentityVerificationHandling.external` — checkout then stops rendering verification itself, and the buyer cannot finish unless you mount this widget with the credentials from `CrossmintCheckoutController.identityVerificationCredentials`.

### Props

<ResponseField name="apiKey" type="String" required>
  Crossmint API key. Resolves staging versus production and is forwarded to the hosted page, matching the React Native SDK and the other Crossmint widgets in this package.
</ResponseField>

<ResponseField name="credentials" type="CrossmintIdentityVerificationCredentials" required>
  Credentials for the verification session.

  <Expandable title="properties">
    <ResponseField name="inquiryId" type="String" required>
      Provider-side inquiry identifier.
    </ResponseField>

    <ResponseField name="sessionToken" type="String?">
      Optional provider session token.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="locale" type="String?">
  Optional locale tag. Must be one the hosted page recognises, for example `en-US`, `es-ES`, `pt-PT`. An unrecognised tag is not ignored: the page rejects it and reports a non-retriable `invalidConfiguration` error, which leaves the buyer with a dead screen.
</ResponseField>

<ResponseField name="onReady" type="void Function()?">
  Called when the verification UI is ready.
</ResponseField>

<ResponseField name="onComplete" type="void Function(CrossmintIdentityVerificationStatus status)?">
  Called with the outcome when verification finishes.
</ResponseField>

<ResponseField name="onCancel" type="void Function()?">
  Called when the buyer abandons verification.
</ResponseField>

<ResponseField name="onError" type="void Function(CrossmintIdentityVerificationError error)?">
  Called when verification cannot run or continue.
</ResponseField>

<ResponseField name="loadingBuilder" type="CrossmintIdentityVerificationLoadingBuilder?">
  Optional builder for the loading overlay. Falls back to a themed Material spinner, matching `CrossmintPaymentMethodManagement`.
</ResponseField>

<ResponseField name="defaultHeight" type="double">
  Initial height before the hosted page reports its actual height.
</ResponseField>

### Usage

```dart theme={null}
// Run checkout with the verification step handed to you.
CrossmintEmbeddedCheckout(
  apiKey: 'YOUR_CLIENT_API_KEY',
  config: CrossmintCheckoutConfig(
    order: yourOrder,
    payment: yourPayment,
    identityVerificationHandling:
        CrossmintIdentityVerificationHandling.external,
  ),
  checkoutController: _controller,
)

// Then mount the verification widget on your own route when the
// controller reports that the order needs it.
final credentials = _controller.identityVerificationCredentials;
if (credentials != null)
  CrossmintIdentityVerification(
    apiKey: 'YOUR_CLIENT_API_KEY',
    credentials: credentials,
    onComplete: (status) {
      debugPrint('verification: ${status.wireValue}');
    },
    onError: (error) {
      debugPrint('verification failed: ${error.message}');
    },
  )
```