With Crossmint, agents can transact on behalf of users using saved cards on file, stablecoins, or Crossmint credits. This guide explains how to implement each of those methods.

​
Integration Steps

Agentic tokens can only be generated for cards issued by Mastercard and Visa.
1

Obtain Crossmint API key

Create a project in the Crossmint Console (staging environment), obtain a server-side API key from the Overview page, and make sure to save it for later use.
2

Obtain Basis Theory credentials

curl --request GET \
    --url 'https://staging.crossmint.com/api/unstable/setupTokenizeCard' \
    --header 'X-API-KEY: <x-api-key>'

{
  "basisTheoryAPIKey": "key_test_us_pub_LyApUWWyCJ4PqiTEgrSmeK",
  "jwt": "eyJhbG...",
  "basisTheoryProjectId": "6f1ab30..."
}
3

Collect user's card

Use the basisTheoryAPIKey obtained above to render a card input form using Basis Theory’s SDK.
"use client";
import React, { useRef, FormEvent } from "react";
import {
  BasisTheoryProvider,
  useBasisTheory,
  CardElement,
} from "@basis-theory/basis-theory-react";

const basisTheoryAPIKey = "<basisTheoryAPIKey_from_step_2>";

export default function AgenticTokenizeCard() {
  const { bt } = useBasisTheory(basisTheoryAPIKey, { elements: true });
  const cardRef = useRef<any>(null);
  if (!bt) {
    return <div>Loading...</div>;
  }
  const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const token = await bt.tokens.create({ type: "card", data: cardRef.current });
    console.log("Card token:", token.id); 
  };
  return (
    <BasisTheoryProvider bt={bt}>
      <form onSubmit={handleSubmit}>
        <CardElement id="agentic-card" ref={cardRef} />
        <button type="submit">Save card</button>
      </form>
    </BasisTheoryProvider>
  );
}
Payment checkout example
Be sure to fill in the variable basisTheoryAPIKey with the value obtained from Step 2.Use this card to test the flow in staging:
  • Mastercard: 5186161910000103
  • For CVV or CVC, use any 3 digit number
  • For Expiry Date or MM/YY, enter any future date
4

Create purchase intent

Use the jwt and basisTheoryProjectId from Step 2 and card token (token.id) from Step 3 to create a Basis Theory payment method.
curl --request POST \
    --url 'https://api.sandbox.basistheory.ai/projects/{{basisTheoryProjectId}}/payment-methods' \
    --header 'Authorization: Bearer {{jwt}}' \
    --header 'Content-Type: application/json' \
    --data '{
      "entityId": "crossmint-staging",
      "tokenId": "<card_token_id_from_step_3>"
    }'

{
  "id": "8cb5cbb6-b2ac-4ea7-a73f-f55ca99f834c",
  "entityId": "crossmint-staging",
  "type": "card",
  "card": {
      "brand": "mastercard",
      "type": "credit",
      "details": {
          "bin": "51861619",
          "last4": "0103",
          "expirationYear": 2034,
          "expirationMonth": 12
      },
      "display": {
          "artUrl": "https://sbx.assets.mastercard.com/card-art/combined-image-asset/6713d73d-a701-4bd2-bc9b-2e98940de9c7.png",
          "issuerName": "Test Issuer®",
          "description": "MasterCard Test Bank",
          "backgroundColor": "EB001B",
          "foregroundColor": "0F0F0F"
      }
  },
  "credentialTypes": [
      "virtual-card"
  ],
  "createdAt": "2025-09-19T14:42:43.059Z"
}
Then use the returned payment method id (id) to create a Crossmint purchase intent.
curl --request POST \
    --url 'https://staging.crossmint.com/api/unstable/setupTokenizeCard/createPurchaseIntent' \
    --header 'x-api-key: <x-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "paymentMethodId": "<id_from_previous_call>"
    }'

{
  "purchaseIntentId": "3035e8aa-3a3e-4c2e-8e7e-4be2f591f047"
}
5

Create order

Call Crossmint’s Create Order API with the payment method set to card-token.
curl --request POST \
    --url 'https://staging.crossmint.com/api/2022-06-09/orders' \
    --header 'x-api-key: <x-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "recipient": {
        "email": "john.d@example.com",
        "physicalAddress": {
          "name": "John D",
          "line1": "123 ABC Street",
          "city": "New York City",
          "state": "NY",
          "postalCode": "10007",
          "country": "US"
        }
      },
      "locale": "en-US",
      "payment": {
        "receiptEmail": "john.d@example.com",
        "method": "card-token"
      },
      "lineItems": [
        {
          "productLocator": "url:https://www.nike.com/t/maverick-valor-course-tint-sunglasses-1TrBw8KB/IF0969X-021"
        }
      ]
    }'

{
  "clientSecret": "...",
  "order": {
    "orderId": "b2959ca5-65e4-466a-bd26-1bd05cb4f837",
    "phase": "payment",
  }
  ...
}
General Websites
  • Use url: prefix for any website with guest checkout on the internet
  • Product variants are specified in natural language, as shown below:
url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:9
url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:size-9
url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:size should be 9
url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:{"size":9}
Shopify
  • Use shopify: prefix for Crossmint to place the order as Merchant of Record
  • Specify product variants by ID, fetching them using the route in Step 3 here
url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:<
Amazon
  • Use amazon: prefix for Crossmint to place the order as Merchant of Record
  • No variants are needed as Amazon URLs are unique
amazon:https://www.amazon.com/Sparkling-Naturally-Essenced-Calories-Sweeteners/dp/B00O79SKV6
6

Complete payment

Use the orderId from Step 5’s response and the card token (token.id) from Step 3 to complete the payment.
curl --request POST \
    --url 'https://staging.crossmint.com/api/unstable/orders/{{orderId}}/payment' \
    --header 'x-api-key: <x-api-key>' \
    --header 'Content-Type: application/json' \
    --data '{
      "token": "vic:<card_token_id_from_step_3>"
    }'
Check the recipient’s email inbox specified in Step 5 for a purchase receipt.

Try it out

See a demo that puts the above together in a repo you can quickly get started with