Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt

Use this file to discover all available pages before exploring further.

Ideal for companies that have verified users through their own identity verification (IDV) provider.
Companies can compliantly pass user KYC data to Crossmint, enabling seamless USDC onramp purchase flows. When KYC data is pre-registered, users skip the in-checkout identity verification entirely. If you prefer to have individual users provide their KYC data client-side, Crossmint supports that as well. See the React Quickstart for that approach.

​
How It Works

Crossmint relies on your company running KYC, ID verification, and liveness checks with your own IDV provider (such as Persona or Sumsub). You then share the full KYC data with Crossmint via API. In order to complete orders, Crossmint runs sanction and PEP (Politically Exposed Persons) screens, and performs ongoing monitoring to ensure compliance. To register a user with Full KYC Data you can check the data requirements here. Using the Create User API you are able to send all the required information to Crossmint.

​
Create an Onramp Order

Once the user is registered with their KYC data, you can create an onramp order. The order will use the registered KYC data for compliance checks.
Important: The KYC data is linked to the order through the email address. The payment.receiptEmail field must match the email address used when registering the user’s KYC data via the Create User API. This is how Crossmint associates the pre-registered KYC information with the order.
const options = {
    method: 'POST',
    headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        recipient: {
            walletAddress: "YOUR_WALLET_ADDRESS"
        },
        payment: {
            method: "card",
            receiptEmail: "YOUR_USER_EMAIL"
        },
        lineItems: [
            {
                tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                executionParameters: {
                    mode: "exact-in",
                    amount: "1"
                }
            }
        ]
    })
};

fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
The lineItems field accepts either a single object or an array. The examples above use an array for consistency, but you can also pass a single line item object directly.

​
Linking KYC Data to Orders

When you create an order, Crossmint automatically looks up the user’s KYC data based on the email address provided in payment.receiptEmail. Here is the complete flow:
1

Register user with KYC data

First, register the user’s KYC information using the Create User API. Make sure to include the user’s email in the email field within kycData:
const userLocator = "userId:YOUR_USER_ID";

const options = {
    method: 'PUT',
    headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        userDetails: {
            firstName: "John",
            lastName: "Doe",
            dateOfBirth: "1995-01-01",
            countryOfResidence: "DE"
        },
        kycData: {
            addressOfResidence: {
                line1: "123 Hauptstrasse",
                line2: "Apt 5",
                city: "Berlin",
                postalCode: "10115"
            },
            email: "YOUR_USER_EMAIL",
            identityDocument: {
                type: "passport",
                number: "AS12321"
            }
        }
    })
};

fetch(`https://staging.crossmint.com/api/2025-06-09/users/${userLocator}`, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
2

Create order with matching email

When creating the onramp order, use the same email address in payment.receiptEmail:
const options = {
    method: 'POST',
    headers: {
        'X-API-KEY': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        recipient: {
            walletAddress: "YOUR_WALLET_ADDRESS"
        },
        payment: {
            method: "card",
            receiptEmail: "YOUR_USER_EMAIL"
        },
        lineItems: [
            {
                tokenLocator: "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                executionParameters: {
                    mode: "exact-in",
                    amount: "1"
                }
            }
        ]
    })
};

fetch('https://staging.crossmint.com/api/2022-06-09/orders', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

​
Order Responses

When all required KYC data has been provided and validated, the order moves to the payment phase:
{
  "clientSecret": "...",
  "order": {
    "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [...],
    "quote": {...},
    "payment": {
      "method": "card",
      "currency": "usd",
      "status": "awaiting-payment"
    }
  }
}
When full KYC data is present but Crossmint needs to run additional compliance checks, the order enters a processing state. This typically resolves within a few seconds as Crossmint runs the appropriate checks:
{
  "clientSecret": "...",
  "order": {
    "orderId": "987e81ab-8c8f-464e-95e9-11ceda80d559",
    "phase": "payment",
    "locale": "en-US",
    "lineItems": [...],
    "quote": {...},
    "payment": {
      "method": "card",
      "currency": "usd",
      "status": "pending-kyc-review"
    }
  }
}
If no user personal data is provided, or if the data is insufficient, the order will fail:
{
  "error": true,
  "message": "Required full KYC user data is missing to complete the order"
}

​
Next Steps

React Quickstart

Build an embedded onramp checkout with React

Onramp Overview

Learn more about Crossmint’s onramp capabilities