Private preview

Integrate the KYC tier system for the Embedded Components onramp Private preview

Learn about KYC verification tiers, the information required for each, and how to detect when a customer's purchase amount is limited by their verification level.

All customers must pass KYC verification before they can buy crypto with the onramp. Customers can provide additional information to increase their purchase limits. This guide covers the KYC tiers, the information required for each tier, and how you can detect when a customer’s purchase amount is limited by the amount of KYC information provided. For reference integration flows, screen overviews, and step-up detection patterns, see KYC integration best practices.

Note

EU customers have additional identifier and attestation requirements beyond the standard KYC tiers. See the EU KYC integration guide for details.

Before you begin

Before you begin, integrate the Embedded Components Onramp.

KYC tier comparison

The following table summarizes the requirements for each KYC tier.

KYC API

Use attachKYCInfo for L0 and L1 KYC

Call attachKYCInfo to initiate the L0 and L1 KYC verification processes for a customer.

The fields collected by attachKYCInfo depend on the tier:

• L0 : firstName , lastName , address
• L1 : All L0 fields, plus dateOfBirth , idNumber , idType

L0 and L1 verification are asynchronous. Call this API and check the verification status before you create an onramp session. Creating a CryptoOnrampSession returns a 400 error if the customer has pending verifications. Continue retrieving the verification result until no verification remains pending. See Determine whether a customer is verified for details.

Use verifyIdentity for L2 KYC

Call verifyIdentity to present a Stripe-hosted flow where the customer uploads an identity document and a selfie.

L2 verification is asynchronous. Your backend must call the Retrieve a CryptoCustomer API with the customerId. The API returns the L2 verification status in id_document_verified.

Handling KYC error for createCryptoPaymentToken

Customers must submit their minimum identity information (name, phone, email, and address) before you can collect payment methods. If a customer hasn’t yet provided this minimum information, createCryptoPaymentToken returns a crypto_onramp_missing_minimum_identity_verification error. Handle this error by prompting the customer to submit their information using attachKYCInfo.

A customer’s L0 tier verification status is independent of their ability to use the onramp. If a customer submits the minimum identity information but fails L0 verification, they can still use the onramp by completing L1 verification (date of birth and SSN). L1 verification supersedes L0.

Determining a customer’s current KYC tier

Retrieve a CryptoCustomer with the customerId and inspect the kyc_tiers field to determine a customer’s current KYC tier. The customer’s current tier is the highest tier where verification_status is not not_available or not_started.

The verification_status values for each tier are:

For example, given the following kyc_tiers response:

"kyc_tiers": [
 { "tier": "l0", "verification_status": "verified", "verification_errors": [] },
 { "tier": "l1", "verification_status": "verified", "verification_errors": [] },
 { "tier": "l2", "verification_status": "not_started", "verification_errors": [] }
]

The customer’s current tier is L1 because it is the highest tier that is not not_available or not_started.

After Retrieving a CryptoCustomer, use the following snippet to determine the customer’s current KYC tier from the kyc_tiers field in the response:

// Iterates from the highest tier (l2) to the lowest (l0) and returns the first tier
// whose verification_status is "pending", "rejected", or "verified" (meaning the customer
// has at least attempted that tier). Returns undefined if no tier has been started.
const currentTier = ["l2", "l1", "l0"].find((t) => ["pending", "rejected", "verified"].includes(customer.kyc_tiers.find((k) => k.tier === t)?.verification_status));

You can also use the provided_fields field to determine a customer’s tier:

Determine whether a customer is verified

After retrieving the customer’s current KYC tier, check whether the tier entry for that tier has verification_status: "verified". If so, the customer is verified at that tier.

The following table summarizes how to use the kyc_tiers field to check verification status:

The deprecated verifications field can also be used to determine verification status:

Interpret limit errors from CryptoOnrampSession

Your backend must Create a CryptoOnrampSession to create a CryptoOnrampSession. If the customer reaches a purchase limit, the Create a CryptoOnrampSession API returns an HTTP 400 error with a JSON object that describes the error. Your application can use these errors to request more information from the customer so they can complete the transaction.

If creating a CryptoOnrampSession returns an HTTP 400 error with one of the following error codes, Retrieve a CryptoCustomer with the customerId to determine the next step.

• crypto _ onramp _ missing _ minimum _ identity _ verification
• crypto _ onramp _ missing _ identity _ verification
• crypto _ onramp _ missing _ document _ verification

The following table summarizes how to use both the error code from Creating a CryptoOnrampSession and the kyc_tiers field from Retrieving a CryptoCustomer to determine the next step.