Skip to main content
Crossmint Onramp Embedded Checkout Demo

You will build this demo

Before you start

Set up your project and get an API key.

Onramp Embedded Quickstart

See a full working example.
You can start testing Onramp in staging. Once you are ready to go live, reach out to sales to enable the feature in production
Crossmint’s Embedded Checkout API lets you build a seamless onramp so users can buy crypto with a credit card. In this guide, you’ll learn how to:
  • Create a Crossmint order for a user authenticated in your app
  • Use Crossmint’s embedded checkout component to handle KYC, payment, and delivery automatically

​
1. Prerequisites

1

Install the SDK

Install the Crossmint client SDK:
npm install @crossmint/client-sdk-react-ui
2

Create API keys

Create a server-side API key with the orders.create and orders.read scopes enabled.
Create a client-side API key for the embedded checkout component.
3

Add environment variables

Add environment variables to your .env.local:
NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY="_YOUR_CLIENT_API_KEY_"
CROSSMINT_SERVER_SIDE_API_KEY="_YOUR_SERVER_API_KEY_"
CROSSMINT_ENV="staging"

​
2. Create Order

Use the Create Order API to initiate the purchase process. Use the following token addresses for USDC:
ChainStagingProduction
Solana4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDUEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Base0x036CbD53842c5426634e7929541eC2318f3dCF7e0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
🚨 IMPORTANT: The user email you send as a parameter (on payment.receiptEmail) must correspond to a user authenticated by your application. This email is used by Crossmint to determine whether KYC is required for the order.
Here’s an example API call: 
const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY; // Server-side API key
const tokenLocator = "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"; // USDC staging address
const receiptEmail = "user@example.com"; // Replace with actual recipient authenticated email
const walletAddress = "example-wallet-address"; // Replace with actual recipient wallet address
const tokenAmount = "5"; // Replace with desired amount

const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": serverApiKey,
    },
    body: JSON.stringify({
        lineItems: [
            {
                tokenLocator,
                executionParameters: {
                    mode: "exact-in",
                    amount: tokenAmount,
                },
            },
        ],
        payment: {
            method: "checkoutcom-flow",
            receiptEmail,
        },
        recipient: {
            walletAddress,
        },
    }),
});

const data = await response.json();

{
  "clientSecret": "example-client-secret",
  "order": {
    "orderId": "example-order-id",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [
      {
        "chain": "solana",
        "metadata": {
          "name": "USDC",
          "description": "USDC Token",
          "imageUrl": "https://cryptologos.cc/logos/usd-coin-usdc-logo.svg?v=040"
        },
        "quote": {
          "status": "valid",
          "charges": {
            "unit": {
              "amount": "1.47",
              "currency": "usd"
            }
          },
          "totalPrice": {
            "amount": "2",
            "currency": "usd"
          },
          "quantityRange": {
            "lowerBound": "1.36",
            "upperBound": "1.36"
          }
        },
        "delivery": {
          "status": "awaiting-payment",
          "recipient": {
            "locator": "solana:example-wallet-address",
            "walletAddress": "example-wallet-address"
          }
        },
        "executionMode": "exact-in",
        "maxSlippageBps": "0",
        "executionParams": {
          "mintHash": "example-mint-hash",
          "mode": "exact-in",
          "amount": "2"
        }
      }
    ],
    "quote": {
      "status": "valid",
      "quotedAt": "2025-03-07T23:04:11.996Z",
      "expiresAt": "2025-03-07T23:14:11.996Z",
      "totalPrice": {
        "amount": "2",
        "currency": "usd"
      }
    },
    "payment": {
      "method": "checkoutcom-flow",
      "currency": "usd",
      "status": "requires-kyc",
      "preparation": {
        "kyc": {
          "provider": "persona",
          "templateId": "example-template-id",
          "referenceId": "example-reference-id"
        }
      }
    }
  }
}

​
3. Use Embedded Checkout

Once you have the order response with orderId and clientSecret, use Crossmint’s embedded checkout component to handle the entire KYC, payment and delivery flow automatically: 
"use client";

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

const CLIENT_API_KEY = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY;
if (CLIENT_API_KEY == null) {
    throw new Error("NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY is not set");
}
<CrossmintProvider apiKey={CLIENT_API_KEY}>
    <div className="max-w-[450px] w-full mx-auto">
        <CrossmintEmbeddedCheckout
            orderId={orderId}
            clientSecret={clientSecret}
            payment={{
                receiptEmail,
                crypto: { enabled: false },
                fiat: { enabled: true },
                defaultMethod: "fiat",
            }}
        />
    </div>
</CrossmintProvider>;

​
4. Transaction Completion

Upon successful payment:
  • The purchased tokens (minus fees) are sent directly to the user’s wallet
  • User receives an email receipt from hello@crossmint.io
  • The embedded checkout component handles all the complexity of KYC verification and payment processing automatically

​
5. Next Steps

⌘I