@basis-theory/react-agentic

[!IMPORTANT] HTTPS is required. The card network SDKs used for verification (Visa and Mastercard) require your application to be served over HTTPS, even in development. Verification will fail on plain HTTP.

For local development, we recommend Cloudflare Quick Tunnels to expose your local server over HTTPS with zero configuration:

# Install cloudflared
brew install cloudflared

# Start a quick tunnel pointing to your local dev server
cloudflared tunnel --url http://localhost:3000

This gives you a temporary https://*.trycloudflare.com URL you can use for testing.

Installation

npm install @basis-theory/react-agentic

Setup

Wrap your app with BtAiProvider:

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

function App() {
  return (
    <BtAiProvider
      apiKey="your-public-api-key"
      environment="production"
      passkeyTimeoutMs={120000}        // optional: 2 min passkey timeout
      sessionReadyTimeoutMs={15000}    // optional: 15s session ready timeout
    >
      <YourComponent />
    </BtAiProvider>
  );
}

BtAiProvider Props

| Prop | Type | Required | Description | |------------------------|-------------------------------|----------|---------------------------------------| | apiKey | string | Yes | A Basis Theory AI public API key | | environment | 'production' \| 'test' | No | Environment to use (default: production) | | agenticApiUrl | string | No | Override the agentic commerce API base URL | | passkeyTimeoutMs | number | No | Timeout in ms for Visa passkey authentication (default: 60000) | | sessionReadyTimeoutMs| number | No | Timeout in ms for Visa session readiness after refresh (default: 10000) |

SDK Ready State

The useAgentic hook exposes a ready boolean that indicates when the underlying card network SDKs (Visa and Mastercard) have finished initializing. Use this to prevent calling verification methods before the SDK is ready.

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

function VerifyButton() {
  const { ready, verifyEnrollment } = useAgentic();

  return (
    <button onClick={() => verifyEnrollment('enrollment-id')} disabled={!ready}>
      {ready ? 'Verify' : 'Initializing...'}
    </button>
  );
}

• false initially and during SDK initialization
• true once at least one card network SDK (Visa or Mastercard) is ready
• Resets to false if the provider unmounts or the environment changes

All verify methods (verifyEnrollment, verifyInstruction) automatically wait for ready before executing, so it is safe to call them before initialization completes — they will queue until the SDK is ready.

For granular per-network status, use getStatus() which returns { visa: boolean, mastercard: boolean }.

Hooks

useAgentic() / useBtAi()

The primary hook for interacting with the SDK. Returns verification methods and SDK state.

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

function MyComponent() {
  const {
    ready,              // boolean - whether the SDK is ready
    apiKey,             // string - current API key
    environment,        // string - current environment
    updateApiKey,       // (newKey: string) => void
    getStatus,          // () => { visa: boolean, mastercard: boolean }
    verifyEnrollment,   // (enrollmentId: string) => Promise
    verifyInstruction,  // (agentId: string, instructionId: string) => Promise
  } = useAgentic();
}

Both useAgentic() and useBtAi() return the same interface — use whichever you prefer.

useEnrollmentVerification()

Action-based hook for building a custom enrollment verification UI. Render your UI based on status and call the corresponding action to advance the flow.

This hook handles the complete orchestration for both card networks:

• Visa: OTP method selection → OTP input → passkey creation → completion
• Mastercard: popup-based authentication → completion

Statuses

| Status | Description | Available Actions | |---|---|---| | idle | Not started | start() | | loading | Async operation in progress | — | | otp_required | Show OTP method picker (otpMethods available) | selectOtpMethod(methodId) | | otp_sent | Show OTP code input | submitOtp(code) | | passkey_required | Visa passkey creation needed | confirmPasskey() | | popup_required | Mastercard popup needed | confirmPasskey(), retry() | | verified | Verification complete | — | | error | Something went wrong (error has message) | retry(), start() |

Example

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

function CustomEnrollmentUI({ enrollmentId }) {
  const {
    status,           // current status (see table above)
    error,            // string | null — error message when status is 'error'
    otpMethods,       // available OTP methods when status is 'otp_required'
    start,            // () => Promise — begin or restart verification
    selectOtpMethod,  // (methodId: string) => Promise — select an OTP delivery method
    submitOtp,        // (code: string) => Promise — submit the OTP code
    confirmPasskey,   // () => Promise — trigger passkey creation (Visa) or popup (Mastercard)
    retry,            // () => Promise — retry the current step (or restart if needed)
    cancel,           // () => void — cancel and reset to idle
  } = useEnrollmentVerification({ enrollmentId });

  // Render your own UI based on status
}

How to Build Your Own UI

• Call start() to kick off the enrollment verification flow
• Switch on status to render the appropriate UI for each step:
  • loading — show a spinner or loading indicator
  • otp_required — render a list/buttons from otpMethods and call selectOtpMethod(methodId) on selection
  • otp_sent — render a code input field and call submitOtp(code) on submit
  • passkey_required — show a prompt/button explaining passkey creation and call confirmPasskey()
  • popup_required — show a prompt/button explaining Mastercard popup auth and call confirmPasskey()
  • verified — show a success message and proceed with your app flow
  • error — display error message with a button to retry() or start() again
• Use cancel() to let the user abort and reset to idle at any point
• The hook manages all card-network orchestration internally — you only need to render UI and call actions

useInstructionVerification()

Action-based hook for building a custom instruction verification UI. Handles passkey authentication for both card networks:

• Visa: passkey authentication → completion
• Mastercard: popup-based authentication → completion

Statuses

| Status | Description | Available Actions | |---|---|---| | idle | Not started | start() | | loading | Async operation in progress | — | | passkey_required | Visa passkey auth needed | confirmPasskey() | | popup_required | Mastercard popup needed | confirmPasskey(), retry() | | verified | Verification complete | — | | error | Something went wrong (error has message) | retry(), start() |

Example

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

function CustomInstructionUI({ agentId, instructionId }) {
  const {
    status,           // current status (see table above)
    error,            // string | null — error message when status is 'error'
    start,            // () => Promise — begin or restart verification
    confirmPasskey,   // () => Promise — trigger passkey auth (Visa) or popup (Mastercard)
    retry,            // () => Promise — retry the current step (or restart if needed)
    cancel,           // () => void — cancel and reset to idle
  } = useInstructionVerification({ agentId, instructionId });

  // Render your own UI based on status
}

How to Build Your Own UI

• Call start() to kick off the instruction verification flow
• Switch on status to render the appropriate UI for each step:
  • loading — show a spinner or loading indicator
  • passkey_required — show a prompt/button explaining Visa passkey authentication and call confirmPasskey()
  • popup_required — show a prompt/button explaining Mastercard popup auth and call confirmPasskey()
  • verified — show a success message and proceed with your app flow
  • error — display error message with a button to retry() or start() again
• Use cancel() to let the user abort and reset to idle at any point
• The hook manages all card-network orchestration internally — you only need to render UI and call actions

Enrollment Verification

Opens a modal that guides the user through enrollment verification. Automatically handles both Visa (OTP + passkey creation) and Mastercard (popup authentication) flows.

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

function EnrollmentExample() {
  const { verifyEnrollment } = useAgentic();

  const handleVerify = async () => {
    try {
      const result = await verifyEnrollment('enrollment-id');
      console.log('Verified:', result);
    } catch (err) {
      console.error('Verification failed:', err.message);
    }
  };

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

Instruction Verification

Opens a modal that guides the user through instruction verification (passkey authentication). Supports both Visa and Mastercard cards.

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

function InstructionExample() {
  const { verifyInstruction } = useAgentic();

  const handleVerify = async () => {
    try {
      const result = await verifyInstruction('agent-id', 'instruction-id');
      console.log('Verified:', result);
    } catch (err) {
      console.error('Verification failed:', err.message);
    }
  };

  return <button onClick={handleVerify}>Verify Instruction</button>;
}

Utilities

collectDeviceContext()

Collects browser and device fingerprint data sent with verification requests. Useful if you're building a fully custom integration.

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

const context = collectDeviceContext();
// { userAgent, language, platform, screenResolution, ... }

License

MIT