Ideal for companies that have verified users through their own identity verification (IDV) provider.
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": "[email protected]"
},
"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:
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: "[email protected]", // 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));
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: "[email protected]" // 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
