Initialization

Installation

npm install @btai/web --save
 
npm install @btai/react --save

React Provider Setup

import { btAi } from '@btai/js-sdk';
 
// ... get signed jwt from your backend
 
// initialize sdk
const btAi = await btAi.init(jwt);

Hook Usage Example

import { useBasisTheory } from '@basis-theory/react-sdk';
 
function PaymentComponent() {
  const { 
    bt,           // BasisTheory SDK instance
    isInitialized, // Boolean: is SDK ready
    isLoading,     // Boolean: is SDK initializing  
    initError,     // Error object if initialization failed
    apiKey,        // Current API key/JWT
    environment,   // Current environment
    getSessionKey, // Helper: get session key
    isReady,       // Helper: check if ready for use
    getStatus      // Helper: get current status string
  } = useBasisTheory();
 
  if (!isReady()) {
    return <div>SDK Status: {getStatus()}</div>;
  }
 
  return (
    <div>
      <p>SDK is ready with session key: {getSessionKey()}</p>
    </div>
  );
}

Configuration Options

BasisTheoryProvider Props

Parameter	Type	Required	Description
`jwt`	string	Yes	JWT token for authentication (despite the name, this should be a JWT)
`environment`	string	No	Environment: `"production"` or `"sandbox"` (default: `"production"`)
`children`	ReactNode	Yes	React components that will have access to the SDK

useBasisTheory Hook Returns

Property	Type	Description
`bt`	object	BasisTheory SDK instance (null until initialized)
`isInitialized`	boolean	Whether the SDK has finished initializing
`isLoading`	boolean	Whether the SDK is currently initializing
`initError`	Error \| null	Error object if initialization failed
`environment`	string	Current environment setting
`getSessionKey()`	function	Returns the session key from the initialized SDK
`isReady()`	function	Returns true if SDK is ready for use
`getStatus()`	function	Returns current status: “loading”, “error”, “ready”, or “idle”
`verifyPurchaseIntent(projectId, purchaseIntentId)`	function	Triggers customer verification for a purchase intent

Error Handling

The SDK handles several types of initialization errors:

Common Errors

Invalid API key format: Empty or malformed JWT token
Invalid environment: Environment not “production” or “sandbox”
SDK not loaded: BasisTheory script not included in HTML
Already initialized: SDK instance already exists (handled gracefully)

Error Handling Example

function ErrorHandlingExample() {
  const { initError, isLoading, isInitialized } = useBasisTheory();
 
  if (isLoading) return <div>Loading...</div>;
  
  if (initError) {
    // Handle specific error types
    if (initError.message.includes('API key')) {
      return <div>Please provide a valid JWT token</div>;
    }
    
    if (initError.message.includes('BasisTheory SDK not loaded')) {
      return <div>Please include the BasisTheory script tag</div>;
    }
    
    return <div>Initialization error: {initError.message}</div>;
  }
  
  if (!isInitialized) return <div>Initializing...</div>;
  
  return <div>SDK Ready!</div>;
}

Important Notes

JWT Token: Despite the prop name apiKey, you must provide a valid JWT token, not a static API key
Script Dependency: The BasisTheory SDK script must be loaded before the provider initializes
Single Instance: The provider prevents duplicate initialization and reuses existing instances
Automatic Cleanup: The provider handles cleanup when components unmount
Environment: Use “sandbox” for development and testing, “production” for live applications