Agentic Credentials for Purchases

Allow an AI agent to make purchases on behalf of a consumer using Basis Theory's Agentic Commerce API

On-boarding is required for Production Access. Agentic Commerce supports Visa cards through Visa Intelligent Commerce. Mastercard support via Mastercard Agent Pay is available through a limited waitlist — contact support@basistheory.com to request access.

AI agents need the ability to make purchases on behalf of consumers — booking travel, ordering products, or paying for services. The Agentic Commerce API turns a card stored in Basis Theory into a virtual card credential that an agent can use at checkout, with consumer verification and spending limits built in.

This guide walks through the full flow: creating an agent, enrolling a card, verifying the enrollment with the consumer, setting spending rules via instructions, verifying the instruction, and retrieving virtual card credentials for the agent to use.

Core Concepts

Concept	What It Is	Analogy
Enrollment	A card registered with Visa for AI agent use. Created from a BT card token.	Like adding a card to Apple Pay — the card is "enrolled" so it can be used without exposing the real number.
Verification	Cardholder proves they approve the enrollment. Done via SMS/email OTP + passkey creation.	Like the OTP you get when adding a card to a digital wallet — proves you own the card.
Agent	An AI entity that can use enrolled cards to make purchases. Has a name and a list of enrollments it can access.	Like giving a personal assistant your credit card — but with spending rules attached.
Instruction	A purchase intent with spending rules (max amount, currency, expiry). Must reference an active enrollment.	Like saying "you can spend up to $500 on electronics, but only until Friday."
Credentials	A one-time-use virtual card (number, expiry, CVC) generated from an approved instruction. Used at merchant checkout.	Like a virtual card number that works once and expires. The agent uses this at checkout.

How It Works

1. Collect Card Data — securely collect and tokenize card data using Basis Theory Elements (frontend).
2. Create an Agent — register the AI agent that will make purchases (backend).
3. Enroll a Card — link a Basis Theory card token to the agent via a network provider (backend).
4. Verify Enrollment — the consumer confirms ownership of the card through OTP and passkey creation (frontend).
5. Create an Instruction — set spending rules for a specific purchase (backend).
6. Verify Instruction — the consumer approves the purchase via passkey authentication (frontend).
7. Retrieve Credentials — the agent receives virtual card credentials to complete checkout (backend).

Prerequisites

Basis Theory Account

You need a Basis Theory account to store card data and interact with the Agentic Commerce API. Sign up for free if you do not have one.

Agentic Commerce Access

Enable Agentic Commerce on your tenant by requesting access to the Agentic Commerce quota in the Basis Theory Portal under Settings → Quotas. For sandbox testing, see the test cards and mock flows.

Public Application

You will need a Public Application to authenticate requests. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

• Permissions: token:create, enrollment:verify, agent:instruction:verify

Save the key from the created Public Application as it will be used later in this guide.

This application is used in the frontend for collecting card data and for the consumer verification flows (enrollment and instruction verification).

Private Application

You will need a Private Application to allow your backend to call Basis Theory APIs. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

• Permissions: enrollment:create, enrollment:get, enrollment:delete, agent:create, agent:get, agent:update, agent:delete, agent:instruction:create, agent:instruction:get, agent:instruction:update, agent:instruction:delete, agent:instruction:credentials

Save the key from the created Private Application as it will be used later in this guide.

This application is used in the backend for managing agents, enrollments, instructions, and retrieving credentials.

1. Collecting Card Data with Elements

Use Basis Theory Elements to securely collect and tokenize card data without your systems touching sensitive information.

Configure Elements SDK

Basis Theory Elements are available for the following platforms:

• Web Elements
• iOS Elements
• Android Elements
• React Native Elements

Add Card Elements to Your Page

JavaScript

<div id="cardNumber"></div>
<div style="display: flex;">
  <div id="cardExpirationDate" style="width: 100%;"></div>
  <div id="cardVerificationCode" style="width: 100%;"></div>
</div>
<button id="submit">Submit</button>

import { basistheory } from '@basis-theory/web-elements';

let bt;
let cardNumberElement;
let cardExpirationDateElement;
let cardVerificationCodeElement;

async function init() {
  bt = await basistheory('<PUBLIC_API_KEY>');

  cardNumberElement = bt.createElement('cardNumber', {
    targetId: 'myCardNumber'
  });
  cardExpirationDateElement = bt.createElement('cardExpirationDate', {
    targetId: 'myCardExpiration'
  });
  cardVerificationCodeElement = bt.createElement('cardVerificationCode', {
    targetId: 'myCardVerification'
  });

  await Promise.all([
    cardNumberElement.mount('#cardNumber'),
    cardExpirationDateElement.mount('#cardExpirationDate'),
    cardVerificationCodeElement.mount('#cardVerificationCode'),
  ]);

  cardNumberElement.on('change', ({ cardBrand }) => {
    cardVerificationCodeElement.update({ cardBrand });
  });

  document.getElementById("submit").addEventListener("click", submit);
}

async function submit() {
  try {
    const token = await bt.tokens.create({
      type: 'card',
      data: {
        number: cardNumberElement,
        expiration_month: cardExpirationDateElement.month(),
        expiration_year: cardExpirationDateElement.year(),
        cvc: cardVerificationCodeElement,
      }
    });
    console.log('Token created:', token.id);
    // Send token.id to your backend for enrollment
  } catch (error) {
    console.error(error);
  }
}

init();

React

import React, { useRef, useState } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
  useBasisTheory,
} from '@basis-theory/react-elements';

export default function App() {
  const { bt } = useBasisTheory('<PUBLIC_API_KEY>', { environment: 'test' });
  const cardNumberRef = useRef(null);
  const cardExpirationRef = useRef(null);
  const cardVerificationRef = useRef(null);
  const [cardBrand, setCardBrand] = useState();

  const submit = async () => {
    try {
      const token = await bt?.tokens.create({
        type: 'card',
        data: {
          number: cardNumberRef.current,
          expiration_month: cardExpirationRef.current.month(),
          expiration_year: cardExpirationRef.current.year(),
          cvc: cardVerificationRef.current,
        }
      });
      console.log('Token created:', token.id);
      // Send token.id to your backend for enrollment
    } catch (error) {
      console.error(error);
    }
  };

  return (
    <BasisTheoryProvider bt={bt}>
      <CardNumberElement
        id="myCardNumber"
        ref={cardNumberRef}
        onChange={({ cardBrand }) => setCardBrand(cardBrand)}
      />
      <div style={{ display: 'flex' }}>
        <div style={{ width: "100%" }}>
          <CardExpirationDateElement
            id="myCardExpiration"
            ref={cardExpirationRef}
          />
        </div>
        <div style={{ width: "100%" }}>
          <CardVerificationCodeElement
            id="myCardVerification"
            ref={cardVerificationRef}
            cardBrand={cardBrand}
          />
        </div>
      </div>
      <button onClick={submit}>Submit</button>
    </BasisTheoryProvider>
  );
}

2. Create an Agent

Register the AI agent that will make purchases. Each agent represents a distinct bot or assistant in your system.

curl -X POST https://api.basistheory.com/agentic/agents \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Shopping Assistant"
  }'

Response

{
  "id": "agt_fukICjsY2xzRCECiTCbKM",
  "name": "Shopping Assistant",
  "status": "active",
  "created_at": "2026-01-15T10:30:00Z"
}

Save the agent id — you will use it in all subsequent API calls.

See the Agents API Reference for all available operations.

3. Enroll a Card

Enroll a Basis Theory card token with a network provider. The card brand is auto-detected, and the appropriate network (Visa or Mastercard) handles the enrollment.

curl -X POST https://api.basistheory.com/agentic/enrollments \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "token_id": "<TOKEN_ID>",
    "consumer": {
      "email": "consumer@example.com"
    }
  }'

Response

{
  "id": "enr_wNe75VKdzvojI9iD5fJxr",
  "provider": "visa",
  "status": "pending_verification",
  "card": {
    "brand": "visa",
    "bin": "424032",
    "last4": "0359",
    "expiration_month": 11,
    "expiration_year": 2029,
    "display": {
      "art_url": "https://assets.vims.visa.com/vims/cardart/abc123",
      "background_color": "1A1F71",
      "foreground_color": "FFFFFF",
      "description": "Visa Signature",
      "issuer_name": "Chase"
    }
  },
  "created_at": "2026-01-15T10:31:00Z"
}

The enrollment starts in pending_verification status and moves to active after the consumer completes verification.

See the Enrollments API Reference for all available operations.

4. Verify Enrollment

The consumer must verify they own the card. This involves an OTP challenge from the card network followed by passkey creation for future use. Use the @basis-theory/react-agentic SDK to handle the verification flow in your frontend.

Install the SDK:

npm install @basis-theory/react-agentic

Wrap your application with the BtAiProvider and use the useAgentic hook to call verifyEnrollment:

import { BtAiProvider } from '@basis-theory/react-agentic';

function App() {
  return (
    <BtAiProvider apiKey="<PUBLIC_API_KEY>" environment="production">
      <VerifyEnrollment enrollmentId="enr_wNe75VKdzvojI9iD5fJxr" />
    </BtAiProvider>
  );
}

import { useAgentic } from '@basis-theory/react-agentic';

function VerifyEnrollment({ enrollmentId }) {
  const { verifyEnrollment } = useAgentic();

  const handleVerify = async () => {
    try {
      const result = await verifyEnrollment(enrollmentId);
      console.log('Enrollment verified:', result);
      // Enrollment status is now "active"
    } catch (error) {
      console.error('Verification failed:', error);
    }
  };

  return (
    <button onClick={handleVerify}>
      Verify Card Enrollment
    </button>
  );
}

The BtAiProvider must wrap any component that uses the useAgentic hook. It authenticates requests using your Public API key. Set environment to "test" when using a test tenant — the SDK uses mock providers that don't require HTTPS. See the React Agentic SDK reference for all provider props.

verifyEnrollment renders a modal that guides the consumer through:

1. OTP verification — the card network sends a one-time code to the consumer's registered contact method.
2. Passkey creation — a passkey is created on the consumer's device for faster verification on future requests.

After successful verification, the enrollment status changes from pending_verification to active.

5. Create an Instruction

Once the enrollment is active, create an instruction that defines the spending rules for a specific purchase. Instructions control how much the agent can spend and when the authorization expires.

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
    "amount": {
      "value": "500.00",
      "currency": "USD"
    },
    "description": "Purchase electronics",
    "expires_at": "2026-02-20T00:00:00Z"
  }'

Response

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "pending_verification",
  "amount": {
    "value": "500.00",
    "currency": "USD"
  },
  "expires_at": "2026-02-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Instruction Statuses

Status	Description
pending	Awaiting provider approval
pending_verification	Provider approved; awaiting consumer verification
approved	Consumer verified; credentials can be retrieved
expired	Past the expires_at time
cancelled	Cancelled before use
failed	Verification or provider failure

See the Instructions API Reference for all available operations.

6. Verify Instruction

The consumer must approve each instruction via passkey authentication. Use the verifyInstruction method from the useAgentic hook. This component must also be wrapped by the BtAiProvider (see Step 4).

import { useAgentic } from '@basis-theory/react-agentic';

function VerifyInstruction({ agentId, instructionId }) {
  const { verifyInstruction } = useAgentic();

  const handleVerify = async () => {
    try {
      const result = await verifyInstruction(agentId, instructionId);
      console.log('Instruction approved:', result);
      // Instruction status is now "approved"
    } catch (error) {
      console.error('Verification failed:', error);
    }
  };

  return (
    <button onClick={handleVerify}>
      Approve Purchase
    </button>
  );
}

verifyInstruction renders a modal that prompts the consumer to authenticate with their passkey. After successful verification, the instruction status changes from pending_verification to approved.

7. Retrieve Credentials

Once the instruction is approved, retrieve virtual card credentials from your backend. The response contains a full card number, expiry, and CVC that the agent can use at checkout.

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/credentials \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchant": {
      "name": "Amazon",
      "url": "https://www.amazon.com",
      "country_code": "US"
    },
    "products": [
      {
        "name": "Widget",
        "price": 99.99,
        "quantity": 2
      }
    ],
    "shipping_address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country_code": "US"
    }
  }'

Response

{
  "card": {
    "number": "4111111111111111",
    "expiration_month": "12",
    "expiration_year": "2026",
    "cvc": "123"
  },
  "expires_at": "2026-02-20T00:00:00Z"
}

The credentials returned are virtual card credentials — they look like a card number and CVC but are not actual PCI cardholder data. These credentials should still be treated securely and requests should only be made from your backend.

The agent can now use these credentials to complete a purchase at the specified merchant.

See the Credentials API Reference for request and response details.

FAQ

Which card brands are supported?

Visa cards are supported through Visa Intelligent Commerce. Mastercard support via Mastercard Agent Pay is available through a limited waitlist — contact support@basistheory.com to request access. The card brand is auto-detected during enrollment based on the Basis Theory token data.

Can I also process my own payments with the cards collected?

Yes. To process payments with your tokenized card data, refer to these guides:

• Charge a Card — process payments with various processors including Stripe, Adyen, and others
• Verify a Card — validate cards by performing $0 authorizations before processing actual payments

Can I integrate with other agentic platforms with cards collected?

Once you have a Basis Theory Token, you can use it with any payment processor or agentic payments partner. The Basis Theory platform provides flexible options for integrating without being locked into any specific provider.

• Proxy API Reference — use the proxy to integrate with any HTTP-based payment service
• Invoke Proxy — invoke proxy requests with your tokens

What happens if the consumer does not complete verification?

The enrollment remains in pending_verification status. You can retry verification or delete the enrollment and create a new one. Instructions cannot be created against a pending_verification enrollment.

How long are credentials valid?

Credentials expire based on the expires_at value set on the instruction. After expiry, the instruction status changes to expired and new credentials cannot be retrieved.