Payment Methods

Before a purchase is initiated, your users must either save a card on file with them, or give them stablecoins in a crypto wallet. This guide explains how to do each of those flows.

Pay with a user’s credit or debit card

Use this option if you want the agent to pay with a user’s card just in time.

Tokenize and securely store the user’s card so the agent can use it in future payments compliantly, without ever touching sensitive card data.Start testing today by creating a Crossmint project and test API key:

Crossmint Project

Create a project in the Crossmint Console (staging environment)

Server-side API Key

Obtain a server-side API key from the Overview page and save it for later use

Integration Steps

Crossmint and Basis Theory are closely collaborating to enable this solution.

These APIs are under development and subject to change.

Retrieve Credentials

In order to tokenize a user’s card, obtain the necessary keys from Basis Theory by calling the following Crossmint route with your Crossmint API key:

GET https://staging.crossmint.com/api/unstable/setupTokenizeCard

The response looks as follows:

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

Tokenize Card

Tokenizing a user’s card enables the agent to handle payments without getting access to sensitive card information.Render a card input form using Basis Theory’s SDK and the basisTheoryAPIKey obtained above to tokenize and save the user’s card.You can choose between generating an agentic token or a normal card token.

The “Agentic Token” option only works in staging and is subject to change.

Agentic Token (Mastercard supported)

Test cards:

Mastercard: 5120350110725465

For CVV or CVC, use any 3 digit number and for Expiry Date or MM/YY, enter any future date.

"use client";
import React, { useEffect, useRef, useState } from "react";
import {
// @ts-ignore
useBasisTheory as useBasisTheoryAI,
// @ts-ignore
BasisTheoryProvider as BasisTheoryAIProvider,
} from "@basis-theory-ai/react";
import {
CardElement,
useBasisTheory,
BasisTheoryProvider,
} from "@basis-theory/react-elements";
import { CROSSMINT_BASE_URL, CROSSMINT_CLIENT_API_KEY, ENTITY_ID } from "@/consts";

function CheckoutWithBT({ jwt, apiKey }: { jwt: string; apiKey: string }) {
const { bt } = useBasisTheory(apiKey);
return (
    <BasisTheoryProvider bt={bt}>
    <PaymentForm jwt={jwt} apiKey={apiKey} />
    </BasisTheoryProvider>
);
}

export default function CheckoutPage() {
const [jwt, setJwt] = useState(null);
const [apiKey, setApiKey] = useState(null);
const [loading, setLoading] = useState(true);

// Fetch API key on mount
useEffect(() => {
    async function fetchApiKey() {
    try {
        const res = await fetch(
          `${CROSSMINT_BASE_URL}/api/unstable/setupTokenizeCard`,
          {
            headers: {
              "x-api-key": CROSSMINT_API_KEY,
            },
          }
        );
        const data = await res.json();
        setJwt(data.jwt);
        setApiKey(data.basisTheoryAPIKey);
    } catch (error) {
        console.error("Failed to fetch API key:", error);
    } finally {
        setLoading(false);
    }
    }
    fetchApiKey();
}, []);

if (loading || !jwt || !apiKey) {
    return <div>Loading Basis Theory...</div>;
}

return (
    <BasisTheoryAIProvider apiKey={jwt}>
    <CheckoutWithBT jwt={jwt} apiKey={apiKey} />
    </BasisTheoryAIProvider>
);
}

function PaymentForm({ jwt, apiKey }: { jwt: string; apiKey: string }) {
const cardRef = useRef(null);
const { verifyPurchaseIntent } = useBasisTheoryAI();
const { bt } = useBasisTheory();
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    if (!bt) {
      throw new Error("Basis Theory not initialized");
    }

    const token = await bt.tokens.create({
      type: "card",
      data: cardRef.current,
    });

    console.log({ token });

    const createPaymentMethodRequestBody = {
      entityId: ENTITY_ID,
      tokenId: token.id,
    };

    const response = await fetch(
    `https://api.sandbox.basistheory.ai/projects/6f1ab300-8dca-4ac4-8766-ad7e7a735b0b/payment-methods`,
    {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${jwt}`,
        },
        body: JSON.stringify(createPaymentMethodRequestBody),
    }
    );
    const paymentMethod = await response.json();
    console.log("paymentMethod", paymentMethod);

    const paymentIntentData = {
      paymentMethodId: paymentMethod.id,
    };

    const response2 = await fetch(
    `${CROSSMINT_BASE_URL}/api/unstable/setupTokenizeCard/createPurchaseIntent`,
    {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": CROSSMINT_CLIENT_API_KEY,
        },
        body: JSON.stringify(paymentIntentData),
    }
    );

    const purchaseIntent = await response2.json();

    console.log("purchaseIntent", purchaseIntent);

    await verifyPurchaseIntent(
      "6f1ab300-8dca-4ac4-8766-ad7e7a735b0b",
      purchaseIntent.purchaseIntentId
    );

    // As described in Step 4 below
    const response3 = await fetch(`${CROSSMINT_BASE_URL}/api/2022-06-09/orders`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-client-secret": CROSSMINT_CLIENT_API_KEY,
      },
      body: JSON.stringify({
        recipient: {
        email: "john.smith@example.com",
        physicalAddress: {
            name: "John",
            line1: "Smith",
            city: "New York City",
            postalCode: "10007",
            country: "US",
            state: "NY",
        },
        },
        locale: "en-US",
        payment: {
          receiptEmail: "john.smith@example.com",
          method: "card-token",
        },
        lineItems: [
        {
        productLocator:
            "amazon:https://www.amazon.com/Croix-Sparkling-Water-Grapefruit-Count/dp/B00EEN4OI8"
        }
        ],
    }),
    });
    const { order } = await response3.json();

    console.log("order", order);
    
    // As described in Step 5 below
    await fetch(`${CROSSMINT_BASE_URL}/api/unstable/orders/${order.orderId}/payment`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-client-secret": CROSSMINT_CLIENT_API_KEY,
        },
        body: JSON.stringify({
            token: `vic:${purchaseIntent.purchaseIntentId}`,
        }),
    });
};

return (
    <form
    onSubmit={handleSubmit}
    >
    <CardElement id="my-card" ref={cardRef} />
    <button
        type="submit"
    >
        Register
    </button>
    </form>
);
}

Card Token (All card networks supported)

For other card networks, use a Crossmint test card to test the token generation step.

"use client";
import React, { useRef, useState, FormEvent } from "react";
import {
  BasisTheoryProvider,
  useBasisTheory,
  CardElement,
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
} from "@basis-theory/basis-theory-react";

// Obtained from Step 1
const PUBLIC_KEY = process.env.NEXT_PUBLIC_BT_PUBLIC_KEY!;

export default function CheckoutPage() {
  // Initialize with your API key using the hook
  const { bt } = useBasisTheory(PUBLIC_KEY, { elements: true });
  if (!bt) {
    return <div>Loading...</div>;
  }
  return (
    <BasisTheoryProvider bt={bt}>
      <PaymentForm />
    </BasisTheoryProvider>
  );
}

function PaymentForm() {
  const { bt } = useBasisTheory(PUBLIC_KEY, { elements: true });
  const cardNumberRef = useRef<any>(null);
  const cardExpirationRef = useRef<any>(null);
  const cardCvcRef = useRef<any>(null);
  const [cardholderName, setCardholderName] = useState("");
  if (!bt) {
    return <div>Loading...</div>;
  }
  const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();

    try {
      if (
        !cardNumberRef.current ||
        !cardExpirationRef.current ||
        !cardCvcRef.current ||
        !cardholderName
      ) {
        console.error(
          "One or more card elements are not ready or cardholder name is not set"
        );
        return;
      }
      const token = await bt.tokens.create({
        type: "card",
        data: {
          number: cardNumberRef.current,
          expiration_month: cardExpirationRef.current.month(),
          expiration_year: cardExpirationRef.current.year(),
          cvc: cardCvcRef.current,
          cardholder_name: cardholderName,
        },
      });

      await fetch(
        `${CROSSMINT_BASE_URL}/api/unstable/setupTokenizeCard/registerToken`,
        {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "x-api-key": CROSSMINT_CLIENT_API_KEY,
          },
          body: JSON.stringify({
            token: token.id,
          }),
        }
      );

      console.log("Token created:", token.id);
    } catch (error: any) {
      console.error("Error creating token:", error.details);
    }
  };

  return (
    <form
      onSubmit={handleSubmit}
      style={{ display: "grid", gap: 12, maxWidth: 360 }}
    >
      <input
        type="text"
        name="cardholderName"
        placeholder="Cardholder name"
        value={cardholderName}
        onChange={(e) => setCardholderName(e.target.value)}
        autoComplete="cc-name"
        required
      />
      <CardNumberElement
        id="card-number"
        ref={cardNumberRef}
        placeholder="Card number"
        style={{
          base: {
            color: "#111",
            fontSize: "16px",
            fontFamily: "inherit",
            "::placeholder": { color: "#888" },
          },
          invalid: { color: "#b00020" },
        }}
      />
      <div style={{ display: "grid", gridTemplateColumns: "1fr 1fr", gap: 12 }}>
        <CardExpirationDateElement
          id="card-expiration"
          ref={cardExpirationRef}
          placeholder="MM/YY"
          style={{
            base: {
              color: "#111",
              fontSize: "16px",
              fontFamily: "inherit",
              "::placeholder": { color: "#888" },
            },
            invalid: { color: "#b00020" },
          }}
        />
        <CardVerificationCodeElement
          id="card-cvc"
          ref={cardCvcRef}
          placeholder="CVC"
          style={{
            base: {
              color: "#111",
              fontSize: "16px",
              fontFamily: "inherit",
              "::placeholder": { color: "#888" },
            },
            invalid: { color: "#b00020" },
          }}
        />
      </div>
      <button type="submit">Register</button>
    </form>
  );
}

Here is an example of how the above card form can look. Its design can be easily customized by the developer.

This step is only needed when using non-agentic Card Tokens.

Call the following Crossmint API with the obtained API key from the Crossmint Console where the TODO comment is above, in order to register the token with Crossmint:


POST https://staging.crossmint.com/api/unstable/setupTokenizeCard/registerToken

{
  "token": "9f243106-d4a4-4327-a7cb-e3ec22031ed2" // Obtained from Step 2
}

No response body is expected from this call, simply a 200 response.

Create Order

Call Crossmint’s Create Order API and specify card-token as the payment method (with the same Crossmint API key used above):

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

{
  "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"
    }
  ]
}

Notes on productLocator:General Websites

Use url: prefix for any website with guest checkout on the internet
Specify product variants by adding a suffix 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 pay on your behalf & act as Merchant of Record
Specify product variants by ID, fetching them using the route found in Step 3 here

url:https://www.nike.com/t/downshifter-13-mens-road-running-shoes-extra-wide-4M0LNf:<

Amazon

Use amazon: prefix instead of url: for Amazon products
Crossmint will complete the transaction on your behalf
No variants are needed as Amazon URLs are unique

Complete Payment with Card Token

Obtain the orderId from Step 4’s response and call the following Crossmint API:

POST https://staging.crossmint.com/api/unstable/orders/{{orderId}}/payment

{
  "token": "9f243106-d4a4-4327-a7cb-e3ec22031ed2" // Obtained from Step 2
}

The response will show that the payment is successful. Check the recipient’s email for a purchase receipt.

See it in action

Clone and Setup

git clone https://github.com/Crossmint/crossmint-checkout-tokenized-cc-demo
cd crossmint-checkout-tokenized-cc-demo
npm install

Configure Environment

Add your Crossmint API key to the src/app/consts.ts file.

Start the Application

npm run dev

Setup HTTPS Tunnel

Note that due to security reasons, the card verification process cannot happen in an HTTP environment. Use ngrok to create an HTTPS tunnel:

  ngrok http 3000 (or the port shown in your terminal)

Open your browser

Navigate to the HTTPS URL provided by ngrok (e.g., https://abc123.ngrok.io) instead of the local HTTP URL

Solution Guides

Agentic Commerce

n8n

StoryKit

Pay with a user’s credit or debit card

Integration Steps

See it in action

Solution Guides

Agentic Commerce

n8n

StoryKit

​Pay with a user’s credit or debit card

​Integration Steps

​See it in action

Pay with a user’s credit or debit card

Integration Steps

See it in action