Widgets

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

String

required

Crossmint API key.

CrossmintCheckoutConfig

required

Checkout configuration (order, payment, appearance).

Show properties

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.

CrossmintCheckoutCryptoPayment?

Crypto payment configuration — null disables the crypto tab.

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.

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.

CrossmintCheckoutPayer?

Optional crypto payer override for signing transactions within checkout.

CrossmintCheckoutController?

Optional reactive controller for checkout order state.

void Function(Map<String, Object?> order)?

Called when the order state changes.

void Function(String errorMessage)?

Called when order creation fails.

void Function(CrossmintCheckoutDiagnostic diagnostic)?

Called when the hosted checkout emits a runtime diagnostic.

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).

double

Initial height before the hosted page reports its actual height.

Usage

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

Map<String, Object?>?

The current order object from the checkout, or null if no order yet.

String?

The server-assigned client secret for the current order.

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.

Show properties

String

required

Provider-side inquiry identifier.

String?

Optional provider session token.

Methods

void

Updates the order state from a checkout order:updated event.

Show parameters

Map<String, Object?>

required

void

Clears the order state.

Usage

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

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.

CrossmintIdentityVerificationCredentials

required

Credentials for the verification session.

Show properties

String

required

Provider-side inquiry identifier.

String?

Optional provider session token.

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.

void Function()?

Called when the verification UI is ready.

void Function(CrossmintIdentityVerificationStatus status)?

Called with the outcome when verification finishes.

void Function()?

Called when the buyer abandons verification.

void Function(CrossmintIdentityVerificationError error)?

Called when verification cannot run or continue.

CrossmintIdentityVerificationLoadingBuilder?

Optional builder for the loading overlay. Falls back to a themed Material spinner, matching CrossmintPaymentMethodManagement.

double

Initial height before the hosted page reports its actual height.

Usage

// 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}');
    },
  )

Introduction

Hosted (pop-up)

Embedded

Headless (API)

Advanced Guides

API Reference

CrossmintEmbeddedCheckout

Props

Usage

CrossmintCheckoutController

Properties

Methods

Usage

CrossmintIdentityVerification

Props

Usage

​CrossmintEmbeddedCheckout

​Props

​Usage

​CrossmintCheckoutController

​Properties

​Methods

​Usage

​CrossmintIdentityVerification

​Props

​Usage

CrossmintEmbeddedCheckout

Props

Usage

CrossmintCheckoutController

Properties

Methods

Usage

CrossmintIdentityVerification

Props

Usage