Crossmint’s Headless Checkout API allows developers to create a seamless onramp experience for users to purchase various crypto tokens (including USDC and other supported tokens) using their credit card while completing the necessary KYC (Know Your Customer) process. This guide walks you through the steps to implement this functionality in your application, with support for users across any geography.

​
Native Integration Experience

Crossmint’s onramp solution provides a natively integrated experience that keeps users within your application’s flow:

  • Seamless User Experience: Users complete the entire purchase process without being redirected to external platforms
  • Consistent Branding: Maintain your app’s look and feel throughout the entire process
  • Higher Conversion Rates: Reduce drop-offs by eliminating jarring transitions to third-party services
  • Complete Control: Customize every aspect of the user journey while Crossmint handles the complex payment infrastructure

​
1. Setup

  • Create a developer account in the Crossmint Console
  • Create a server-side API key with the orders.create and orders.read scopes enabled
    • Contact Crossmint Support to include your project in our allowlist

​
2. Create Order

Use the Create Order API to initiate the purchase process. Here’s an example API call:

const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY",
    },
    body: JSON.stringify({
        lineItems: [
            {
                tokenLocator: "solana:example-token-address", // Token address, e.g., USDC: 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU
                executionParameters: {
                    mode: "exact-in",
                    amount: "2",
                },
            },
        ],
        payment: {
            method: "checkoutcom-flow",
            receiptEmail: "user@example.com",
        },
        recipient: {
            walletAddress: "example-wallet-address", // Replace with actual recipient wallet address
        },
    }),
});

const data = await response.json();

​
3. Check KYC Requirements

After creating an order, check the response for KYC requirements:

  • If payment.status is requires-kyc, direct your user through the KYC flow
  • If payment.status is awaiting-payment, the user has already completed KYC and can proceed

​
4. Complete KYC Process

​
Embedded experience

Use the provided identifiers to specify which verification template to use (templateId), which user this verification applies to (referenceId), and which environment to connect to (environmentId).

Customization of the KYC flow’s look-and-feel is an enterprise feature. Please contact Crossmint support to enable this feature.

import Persona from 'persona';

const client = new Persona.Client({
  // Fill out from previous response
  templateId: "example-template-id",
  referenceId: "example-reference-id",
  environmentId: "example-environment-id",
  onReady: () => client.open(),
  onComplete: ({ inquiryId, status, fields }) =>
    console.log(`Sending finished inquiry ${inquiryId} to backend`);
  },
  onCancel: ({ inquiryId, sessionToken }) => console.log('onCancel'),
  onError: (error) => console.log(error),
});

For a mobile integration, check Persona’s React Native guide.

​
Hosted experience

If you want to redirect users to a URL, opening it in a WebView, you can construct the proper Persona URL given the IDs above.

​
5. Poll KYC Status

Poll Crossmint’s Get Order API, replacing {orderId} with the order ID received when initiating the payment, to check the status of the verification. Polling at reasonable intervals is recommended (i.e. every 5 seconds).

const checkOrderStatus = async (orderId) => {
    const response = await fetch(`https://staging.crossmint.com/api/2022-06-09/orders/${orderId}`, {
        method: "GET",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": "YOUR_API_KEY",
        },
    });

    return await response.json();
};

The possible KYC status values are:

  • If payment.status is awaiting-payment, user has successfully completed KYC, proceeding to pay
  • If payment.status is rejected-kyc, verification was rejected and the user can’t onramp
  • If payment.status is manual-kyc, verification requires manual review and the user will be notified via email about its ultimate success or rejection

​
6. Execute Transactions

Initialize Checkout.com’s Flow component for Desktop or Mobile to render an embedded payment form using the payment session and public key obtained in the prior response.

// Example implementation using Checkout.com Flow component
const initializePayment = (checkoutcomPaymentSession, checkoutcomPublicKey) => {
    const checkout = new Checkout.Flow({
        publicKey: checkoutcomPublicKey,
        paymentSession: checkoutcomPaymentSession,
        onSuccess: (event) => {
            console.log("Payment successful", event);
            // Handle successful payment
        },
        onFailure: (event) => {
            console.log("Payment failed", event);
            // Handle payment failure
        },
    });

    checkout.mount("#payment-container");
};

​
7. Transaction Completion

Upon successful payment:

  • The purchased tokens (minus fees) are sent directly to the user’s wallet
  • User receives an email receipt from hello@crossmint.io

Was this page helpful?