Import User KYC Data

If you already verify users with an identity verification (IDV) provider like Sumsub or Persona, you can send that data to Crossmint before creating an onramp order. When the data is complete, users can skip in-checkout identity verification. 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

Verify the user with your IDV provider
Have the user accept Crossmint’s Privacy Policy
Register the user’s identity data with Crossmint and trigger verification
Create an onramp order to the wallet linked to that user
Crossmint runs sanctions, Politically Exposed Persons (PEP), and compliance checks
The user completes payment

Register and Verify the User

User registration, KYC data, document uploads, and identity verification are managed by the identity APIs. Follow the Identity Quickstart to:

Record the user’s privacy-policy acceptance (consent must be collected following the requirements in Register User Data)
Register the user’s details and KYC data
Upload any required documents
Trigger identity verification and poll until the onramp eligibility reads verified

The exact fields required vary by region and KYC tier. See Data Requirements for the full list, and User Onboarding and KYC for how the onramp KYC tiers work.

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: Crossmint links pre-registered KYC data to an order using the user’s email address. The payment.receiptEmail value must match the email used in kycData.email when registering the user’s KYC data with the Create User API.

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

curl --request POST \
    --url https://staging.crossmint.com/api/2022-06-09/orders \
    --header 'X-API-KEY: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
        "recipient": {
            "walletAddress": "YOUR_WALLET_ADDRESS"
        },
        "payment": {
            "method": "card",
            "receiptEmail": "YOUR_USER_EMAIL"
        },
        "lineItems": [
            {
                "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "executionParameters": {
                    "mode": "exact-in",
                    "amount": "1"
                }
            }
        ]
    }'

import requests

url = "https://staging.crossmint.com/api/2022-06-09/orders"

payload = {
    "recipient": {
        "walletAddress": "YOUR_WALLET_ADDRESS"
    },
    "payment": {
        "method": "card",
        "receiptEmail": "YOUR_USER_EMAIL"
    },
    "lineItems": [
        {
            "tokenLocator": "base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e",
            "executionParameters": {
                "mode": "exact-in",
                "amount": "1"
            }
        }
    ]
}
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

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.

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

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

How It Works

Register and Verify the User

Create an Onramp Order

Order Responses

Guides

Identity Quickstart

Data Requirements

​How It Works

​Register and Verify the User

​Create an Onramp Order

​Order Responses

​Guides

Identity Quickstart

Data Requirements

How It Works

Register and Verify the User

Create an Onramp Order

Order Responses

Guides