Digital Asset Checkout Integration

If you are using our previous version of the hosted checkout button, please refer to the old quickstart guide

Introduction

In this guide, you will create a web app with Next.js which allows customers to buy digital assets with credit card and crypto payments using Crossmint’s hosted checkout. We will add a button that opens a checkout hosted in a pop-up or new tab.

From Crossmint

Create a developer account in the Staging Console.
Create a new collection or import yours into the console, and have your collectionId ready.
- Make sure you follow the maximum prices for collections set in staging outlined here.
Create a client-side API key with the orders.create scope enabled. More info on creating API keys here.

To integrate in production/mainnet, you'll also need to complete account and collection verification. More information in the production launch guide.

For Marketplaces and Launchpads: You do not need to create a collection (skip Step 2).

Simply use tokenLocator instead of collectionLocator in the examples. It is recommended to test tokenlocator in the production environment.

See Marketplaces & Launchpads guide for more secondary-sale specific details.

Integration Steps

This guide will start from scratch with an empty Next.js application. You'll install the required @crossmint/client-sdk-react-ui dependency and add the embedded checkout component. To get started:

Set up the Project

Create a new Next.js application

npx create-next-app@latest

If you see this message, type y and press Enter to proceed:

Need to install the following packages:
  create-next-app@latest
Ok to proceed? (y)

Name your app `crossmint-embedded-checkout-demo` and accept the default options

What is your project named? crossmint-embedded-checkout-demo
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? No
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias? No

Change into the directory created in previous steps

cd crossmint-embedded-checkout-demo

Install @crossmint/client-sdk-react-ui

npm i @crossmint/client-sdk-react-ui

Open the project in your preferred code editor

Basic Integration

This quickstart guide focuses on NFT Collections/Drops (primary sales), but Crossmint also supports marketplace integrations.

Add environment variables

Create .env.local in your project root:

NEXT_PUBLIC_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"    # From API Keys page
NEXT_PUBLIC_COLLECTION_ID="_YOUR_COLLECTION_ID_"      # From Collection details page

Create the checkout page

Create /src/app/page.tsx with:

"use client";

import { CrossmintProvider, CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    return (
        <CrossmintProvider apiKey={clientApiKey}>
            <CrossmintHostedCheckout
                lineItems={{
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                }}
                payment={{
                    crypto: { enabled: true },
                    fiat: { enabled: true },
                }}
            />
        </CrossmintProvider>
    );
}

Run your app

Navigate to the directory your package.json is to run the app

cd hosted-checkout/crossmint-hosted-checkout-demo

npm run dev

Visit http://localhost:3000 to see your checkout!

(Optional) Advanced Integration

Need purchase tracking, multiple line items, or more customization? Here’s a complete setup with additional features:

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            },
        ]}
        appearance={{
            display: "new-tab", // Open in a new tab
            overlay: {
                enabled: false, // Disable overlay
            },
            theme: {
                button: "dark", // Dark button theme
                checkout: "dark", // Dark checkout theme
            },
        }}
        payment={{
            crypto: {
                enabled: true,
                defaultChain: "polygon", // Set preferred blockchain
                defaultCurrency: "matic", // Set preferred crypto
            },
            fiat: {
                enabled: true,
                defaultCurrency: "usd", // Set preferred fiat currency
            },
            receiptEmail: "receipt@example.com", // Optional: Set receipt email
        }}
        recipient={{
            email: "buyer@example.com", // Digital assets will be delivered to this email's wallet
            // Or use walletAddress: "0x..." for direct delivery
        }}
        locale="en-US" // Set interface language
    />
);

}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            },
        ]}
        appearance={{
            display: "new-tab", // Open in a new tab
            overlay: {
                enabled: false, // Disable overlay
            },
            theme: {
                button: "dark", // Dark button theme
                checkout: "dark", // Dark checkout theme
            },
        }}
        payment={{
            crypto: {
                enabled: true,
                defaultChain: "polygon", // Set preferred blockchain
                defaultCurrency: "matic", // Set preferred crypto
            },
            fiat: {
                enabled: true,
                defaultCurrency: "usd", // Set preferred fiat currency
            },
            receiptEmail: "receipt@example.com", // Optional: Set receipt email
        }}
        recipient={{
            email: "buyer@example.com", // Digital assets will be delivered to this email's wallet
            // Or use walletAddress: "0x..." for direct delivery
        }}
        locale="en-US" // Set interface language
    />
);

}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    // For Solana NFTs
                    tokenLocator: "solana:4oDd...x6NC",
                    callData: {
                        totalPrice: "0.1",
                        buyerCreatorRoyaltyPercent: 100
                    }
                },
                {
                    // For EVM NFTs (Ethereum, Polygon, etc)
                    tokenLocator: "ethereum:0xbC...307e:7777",
                    callData: {
                        totalPrice: "0.2"
                    }
                }
            ]}
            appearance={{
                display: "new-tab", // Open in a new tab
                overlay: {
                    enabled: false, // Disable overlay
                },
                theme: {
                    button: "dark", // Dark button theme
                    checkout: "dark", // Dark checkout theme
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "solana", // Set preferred blockchain
                    defaultCurrency: "sol", // Set preferred crypto
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd", // Set preferred fiat currency
                },
            }}
            locale="en-US" // Set interface language
        />
    );
}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

This advanced example showcases: - Multiple NFTs in one checkout - Purchase status tracking - Preferred payment methods and currencies - Email-based digital asset delivery - Language settings Learn more in our guides: - Payment Methods - Multi-purchases

React Hooks

Testing Your Integration

This demo uses the staging environment:

Use test credit cards for payments
Get test USDC from our faucet
Check price limits for staging

All Set!

You’ve successfully integrated a hosted checkout with credit card and crypto payment methods!

Remember this demo is built on staging, so the digital assets will show up on the testnets. To launch on production, check the production launch checklist. You will need to contact Sales to enable the embedded checkout on production.

Next Steps

Customize the UI and Behavior Further

UI Customization

Learn how to customize the look and feel of the checkout button

Payment Methods

Configure available payment options for your users

React Hooks

Use React hooks to build custom checkout experiences

Advanced Topics

SDK Reference

Launch in Production

Localization

Multi-purchases

Marketplaces

On this page

Introduction
From Crossmint
Integration Steps
Set up the Project
Basic Integration
(Optional) Advanced Integration
Testing Your Integration
All Set!
Next Steps
Customize the UI and Behavior Further
Advanced Topics

If you are using our previous version of the hosted checkout button, please refer to the old quickstart guide

Introduction

From Crossmint

Create a developer account in the Staging Console.
Create a new collection or import yours into the console, and have your collectionId ready.
- Make sure you follow the maximum prices for collections set in staging outlined here.
Create a client-side API key with the orders.create scope enabled. More info on creating API keys here.

To integrate in production/mainnet, you'll also need to complete account and collection verification. More information in the production launch guide.

For Marketplaces and Launchpads: You do not need to create a collection (skip Step 2).

Simply use tokenLocator instead of collectionLocator in the examples. It is recommended to test tokenlocator in the production environment.

See Marketplaces & Launchpads guide for more secondary-sale specific details.

Integration Steps

This guide will start from scratch with an empty Next.js application. You'll install the required @crossmint/client-sdk-react-ui dependency and add the embedded checkout component. To get started:

Set up the Project

Create a new Next.js application

npx create-next-app@latest

If you see this message, type y and press Enter to proceed:

Need to install the following packages:
  create-next-app@latest
Ok to proceed? (y)

Name your app `crossmint-embedded-checkout-demo` and accept the default options

What is your project named? crossmint-embedded-checkout-demo
Would you like to use TypeScript? Yes
Would you like to use ESLint? Yes
Would you like to use Tailwind CSS? Yes
Would you like to use `src/` directory? No
Would you like to use App Router? (recommended) Yes
Would you like to customize the default import alias? No

Change into the directory created in previous steps

cd crossmint-embedded-checkout-demo

Install @crossmint/client-sdk-react-ui

npm i @crossmint/client-sdk-react-ui

Open the project in your preferred code editor

Basic Integration

This quickstart guide focuses on NFT Collections/Drops (primary sales), but Crossmint also supports marketplace integrations.

Add environment variables

Create .env.local in your project root:

NEXT_PUBLIC_CLIENT_API_KEY="_YOUR_CLIENT_API_KEY_"    # From API Keys page
NEXT_PUBLIC_COLLECTION_ID="_YOUR_COLLECTION_ID_"      # From Collection details page

Create the checkout page

Create /src/app/page.tsx with:

"use client";

import { CrossmintProvider, CrossmintHostedCheckout } from "@crossmint/client-sdk-react-ui";

export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    return (
        <CrossmintProvider apiKey={clientApiKey}>
            <CrossmintHostedCheckout
                lineItems={{
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                }}
                payment={{
                    crypto: { enabled: true },
                    fiat: { enabled: true },
                }}
            />
        </CrossmintProvider>
    );
}

Run your app

Navigate to the directory your package.json is to run the app

cd hosted-checkout/crossmint-hosted-checkout-demo

npm run dev

Visit http://localhost:3000 to see your checkout!

(Optional) Advanced Integration

Need purchase tracking, multiple line items, or more customization? Here’s a complete setup with additional features:

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            },
        ]}
        appearance={{
            display: "new-tab", // Open in a new tab
            overlay: {
                enabled: false, // Disable overlay
            },
            theme: {
                button: "dark", // Dark button theme
                checkout: "dark", // Dark checkout theme
            },
        }}
        payment={{
            crypto: {
                enabled: true,
                defaultChain: "polygon", // Set preferred blockchain
                defaultCurrency: "matic", // Set preferred crypto
            },
            fiat: {
                enabled: true,
                defaultCurrency: "usd", // Set preferred fiat currency
            },
            receiptEmail: "receipt@example.com", // Optional: Set receipt email
        }}
        recipient={{
            email: "buyer@example.com", // Digital assets will be delivered to this email's wallet
            // Or use walletAddress: "0x..." for direct delivery
        }}
        locale="en-US" // Set interface language
    />
);

}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();
    const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            },
        ]}
        appearance={{
            display: "new-tab", // Open in a new tab
            overlay: {
                enabled: false, // Disable overlay
            },
            theme: {
                button: "dark", // Dark button theme
                checkout: "dark", // Dark checkout theme
            },
        }}
        payment={{
            crypto: {
                enabled: true,
                defaultChain: "polygon", // Set preferred blockchain
                defaultCurrency: "matic", // Set preferred crypto
            },
            fiat: {
                enabled: true,
                defaultCurrency: "usd", // Set preferred fiat currency
            },
            receiptEmail: "receipt@example.com", // Optional: Set receipt email
        }}
        recipient={{
            email: "buyer@example.com", // Digital assets will be delivered to this email's wallet
            // Or use walletAddress: "0x..." for direct delivery
        }}
        locale="en-US" // Set interface language
    />
);

}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintHostedCheckout,
    useCrossmintCheckout,
} from "@crossmint/client-sdk-react-ui";

// Component with purchase tracking
function Checkout() {
    const { order } = useCrossmintCheckout();

    useEffect(() => {
        if (order && order.phase === "completed") {
            console.log("Purchase completed!");
            // Handle successful purchase
        }
    }, [order]);

    return (
        <CrossmintHostedCheckout
            lineItems={[
                {
                    // For Solana NFTs
                    tokenLocator: "solana:4oDd...x6NC",
                    callData: {
                        totalPrice: "0.1",
                        buyerCreatorRoyaltyPercent: 100
                    }
                },
                {
                    // For EVM NFTs (Ethereum, Polygon, etc)
                    tokenLocator: "ethereum:0xbC...307e:7777",
                    callData: {
                        totalPrice: "0.2"
                    }
                }
            ]}
            appearance={{
                display: "new-tab", // Open in a new tab
                overlay: {
                    enabled: false, // Disable overlay
                },
                theme: {
                    button: "dark", // Dark button theme
                    checkout: "dark", // Dark checkout theme
                },
            }}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "solana", // Set preferred blockchain
                    defaultCurrency: "sol", // Set preferred crypto
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd", // Set preferred fiat currency
                },
            }}
            locale="en-US" // Set interface language
        />
    );
}

// Main component with providers
export default function Home() {
    const clientApiKey = process.env.NEXT_PUBLIC_CLIENT_API_KEY as string;

    return (
        <div className="flex flex-col items-center justify-start min-h-screen p-6">
            <CrossmintProvider apiKey={clientApiKey}>
                <CrossmintCheckoutProvider>
                    <Checkout />
                </CrossmintCheckoutProvider>
            </CrossmintProvider>
        </div>
    );
}

React Hooks

Testing Your Integration

This demo uses the staging environment:

Use test credit cards for payments
Get test USDC from our faucet
Check price limits for staging

All Set!

You’ve successfully integrated a hosted checkout with credit card and crypto payment methods!

Next Steps

Customize the UI and Behavior Further

UI Customization

Learn how to customize the look and feel of the checkout button

Payment Methods

Configure available payment options for your users

React Hooks

Use React hooks to build custom checkout experiences

Advanced Topics

SDK Reference

Launch in Production

Localization

Multi-purchases

Marketplaces

On this page

Introduction
From Crossmint
Integration Steps
Set up the Project
Basic Integration
(Optional) Advanced Integration
Testing Your Integration
All Set!
Next Steps
Customize the UI and Behavior Further
Advanced Topics

​Introduction

​From Crossmint

​Integration Steps

​Set up the Project

​Basic Integration

​(Optional) Advanced Integration

​Testing Your Integration

​All Set!

​Next Steps

​Customize the UI and Behavior Further

UI Customization

Payment Methods

React Hooks

​Advanced Topics

SDK Reference

Launch in Production

Localization

Multi-purchases

Marketplaces

Changelog

​Introduction

​From Crossmint

​Integration Steps

​Set up the Project

​Basic Integration

​(Optional) Advanced Integration

​Testing Your Integration

​All Set!

​Next Steps

​Customize the UI and Behavior Further

UI Customization

Payment Methods

React Hooks

​Advanced Topics

SDK Reference

Launch in Production

Localization

Multi-purchases

Marketplaces

Introduction

From Crossmint

Integration Steps

Set up the Project

Basic Integration

(Optional) Advanced Integration

Testing Your Integration

All Set!

Next Steps

Customize the UI and Behavior Further

Advanced Topics

Introduction

From Crossmint

Integration Steps

Set up the Project

Basic Integration

(Optional) Advanced Integration

Testing Your Integration

All Set!

Next Steps

Customize the UI and Behavior Further

Advanced Topics