Skip to main content
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. 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.

​
Register User with Full KYC Data

Check the requirements here, on what information needs to be attached to the user using the Create User API.

​
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.
curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'X-API-KEY: <x-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "recipient": {
            "walletAddress": "<recipient-wallet-address>"
        },
        "payment": {
            "method": "card",
            "receiptEmail": "johnd@example.com"
        },
        "lineItems": [
            {
                "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "executionParameters": {
                    "mode": "exact-in",
                    "amount": "1"
                }
            }
        ]
    }'
The lineItems field accepts both 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’s 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:johnd-123";

const options = {
  method: 'PUT',
  headers: {
    'X-API-KEY': '<x-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: "johnd@example.com",  // This email will be used to link KYC data
      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': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      walletAddress: "<recipient-user-wallet-address>"
    },
    payment: {
      method: "card",
      receiptEmail: "johnd@example.com"  // Must match kycData.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

​
Success: Full KYC Data Present

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

​
Success: Additional KYC Inquiry

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

​
Error: Missing KYC Data

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