Skip to main content
Crossmint Onramp Embedded Checkout Demo

Native mobile onramp

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 for React Native users to buy crypto with a credit card. In this guide, you’ll learn how to:
  • Install the React Native SDK using npm/yarn
  • Create a Crossmint order for your authenticated users
  • Use Crossmint’s embedded checkout component to handle KYC, payment, and delivery automatically

​
Requirements

  • React Native 0.60+
  • Expo (recommended) or bare React Native CLI
  • iOS 13.0+ / Android 5.0+

​
1. Installation

Install the Crossmint React Native SDK.
1

Install the SDK

npm i @crossmint/client-sdk-react-native-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 or .env.local:
EXPO_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY="_YOUR_CLIENT_API_KEY_"
CROSSMINT_SERVER_SIDE_API_KEY="_YOUR_SERVER_API_KEY_"
For Expo projects, use the EXPO_PUBLIC_ prefix. For bare React Native, configure environment variables according to your setup.

​
2. Create Order

Use the Create Order API to initiate the purchase process from your backend. Use the following token addresses for USDC on staging:
ChainStaging Token Address
Solana4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
Base0x036CbD53842c5426634e7929541eC2318f3dCF7e
🚨 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: 
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": "user@example.com"
    },
    "recipient": {
      "walletAddress": "example-wallet-address"
    }
  }'

{
  "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 in your React Native app: 
import { CrossmintProvider, CrossmintEmbeddedCheckout } from "@crossmint/client-sdk-react-native-ui";

export default function App() {
    const clientApiKey = process.env.EXPO_PUBLIC_CROSSMINT_CLIENT_SIDE_API_KEY;
    
    return (
        <CrossmintProvider apiKey={clientApiKey}>
            <CrossmintEmbeddedCheckout
                orderId={orderId}
                clientSecret={clientSecret}
                payment={{
                    receiptEmail: "user@example.com",
                    crypto: { enabled: false },
                    fiat: { enabled: true },
                    defaultMethod: "fiat",
                }}
            />
        </CrossmintProvider>
    );
}

​
Key Features

  • Cross-platform: Works on both iOS and Android
  • Native Performance: Optimized for mobile devices
  • Automatic KYC: Handles verification flow automatically
  • Multiple Payment Methods: Credit/debit cards, Apple Pay (iOS), Google Pay (Android)

​
4. Track Order

After the user completes payment, you can track the order status using webhooks or polling. Configure a webhook endpoint to receive real-time order status updates:
  1. Go to the Crossmint Console
  2. Add your webhook endpoint URL
  3. Subscribe to order.payment.succeeded and order.delivery.succeeded events
Example webhook payload: 
{
  "type": "order.payment.succeeded",
  "orderId": "example-order-id",
  "payment": {
    "status": "succeeded",
    "method": "card",
    "currency": "usd"
  }
}

​
Option 2: Polling

Poll the order status endpoint from your backend: 
curl --request GET \
  --url https://staging.crossmint.com/api/2022-06-09/orders/{orderId} \
  --header 'x-api-key: YOUR_SERVER_API_KEY'
Check the order.payment.status and order.lineItems[].delivery.status fields to track progress.

​
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

​
Next Steps