Pay with Card

Accept card payments for NFTs or tokens through the Orders REST API

​

Introduction

In this quickstart you will learn how to accept credit card payments (including Apple and Google Pay) using Crossmint’s headless APIs to purchase an NFT or a token (such as a Solana memecoin).

For a faster, embedded checkout solution with minimal setup time, see the embedded quickstart.

​

Prerequisites

​

From Crossmint

1. Create a developer account in the Staging Console.
2. Create a server-side API key with the orders.create, orders.update, and orders.read scopes enabled. More info on creating API keys here.

This Quickstart assumes that you will be using the API Playground or cURL requests to make the API calls. This approach requires the use of a server-side API key.

If you would rather follow the quickstart while building a client-side app that makes requests to Crossmint directly from the browser, you must use a client-side API key. For client-side usage, you don’t need the orders.read scope - use the clientSecret from order creation for subsequent operations. See the Server or Client Guide for more information.

NFTs

Create a new collection or import yours into the console, and have your collectionId ready. You’ll find it on the Collection details page. This guide purchases an NFT on the polygon-amoy testnet.

Make sure you follow the maximum prices for collections set in staging outlined here.

Memecoins & Tokens

​

Important Notes

Compliance Checks

Crossmint runs compliance checks on all tokens to ensure they do not qualify as securities or currencies under applicable regulations. Transactions for tokens that are determined to be too similar to securities or currencies will fail.

Supported Tokens

Memecoin checkout supports the Solana and Base networks. You can check which tokens are supported by using the fungibleCheckoutAvailable endpoint. A more in depth guide on token support is here.

Delivery to External Wallets Only

Memecoin checkout only delivers memecoins to EOAs (Externally Owned Accounts), not Crossmint supported delivery solutions, such as on-the-fly wallet creation (both Crossmint custodial wallets and smart wallet), delivery to Twitter handle, etc.

Merchant of Record

Crossmint remains the merchant of record for all transactions. Your buyers will still receive delivery receipts and transaction confirmations from Crossmint.

​

Prerequisites

1. Solana Wallet

   Have a Solana wallet address ready to receive purchased memecoins

2. Get API Keys

   Get your API keys from the Crossmint Console

   Client-side

   Server-side (Headless Checkout Only)

​

Fungible Token Specification

To define which fungible token you'd like to purchase, you'll need to specify the tokenLocator in the format:

• For Solana: solana:${tokenMintHash}

  • Example: solana:6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN
  • tokenMintHash: The token mint hash (commonly known as contract address, CA, or mint hash)

• For EVM chains (Ethereum, Polygon, Arbitrum, Base, etc.): <chain>:<contractAddress>

  • Example: ethereum:0x1234567890123456789012345678901234567890
  • chain: The chain name (ethereum, polygon, arbitrum, base, etc.)
  • contractAddress: The contract address corresponding to the ERC20 token contract (40 hexadecimal characters, beginning with 0x)

To integrate in production/mainnet, you also need a signed Order Form with Crossmint and KYB. NFT Checkout additionally requires collection verification. See the production launch guide for the full sequence.

​

Integration Steps

This quickstart will focus on the API calls to Crossmint necessary to implement headless checkout in your project, as well as the usage of Crossmint Embedded Checkout component to collect the user's payment.

This guide assumes you are using React, however Crossmint's checkout can be used in all platforms such as Web, iOS, Android, and React Native.

1. Create an Order

   The first step in the headless checkout process is to create an order. An order is an object datastructure, that represents an intent to purchase in Crossmint's systems. This guide will create a basic order, and then update it with required info step-by-step.

   You can also create the entire order in one API call if the necessary information is available at the time of order creation. This can be used for custom "one-click-checkout" experiences, should you wish to make them.

   POST https://staging.crossmint.com/api/2022-06-09/orders

   Refer to the complete create order API reference here.

   NFTs

   {
       "payment": {
           "method": "card"
       },
       "lineItems": [
           {
               "collectionLocator": "crossmint:<collectionId>", // Use the collectionId from the Prerequisites section
               "callData": {
                   "totalPrice": "0.0001"
               }
           }
       ]
   }
   

   Example Response

   {
     "clientSecret": "_removed_",
     "order": {
       "orderId": "cc40e6af-f8dc-4ac2-8e26-d91a32f271cf",
       "phase": "quote",
       "locale": "en-US",
       "lineItems": [
         {
           "chain": "polygon-amoy",
           "quantity": 1,
           "callData": {
             "quantity": 1
           },
           "metadata": {
             "name": "Headless Demo",
             "description": "NFT Checkout Demo",
             "imageUrl": "https://utfs.io/f/cd8545b7-3410-4fcd-988d-cd11951ed53c-g287ok.png"
           },
           "quote": {
             "status": "requires-recipient",
             "charges": {
               "unit": {
                 "amount": "0.000169004",
                 "currency": "eth"
               }
             },
             "totalPrice": {
               "amount": "0.000169004",
               "currency": "eth"
             }
           },
           "delivery": {
             "status": "awaiting-payment"
           }
         }
       ],
       "quote": {
         "status": "requires-recipient",
         "quotedAt": "_DATE_",
         "expiresAt": "_DATE_",
         "totalPrice": {
           "amount": "0.000169004",
           "currency": "eth"
         }
       },
       "payment": {
         "status": "requires-quote",
         "method": "basis-theory",
         "preparation": {}
       }
     }
   }
   

   Memecoins & Tokens

   Memecoins are testable in staging using the xmeme token (7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu). All other token purchases will fail in staging.

   Node.js

   const apiKey = "<your-server-api-key>";
   const tokenId = "solana:7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu"; // xmeme token for staging
   const deliveryAddress = "your-solana-wallet-address";
   const receiptEmail = "[e-mail]";
   
   const options = {
       method: "POST",
       headers: {
           "x-api-key": apiKey,
           "Content-Type": "application/json",
       },
       body: JSON.stringify({
           lineItems: [
               {
                   tokenLocator: tokenId, // Token address in format solana:tokenAddress
                   executionParameters: {
                       mode: "exact-in", // Tells Crossmint to operate in buying fungibles mode
                       amount: "1", // default currency USD
                       maxSlippageBps: "500", // Optional, or else default autogenerated slippage will be applied
                   },
               },
           ],
           payment: {
               method: "card",
               receiptEmail: receiptEmail,
           },
           recipient: {
               walletAddress: deliveryAddress,
           },
       }),
   };
   
   fetch("https://staging.crossmint.com/api/2022-06-09/orders", options)
       .then((response) => response.json())
       .then((response) => console.log(JSON.stringify(response, null, 2)))
       .catch((err) => console.error(err));
   

   Note the following parameters in the request body:

   • maxSlippageBps: Optional, or else default autogenerated slippage will be applied
   • receiptEmail: Optional. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.
   • executionParameters.mode: The execution method for the order. “exact-out” is for NFTs, “exact-in” is for fungible tokens

   For more details on tokenLocator formatting, see the item selection page.

   For the comprehensive list of supported currencies and chains, view the Supported Currencies page.

   At this point you have successfully created an Order in the Crossmint system! The order is currently in the quote phase and is awaiting a recipient to be set. Setting a recipient does not mean that we are sending the NFT to them; it is merely used to verify that the intended recipient is a valid address, before beginning gathering payment info.

   ​

   Optional - View the Order in the Console

   Congratulations! You've made your first contact with Crossmint's systems. You can see your request show up in the developer console. Navigate to the Orders tab for your collection in the Staging Console and enter the orderId returned from your API response to find your incomplete order object and status.

   
2. Update the Order with Recipient

   Next, you will set who's the intended recipient of the order by specifying a wallet address or email. When a recipient is passed as an email, Crossmint will automatically create a custodial wallet associated with this email, that can be accessed by logging in to the (staging) Crossmint Wallet or from your website if you're using whitelabel wallets.

   PATCH https://staging.crossmint.com/api/2022-06-09/orders/<orderId>

   Remember to ensure you're using the right type of API key! See the Server or Client Guide for more info.

   Refer to the complete edit order API reference here.

   If you already set recipient and payment.receiptEmail when creating the order — as in the token example above — you can skip this step.

   Legally, for card payments, an email must be specified in order to deliver a receipt to your user, either in recipient.email or in payment.receiptEmail. If one is not specified, the API will not return the fields necessary to collect the user’s payment.

   Email recipient

   Email recipients work for NFT orders only. Token orders need recipient.walletAddress.

   {
       "recipient": {
           "email": "[e-mail]"
       }
   }
   

   Wallet recipient with receipt email

   {
       "recipient": {
           "walletAddress": "0xabcd1234..."
       },
       "payment": {
           "method": "card", // When updating the payment, you must pass the complete object
           "receiptEmail": "[e-mail]"
       }
   }
   
3. Render the Crossmint Embedded Component

   After creating an order, render the Crossmint Embedded Component to collect payment information. This secure, embeddable UI component lets you accept payment methods, validates input, and handles errors:

   import { CrossmintEmbeddedCheckout, CrossmintProvider } from "@crossmint/client-sdk-react-ui";
   
   export function MyCheckoutPage({ clientSecret, order, receiptEmail }) {
       return (
           <div className="w-full">
               <CrossmintProvider apiKey="<YOUR CLIENT SIDE KEY>">
                   <CrossmintEmbeddedCheckout
                       clientSecret={clientSecret}
                       orderId={order.orderId}
                       payment={{
                           crypto: {
                               enabled: false,
                           },
                           fiat: {
                               enabled: true,
                           },
                           defaultMethod: "fiat",
                           receiptEmail: receiptEmail,
                       }}
                       appearance={{
                           rules: {
                               DestinationInput: {
                                   display: "hidden",
                               },
                               ReceiptEmailInput: {
                                   display: "hidden",
                               },
                           },
                       }}
                   />
               </CrossmintProvider>
           </div>
       );
   }
   

   The CrossmintEmbeddedCheckout component is highly customizable. You can adjust colors, styling, layout, and behavior to match your brand. Learn more in the appearance guide.

4. Poll for Status Updates

   After making the payment via whichever payment method, you'll need to poll the Get Order API to check on the delivery status and present this info to your user.

   Refer to the complete get order API reference here.

   GET https://staging.crossmint.com/api/2022-06-09/orders/<orderId>

​

Handling Refunded Payments

When polling for order status, you may encounter a situation where payment.status is completed but the order also contains a payment.refunded property. This indicates that the payment was initially successful but has since been refunded.

{
    "order": {
        "payment": {
            "status": "completed",
            "refunded": {
                "amount": "1.00",
                "currency": "usd",
                "txId": "0x1234abcd...",
                "chain": "ethereum"
            }
        }
    }
}

The payment.refunded object includes the following fields:

• amount: The amount that was refunded
• currency: The currency of the refund
• txId: The on-chain transaction ID the refund was sent in
• chain: The blockchain where the refund transaction occurred

When you encounter this state, your application should display an appropriate message to the user, provide the txId so they can verify the refund on-chain, and offer the option to place a new order.

​

Memecoin & Token Specifics

The following applies to fungible token purchases (tokenLocator + executionParameters), not NFTs.

​

Refreshing Orders

For memecoin checkout, the order expiration is 1 minute. The Crossmint Embedded Checkout will automatically refresh the order for you when the time comes. Alternatively, you can either create a new order or use the refresh quote API:

async refreshOrder(orderId, clientSecret) {
    try {
        const ancestorOrigins =
            typeof window !== "undefined" && window.location?.ancestorOrigins
                ? Array.from(window.location.ancestorOrigins)
                : [];

        const response = await this.callApi(`2022-06-09/orders/${orderId}/refresh`, "POST", {}, {
            authorization: `${clientSecret}`,
            "x-ancestor-origins": JSON.stringify(ancestorOrigins),
        });

        const parsed = await response.json();
        return parsed;
    } catch (error) {
        console.error("Error refreshing quote:", error);
        throw error;
    }
}

​

Understanding the Code

Quote Expiration

Price quotes are valid for 1 minute. After expiration, you'll need to request a new quote from the embedded checkout component

Slippage

Crossmint applies the slippage specified in your executionParameters.maxSlippageBps. If not provided, Crossmint will use the default slippage configuration (typically 500 BPS or 5%) from Crossmint's provider

​

Order Lifecycle

The order goes through several phases: Learn more about order phases in the headless checkout guide or embedded checkout guide

A summary of the phases is below:

1. Quote Phase (1-minute validity)

   • Initial price quote generated
   • Requires recipient information to proceed

2. Payment Phase

   • Collect payment information
   • Handle payment completion and errors

3. Delivery Phase

   • Purchase memecoin with USDC
   • Apply specified slippage tolerance
   • Send transfer transaction to recipient wallet

4. Completion

   • Order marked as completed
   • Receipt email sent to recipient
   • Memecoins have been delivered to the recipient wallet

​

FAQ

Is there a UI Crossmint provides?

Yes, you can use our embedded checkout or hosted checkout options. Contact our sales team to learn more about these solutions and find the best fit for your needs.

Do I need to complete KYC to purchase memecoins?

Crossmint KYC is currently disabled for memecoin purchases. This means that if your buyers typically have high risk profiles, their transaction may be declined. To increase conversion, please read the improving conversion guide.

What happens if my transaction fails?

When a user attempts a purchase, Crossmint puts a hold on their credit card. Only if the blockchain transaction succeeds, funds are captured. If the blockchain transaction fails, funds are released and the user is never charged.

What are the transaction limits?

The default transaction limit is 1,000 USD per user. A single wallet address is subject to a daily limit of 1,000 USD per user, the same as for NFT purchases. If you need a higher limit, speak to your Crossmint representative.

What do the order creation parameters mean?

The order creation request includes several important parameters:

Payment Object

• method: Set to card for credit card payments
• currency: Set to usd for US Dollar payments
• receiptEmail: Optional. If the buyer pays with Apple Pay or Google Pay, Crossmint obtains the email automatically. Providing it improves fraud signal quality.

Line Items Object

• tokenLocator: Specifies the memecoin token address in the format solana:tokenAddress
• executionParameters:
  • mode: Set to "exact-in" for memecoin purchases (specifies exact USD amount to spend)
  • amount: Amount to purchase in USD
  • maxSlippageBps: Set to "500" for 5% slippage tolerance. If not provided, the default slippage will be applied from the available liquidity provider.

Response Parameters The API response includes a clientSecret and an order object with an orderId. Pass these to the Crossmint Embedded Checkout component to collect payment from the user.

​

Next Steps

Design Your UI

Learn how to design your headless checkout experience

Webhooks

Implement webhook handling for order updates