Skip to main content

​
Properties

The Embedded Checkout component supports two modes of operation:
  1. New Order Mode: Create orders client-side by passing lineItems, recipient, and other order details directly to the component.
  2. Existing Order Mode: Use orders created server-side by passing orderId and clientSecret to the component.
Use Existing Order Mode when you need server-side order creation for enhanced security, custom business logic, or when integrating with the Headless API.

​
Existing Order Properties

Use these properties when working with orders created server-side via the Create Order API.
​
orderId
string
The unique identifier of an existing order created via the server-side API. When provided, the checkout will load and process this existing order instead of creating a new one.
<CrossmintEmbeddedCheckout
  orderId="order_abc123"
  clientSecret="secret_xyz789"
  payment={{
    crypto: { enabled: true },
    fiat: { enabled: true }
  }}
/>
The payment object is still required when using existing orders to configure which payment methods are enabled in the checkout UI.
When using orderId, do not pass lineItems, recipient, or locale as these are already defined in the server-side order.
​
clientSecret
string
Secret token associated with the order for additional security. This is returned when creating an order via the server-side API.
The clientSecret helps ensure that only authorized clients can access and complete the order.

​
New Order Properties

Use these properties when creating orders directly in the client.
​
lineItems
object | array
required
Specifies the assets to purchase. Can be a single item or array of items. Required when creating a new order (not used with orderId).
​
collectionLocator
string
Collection identifier in one of these formats:
  • crossmint:<_YOUR_COLLECTION_ID_>[:_TEMPLATE_ID_] - For collections created in Crossmint Console
    • Template ID is optional and requires template minting to be enabled
    • If template minting is disabled and a template ID is provided, the mint will select a template randomly
  • <blockchain>:<contract-address> - For collections using direct contract addresses (e.g., polygon-amoy:0xF3d2d7b5666f579DcE385b2d53c54AB1b09Ef563)
When using template minting, append the templateId to the collection locator: crossmint:collectionId:templateId. Template minting must be enabled in the Crossmint Console or the mint will select a template randomly. See the Mint to Specific Template guide for details on enabling template minting and error handling.
​
tokenLocator
string
For secondary sales (buying existing assets). Token identifier in one of these formats:
  • EVM chains: <blockchain>:<contractAddress>:<tokenId>
  • Solana: <blockchain>:<tokenAddress>
Using tokenLocator doesn’t require registering the collection in Crossmint Console.
Use either collectionLocator (for primary sales) or tokenLocator (for secondary sales), not both.
​
callData
object
Arguments passed to your contract’s mint function:
Solidity
// Example mint function
function mint(
  address to,  // Auto-filled by Crossmint
  uint256 quantity,
  uint256 totalPrice
) public payable {
  // ...
}
Parameter names must match your contract’s function arguments exactly.
Do not pass the recipient argument (e.g. to) in callData. Crossmint handles this automatically.
​
recipient
object
Delivery details for the assets. You must specify either email OR wallet address, not both. Only used when creating new orders (not used with orderId).
​
email
string
Assets delivered to user’s Crossmint wallet linked to this email
​
walletAddress
string
Assets delivered directly to this blockchain address
When not provided, user will be prompted during checkout.
​
locale
string
Sets the checkout interface language. Only used when creating new orders (not used with orderId).en-US de-DE es-ES fr-FR it-IT ja-JP ko-KR pt-PT ru-RU th-TH tr-TR uk-UA vi-VN zh-CN zh-TW Klingon

​
Common Properties

These properties can be used with both new orders and existing orders.
​
payment
object
required
Configuration for payment methods.
​
crypto
object
required
Crypto payment settings:
{
  enabled: true,  // Enable/disable crypto payments
  defaultChain?: string, // Optional: e.g., "ethereum", "polygon", "solana"
  defaultCurrency?: string // Optional: e.g., "eth", "usdc"
}
For the complete list of supported chains, see Supported Chains.
​
fiat
object
required
Card & wallet payment settings:
{
  enabled: true,  // Enable/disable fiat payments
  defaultCurrency?: string,  // Optional: e.g., "usd", "eur", "gbp"
  allowedMethods: {
    card: boolean,       // Credit/debit cards
    applePay: boolean,   // Apple Pay
    googlePay: boolean   // Google Pay
  }
}
Crossmint supports multiple fiat currencies. Contact your account manager for the complete list of available currencies.
Embedded Checkout supports additional payment method customization. See our Embedded Checkout payment methods guide for details.
​
receiptEmail
string
Optional email address where purchase receipt will be sent
​
defaultMethod
string
Sets the default payment tab: fiat or crypto
​
appearance
Customization options for the checkout UI. See our UI Customization guide for complete details.Notable appearance options:
  • Hide destination input: rules.DestinationInput.display: "hidden"
  • Hide receipt email input: rules.ReceiptEmailInput.display: "hidden"
If inputs are hidden, you must provide the corresponding values via recipient/payment props.

​
React Hooks

The following React hooks are available for use with the Embedded Checkout:
​
useCrossmintCheckout
function
The useCrossmintCheckout hook is used to access the current order and checkout state.
All Crossmint hooks must be used within components wrapped by both CrossmintProvider and CrossmintCheckoutProvider:
<CrossmintProvider apiKey="YOUR_API_KEY">
    <CrossmintCheckoutProvider>
        <YourComponent /> {/* Hooks can be used here */}
    </CrossmintCheckoutProvider>
</CrossmintProvider>
The following properties are available from the useCrossmintCheckout hook:
​
order
object
The current order object containing all order details including order ID, phase, line items, quote, and delivery information.
const { order } = useCrossmintCheckout();
For the complete Order object schema, see the Get Order API reference.To understand order phases and lifecycle, see the Order Lifecycle guides.