React

Allow your users to buy stablecoins with credit cards in under 5 minutes

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 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_"
   

2. Create Order

Use the Create Order API to initiate the purchase process.

Use the following token addresses for USDC on staging:

Chain	Staging Token Address
Solana Devnet	4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Base Sepolia	0x036CbD53842c5426634e7929541eC2318f3dCF7e

🚨 IMPORTANT: The payment.receiptEmail parameter is required for compliance reasons. This email is used by Crossmint to determine whether KYC is required for the order. The API accepts either recipient.email OR recipient.walletAddress, not both.

Example API call for USDC on Solana Devnet:

curl --request POST \
  --url https://staging.crossmint.com/api/2022-06-09/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <YOUR_SERVER_API_KEY>' \
  --data '{
    "lineItems": [
      {
        "tokenLocator": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        "executionParameters": {
          "mode": "exact-in",
          "amount": "5"
        }
      }
    ],
    "payment": {
      "method": "card",
      "receiptEmail": "[e-mail]"
    },
    "recipient": {
      "walletAddress": "example-wallet-address"
    }
  }'

Example Response

{
  "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"
        }
      }
    }
  }
}

Alternatively, here is a TypeScript example for a Next.js server action:

// app/actions/createOrder.ts
"use server";

interface CreateOrderParams {
    walletAddress: string;
    receiptEmail: string;
    tokenAmount: string;
}

export async function createOrder({ walletAddress, receiptEmail, tokenAmount }: CreateOrderParams) {
    const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
    if (!serverApiKey) {
        throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
    }

    const tokenLocator = "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"; // USDC staging

    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: "card",
                receiptEmail,
            },
            recipient: {
                walletAddress,
            },
        }),
    });

    const data = await response.json();
    return data;
}

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";

export default function OnrampCheckout({
    orderId,
    clientSecret,
    receiptEmail,
}: {
    orderId: string;
    clientSecret: string;
    receiptEmail: string;
}) {
    const clientApiKey = process.env.NEXT_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY as string;

    return (
        <CrossmintProvider apiKey={clientApiKey}>
            <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:

1. KYC Verification

   The embedded checkout component handles all the complexity of KYC verification automatically.

2. Token Delivery

   The purchased tokens (minus fees) are sent directly to the user's wallet.

3. Receipt Sent

   User receives an email receipt from [e-mail].

5. Next Steps

• Explore our Payment Methods Guide to learn about different payment options
• Check out our Production Launch Guide for going live