Enterprise feature. Contact us for access.
Introduction
This guide will show you how to accept credit card payments using Crossmint’s Headless Checkout API for memecoin sales with Checkout.com as the payment provider. You’ll learn how to:- Set up credit card payments for Solana memecoin purchases in JavaScript
- Implement a checkout UI using Checkout.com’s Flow component
- Track order status and delivery
For a faster, embedded checkout solution with minimal setup time, see our embedded memecoin
quickstart.
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
Currently, memecoin checkout only supports Solana network. 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
Navigate to the "Integrate" section on the left navigation bar, and ensure you're on the "API Keys" tab.Within the Client-side keys section, click the "Create new key" button in the top right.On the authorized origins section, enter
http://localhost:3000
and click "Add origin".Next, check the scopes labeled orders.create
.Finally, create your key and save it for subsequent steps.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)
- Example:
-
For EVM chains (Ethereum, Polygon, Arbitrum, Base, etc.):
<blockchain>:<contractAddress>:<tokenId>
- Example:
ethereum:0x1234567890123456789012345678901234567890:1
blockchain
: The chain name (ethereum, polygon, arbitrum, base, etc.)contractAddress
: The token contract address (40 hexadecimal characters)tokenId
: For fungible tokens, use "1" as a placeholder value (required by validation schema)
- Example:
EVM Fungible Token Format: While fungible tokens don't conceptually have individual token IDs, Crossmint's validation schema requires the 3-part format
<blockchain>:<contractAddress>:<tokenId>
for all EVM tokens. For fungible tokens (memecoins), use "1" as the tokenId value.Headless Memecoin Checkout
The headless checkout API allows complete control over your checkout experience, including:- Custom UI components and styling
- Custom payment flow sequences
- Integrated analytics and tracking
- Custom error handling and retry logic
- Branded confirmation pages
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://www.crossmint.com/api/2022-06-09/orders
Refer to the complete create order API reference here.
Memecoins are now testable in staging using the xmeme token (
7EivYFyNfgGj8xbUymR7J4LuxUHLKRzpLaERHLvi7Dgu
). All
other token purchases will fail in staging. For production launch with other tokens, contact our sales team.Example Response
Example Response
maxSlippageBps
: Optional, or else default autogenerated slippage will be appliedreceiptEmail
: Required for credit card payments to deliver receiptexecutionParameters.mode
: The execution method for the order. “exact-out” is for NFTs, “exact-in” is for fungible tokens
Render the Checkout.com Flow Component
After creating an order, you’ll need to render the Checkout.com Flow component to collect payment information. The Flow component is a pre-built UI that handles the payment collection process. Reference Documentation:Submit Payment
The Checkout.com Flow component handles the payment submission process automatically. When a user completes the payment form and clicks the payment button, theonPaymentCompleted
callback will be triggered with the payment response.
Unlike with Stripe, you don’t need to manually submit the payment form. The Checkout.com Flow component takes care of the entire payment process, including validation, submission, and handling the response.
Here’s how the payment flow works with Checkout.com:
- The user fills out the payment form rendered by the Flow component
- The user clicks the payment button in the Flow component
- The Flow component validates the payment information
- If valid, the Flow component submits the payment to Checkout.com
- The
onPaymentCompleted
callback is triggered with the payment response - You can use the payment response to update your UI and proceed to the next step
onError
callback will be triggered:
Poll for Status Updates
After making the payment, you’ll need to poll the Get Order API to check on the delivery status and present this information to your user. Endpoint:GET
https://staging.crossmint.com/api/2022-06-09/orders/<orderId>
Refer to the complete get order API reference here.
Example Response:
Handling Refunded Payments
When polling for order status, you may encounter a situation wherepayment.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.
payment.refunded
object includes the following fields:
amount
: The amount that was refundedcurrency
: The currency of the refundtxId
: The on-chain transaction ID the refund was sent inchain
: The blockchain where the refund transaction occurred
- Display an appropriate message to the user indicating that their payment was refunded
- Provide the transaction ID (
txId
) so users can verify the refund on-chain - Prevent any further actions related to the order (such as delivery expectations)
- Provide options for the user to place a new order if desired
Understanding the Code
Quote Expiration
Price quotes are valid for 30 seconds. 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 providerNext Steps
Design Your UI
Learn how to design your headless checkout experience
Handle Webhooks
Implement webhook handling for order updates
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:-
Quote Phase (30-second validity)
- Initial price quote generated
- Requires recipient information to proceed
-
Payment Phase
- Collect payment information (via Crossmint's embedded UI, or your own Checkout.com Flow component if using headless checkout)
- Process credit card payment
- Handle payment completion and errors
-
Delivery Phase
- Purchase memecoin with USDC
- Apply specified slippage tolerance
- Send transfer transaction to recipient wallet
-
Completion
- Order marked as completed
- Receipt email sent to recipient
- Memecoins have been delivered to the recipient wallet
If the quote expires (after 30 seconds), you’ll need to create a new order to get updated pricing. You can choose
the UX flow to handle this.
Refreshing Orders with Checkout.com
If an order expires before payment is completed (e.g., the 30-second quote validity period ends), you can either create a new order or use the refresh quote API:FAQ
Is there a UI Crossmint provides?
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?
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?
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?
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.
Is there a limit on how much of a single token I can sell in a day?
Is there a limit on how much of a single token I can sell in a day?
Yes, there is a volume limit of 1,000,000 USD worth of credit card purchases per day. This limit resets daily at 11:59 PM EST.
What do the order creation parameters mean?
What do the order creation parameters mean?
The order creation request includes several important parameters:Payment Object
method
: Set tocheckoutcom-flow
for Checkout.com credit card paymentscurrency
: Set tousd
for US Dollar paymentsreceiptEmail
: Required for credit card payments to deliver receipt
tokenLocator
: Specifies the memecoin token address in the formatsolana:tokenAddress
executionParameters
:mode
: Set to "exact-in" for memecoin purchases (specifies exact USD amount to spend)amount
: Amount to purchase in USDmaxSlippageBps
: Set to "500" for 5% slippage tolerance. If not provided, the default slippage will be applied from the available liquidity provider.
checkoutcomPaymentSession
: Contains the payment session information from Checkout.comid
: The payment session IDpayment_session_secret
: The secret used to authenticate with Checkout.compayment_session_token
: The token used to initialize the Checkout.com Flow component
checkoutcomPublicKey
: The public key used to initialize the Checkout.com Flow component