React - Webview

Embed a card checkout for NFTs or tokens into a web app in under 5 minutes

You will build this demo

​

Introduction

In this guide, you will create a web app with Next.js which allows customers to buy NFTs or tokens with credit card and crypto payments, using Crossmint’s embedded checkout.

If you want to get started immediately, you can clone a repo with a functioning embedded checkout here: https://github.com/Crossmint/crossmint-embedded-demo. If you want to get started step by step, continue following the guide below.

NFTs

​

From Crossmint

1. Create a developer account in the Staging Console.
2. 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.
3. 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.

Memecoins & Tokens

​

Important Notes

Compliance Checks

Crossmint runs compliance checks on all tokens to ensure they do not qualify as securities or currencies under applicable regulations. Transactions for tokens that are determined to be too similar to securities or currencies will fail.

Supported Tokens

Memecoin checkout supports the Solana and Base networks. You can check which tokens are supported by using the fungibleCheckoutAvailable endpoint. A more in depth guide on token support is here.

Delivery to External Wallets Only

Memecoin checkout only delivers memecoins to EOAs (Externally Owned Accounts), not Crossmint supported delivery solutions, such as on-the-fly wallet creation (both Crossmint custodial wallets and smart wallet), delivery to Twitter handle, etc.

Merchant of Record

Crossmint remains the merchant of record for all transactions. Your buyers will still receive delivery receipts and transaction confirmations from Crossmint.

​

Prerequisites

1. Solana Wallet

   Have a Solana wallet address ready to receive purchased memecoins

2. Get API Keys

   Get your API keys from the Crossmint Console

   Client-side

   Server-side (Headless Checkout Only)

​

Fungible Token Specification

To define which fungible token you'd like to purchase, you'll need to specify the tokenLocator in the format:

• For Solana: solana:${tokenMintHash}

  • Example: solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
  • tokenMintHash: The token mint hash (commonly known as contract address, CA, or mint hash)

• For EVM chains (Ethereum, Polygon, Arbitrum, Base, etc.): <chain>:<contractAddress>

  • Example: ethereum:0x1234567890123456789012345678901234567890
  • chain: The chain name (ethereum, polygon, arbitrum, base, etc.)
  • contractAddress: The contract address corresponding to the ERC20 token contract (40 hexadecimal characters, beginning with 0x)

​

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

1. 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)
   
2. 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
   
3. Change into the directory created in previous steps

   cd crossmint-embedded-checkout-demo
   
4. Install @crossmint/client-sdk-react-ui

   npm

   npm i @crossmint/client-sdk-react-ui
   
5. Open the project in your preferred code editor

1. Add environment variables

   Create .env.local in your project root:

   NFTs

   NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY="<your-client-api-key>"    # From API Keys page
   NEXT_PUBLIC_COLLECTION_ID="<your-collection-id>"      # From Collection details page
   

   Memecoins & Tokens

   NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY="<your-client-api-key>"                    # From API Keys page
   NEXT_PUBLIC_TOKEN_ADDRESS="7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu" # xmeme token for staging testing
   NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS="YOUR_SOLANA_WALLET_ADDRESS"     # Add desired recipient wallet
   NEXT_PUBLIC_RECEIPT_EMAIL="YOUR_EMAIL"                               # Add desired recipient email
   

   Testing in Staging? Use the XMEME test token: solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu. Production tokens will not work in the staging environment.

2. Create the checkout page

   Replace your home page (e.g {root_dir}/app/page.tsx) with:

   NFTs

   "use client";
   
   import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";
   
   export default function Home() {
       const clientApiKey = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY as string;
       const collectionId = process.env.NEXT_PUBLIC_COLLECTION_ID as string;
   
       return (
           <div className="flex flex-col items-center justify-start h-screen p-6 bg-white">
               <CrossmintProvider apiKey={clientApiKey}>
                   <div className="max-w-[450px] w-full">
                       <CrossmintEmbeddedCheckout
                           lineItems={{
                               collectionLocator: `crossmint:${collectionId}`,
                               callData: {
                                   totalPrice: "0.001",
                                   quantity: 1,
                               },
                           }}
                           payment={{
                               crypto: { enabled: true },
                               fiat: { enabled: true },
                           }}
                       />
                   </div>
               </CrossmintProvider>
           </div>
       );
   }
   

   Memecoins & Tokens

   "use client";
   import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-ui";
   
   export default function Home() {
       const clientApiKey = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_API_KEY as string;
       const tokenAddress = process.env.NEXT_PUBLIC_TOKEN_ADDRESS as string;
       const recipientWalletAddress = process.env.NEXT_PUBLIC_RECIPIENT_WALLET_ADDRESS as string;
   
       return (
           <div className="flex flex-col items-center justify-start h-screen p-6 bg-white">
               <CrossmintProvider apiKey={clientApiKey}>
                   <div className="max-w-[450px] w-full">
                       <CrossmintEmbeddedCheckout
                           recipient={{
                               walletAddress: recipientWalletAddress, // Wallet address to receive the tokens
                           }}
                           lineItems={{
                               tokenLocator: `solana:${tokenAddress}`, // Token address in format solana:tokenAddress
                               executionParameters: {
                                   mode: "exact-in", // Tells Crossmint to operate in buying fungibles mode
                                   amount: "5", // Amount in USD
                                   maxSlippageBps: "500" // Optional - default slippage will be applied if not specified
                               }
                           }}
                           payment={{
                               receiptEmail: process.env.NEXT_PUBLIC_RECEIPT_EMAIL as string, // Email address to receive the receipt
                               crypto: {
                                   enabled: false, // Only fiat is supported for memecoin purchases
                               },
                               fiat: {
                                   enabled: true,
                               },
                               defaultMethod: "fiat",
                           }}
                       />
                   </div>
               </CrossmintProvider>
           </div>
       );
   }
   

   Note the key parameters: executionParameters.mode is "exact-in" for fungible token purchases (the exact USD amount to spend; "exact-out" is for NFTs), and maxSlippageBps sets an optional slippage tolerance. For more details on tokenLocator formatting, see the item selection guide.

3. Run your app

   npm

   npm run dev
   

   Visit website (e.g http://localhost:3000) to see your checkout!

4. Test your app

   Test purchases in staging using test credit cards, like 4242424242424242 (Visa). More information on testing can be found here.

​

Advanced Integration

Need purchase tracking, multiple NFT purchases at once, or more customization? Here’s a complete setup with additional features:

"use client";

import { useEffect } from "react";
import {
    CrossmintProvider,
    CrossmintCheckoutProvider,
    CrossmintEmbeddedCheckout,
    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 (
        <CrossmintEmbeddedCheckout
            lineItems={[
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.001",
                        quantity: 1,
                    },
                },
                {
                    collectionLocator: `crossmint:${collectionId}`,
                    callData: {
                        totalPrice: "0.002",
                        quantity: 2,
                    },
                },
            ]}
            payment={{
                crypto: {
                    enabled: true,
                    defaultChain: "polygon", // Set preferred blockchain
                    defaultCurrency: "matic", // Set preferred crypto
                },
                fiat: {
                    enabled: true,
                    defaultCurrency: "usd", // Set preferred fiat currency
                    allowedMethods: {
                        card: true,
                        applePay: true,
                        googlePay: true,
                    },
                },
                receiptEmail: "[e-mail]", // Optional: Set receipt email
            }}
            recipient={{
                email: "[e-mail]", // Items 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_CROSSMINT_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 items in one checkout, purchase status tracking, preferred payment methods and currencies, email-based delivery, and language settings. Learn more: Payment Methods · Select Items · Hooks & Events

​

Testing Your Integration

This demo uses the staging environment:

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

​

All Set!

You’ve successfully integrated card and crypto payments with the Crossmint Embedded Checkout!

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

​

Next Steps

Appearance

Customize the look and feel of your checkout

Payment Methods

Configure available payment options for your users

Hooks & Events

Use React hooks to build custom checkout experiences

Localization

Set the checkout language and payment currency