Pay with Crypto

Create a fully customized checkout experience with crypto payments

Introduction

In this quickstart you’ll learn how to accept multiple different cryptocurrencies as payment using Crossmint’s headless APIs, to purchase an NFT on the polygon-amoy testnet.

Prerequisites

From Crossmint

1. Create a developer account in the Staging Console.
2. Create a new collection or import yours into the console, and have your collectionId ready.
   • Make sure you follow the maximum prices for collections set in staging outlined here
3. 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'll 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. See the Server or Client Guide for more information.

To integrate in production/mainnet, you'll also need to complete account and collection verification. More information in the production launch guide.

If you are choosing to do this quickstart in your own console or IDE, consider you will need to have a way to prompt and sign crypto payments, like using Metamask.

External Prerequisites

• Your crypto wallet of choice - Metamask, Coinbase Wallet, etc.
• A small balance of testnet currency in whichever cryptocurrency you would like to pay with
  • Ethereum, Base, Polygon - note that some of these faucets require a minimum of 0.1 ETH on mainnet, to prevent abuse
  • Solana devnet

Integration Steps

This quickstart will primarily focus on the API calls necessary to implement headless checkout in your project. You will also need to build out the frontend experience for your users.

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.

• Pay with ETH
• Pay with ERC20s
• Pay with SOL
• Pay with SPLs
• Pay with MATIC

{
    "payment": {
        "method": "base-sepolia",
        "currency": "eth",
        "payerAddress": "0xabcd1234..."
    },
    "lineItems": {
        "collectionLocator": "crossmint:<collectionId>",
        "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"
    }
  }
}

In the requests above the payerAddress has been included, however if your user has not yet connected their wallet you may omit this field, allow them to connect their wallet after creating the order, and submit the payerAddress at a later time.

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.

• Email recipient
• Wallet recipient

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

Notice you only need to pass the object that your are updating, in this case, recipient. You can also update multiple properties in the same call. Available properties for update include recipient, locale, and the payment object.

If specifying a recipient by wallet address, ensure the address is valid for the chain your collection is on, which may differ from the chain the payment is being performed on.

Example Response

{
  "orderId": "cc40e6af-f8dc-4ac2-8e26-d91a32f271cf",
  "phase": "payment",
  "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": "valid",
        "charges": {
          "unit": {
            "amount": "0.0001681558",
            "currency": "eth"
          }
        },
        "totalPrice": {
          "amount": "0.0001681558",
          "currency": "eth"
        }
      },
      "delivery": {
        "status": "awaiting-payment"
      }
    }
  ],
  "payment": {
    "status": "awaiting-payment",
    "preparation": {
      "method": "crypto",
      "chain": "base-sepolia",
      "payerAddress": "0x6C3b3225759Cbda68F96378A9F0277B4374f9F06",
      "serializedTransaction": "0x02f9012683aa36a744848917370085080992ce6c82629c94a105c311fa72b8fb78c992ecbdb8b02ea5bd394d869a9d359ca000b8f465794a68624763694f694a49557a49314e694973496e523563434936496b705856434a392e65794a756232356a5a534936496a4d3559544e6d4d444d334c544d7a4e6d51744e4441305a5331684d6a45774c575268593249335957526b5a4456694e794973496d39795a4756795357526c626e52705a6d6c6c63694936496d4e6a4e44426c4e6d466d4c5759345a474d744e47466a4d6930345a5449324c5751354d57457a4d6d59794e7a466a5a694973496d6c68644349364d5463784e546b334f54557a4e33302e662d4949646c653375314c58634c7845765438754e336d74786370764a686f31384a5a4b76483768456659c0"
    }
  }
}

Notice at the bottom, the new serializedTransaction property. This is a unique identifier let’s Crossmint know exactly which order you are updating. Anytime you update an order you must use the returned serializedTransaction property.

3. Show Purchase Preview to User

Now, after you’ve told Crossmint systems what you want, and you have passed a valid place to send the NFT, Crossmint will return a quote with prices for the desired items Within the returned response, you’ll find the lineItems array which contains the metadata and a quote for each line item. Within a quote, a detailed breakdown of its charges can be found.

• Preview Screenshot
• Code Example
• lineItems Example

4. Request Payment from User

You now need to request crypto payment from the user.

You will use the serializedTransaction returned in the purchase preview from the previous step. The serializedTransaction needs to be structured into a transaction object, which can then be passed to a crypto payment prompter, like viem’s sendTransaction or wagmi’s sendTransactionAsync.

Whichever method you use, it should open the user’s default wallet extension in the browser and allow the user to complete the cross-chain payment.

If you’ve followed along this far you can simply paste the serializedTransaction property returned in your previous API call into the app below. This will allow you to sign and send the transaction.

• Send EVM Payment
• Send Solana Payment
• Code Example
• Full Repository Example

5. 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>

Next Steps

You can now receive payments for anything on the blockchain, and display it in whatever UI you choose to build.

Headless checkout is gated in production. To get started, contact us.