Skip to main content
Complete reference documentation for the @uphold/enterprise-travel-rule-widget-web-sdk package.

​
Initialization

Create a new Travel Rule widget instance with a session object obtained from the Create Session endpoint. 
new TravelRuleWidget<T extends TravelRuleWidgetFlow = TravelRuleWidgetFlow>(
  session: TravelRuleWidgetSession,
  options?: TravelRuleWidgetOptions
)

​
Parameters

ParameterTypeRequiredDescription
sessionTravelRuleWidgetSessionYesTravel rule session object obtained from the Create Session endpoint
optionsTravelRuleWidgetOptionsNoConfiguration options for the widget

​
Generic type parameter

The constructor accepts an optional generic type parameter that specifies the flow type. When provided, it enables better type inference for event handlers, particularly for the complete event. Examples: 
// Generic flow type (default)
const widget = new TravelRuleWidget(session);

// Specific flow type for better type inference
const depositWidget = new TravelRuleWidget<'deposit-form'>(session);
const withdrawalWidget = new TravelRuleWidget<'withdrawal-form'>(session);

​
Options

type TravelRuleWidgetOptions = {
  debug?: boolean;
};
PropertyTypeDefaultDescription
debugbooleanfalseEnable debug mode for additional logging

​
Methods

​
mountIframe()

Mounts the widget iframe to the specified DOM element. Parameters:
  • element: The HTML element where the widget should be mounted
Example: 
// Ensure the container has appropriate sizing
const container = document.getElementById('tr-container');

widget.mountIframe(container);
The container element should have explicit dimensions set via CSS. The widget will fill the entire container. Minimum recommended size is 400px width × 600px height for optimal user experience.

​
unmount()

Unmounts and cleans up the widget iframe. Example: 
widget.unmount();
The widget will not unmount itself when a flow is finished, either by successful completion, user cancellation, or unrecoverable error, so it must always be called manually.

​
on()

Registers an event listener for widget events. Parameters:
  • event: The event name to listen for
  • callback: Function to execute when the event is triggered
Example: 
widget.on('complete', (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
});

​
off()

Removes an event listener for widget events. Parameters:
  • event: The event name to stop listening for
  • callback: The specific function to remove (must be the same reference as used in on())
Example: 
const handleComplete = (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
};

// Register the listener
widget.on('complete', handleComplete);

// Remove the listener
widget.off('complete', handleComplete);

​
Events

The widget emits several events during its lifecycle that you can listen to using the on() method.

​
ready

Fired when the Travel Rule widget has finished loading. 
type TravelRuleWidgetReadyEvent = {
  detail: {};
}
Example: 
widget.on('ready', (event: TravelRuleWidgetReadyEvent) => {
  console.log('Travel Rule form is ready');
});

​
complete

Fired when the Travel Rule form is completed. 
type TravelRuleWidgetCompleteEvent<T = TravelRuleWidgetFlow> = {
  detail: {
    value: T;
  };
};
Example: 
widget.on('complete', (event: TravelRuleWidgetCompleteEvent) => {
  console.log('Travel Rule form completed:', event.detail.value);
  
  widget.unmount();
});

​
cancel

Fired when the user cancels the Travel Rule form. 
type TravelRuleWidgetCancelEvent = {
  detail: {};
}
Example: 
widget.on('cancel', (event: TravelRuleWidgetCancelEvent) => {
  console.log('Travel Rule form cancelled by user');

  widget.unmount();
});

​
error

Fired when an unrecoverable error occurs during the Travel Rule flow. 
type TravelRuleWidgetError = {
  name: string;
  code: string;
  message: string;
  details?: Record<string, unknown>;
  cause?: TravelRuleWidgetError;
  httpStatusCode?: number;
}

type TravelRuleWidgetErrorEvent = {
  detail: {
    error: TravelRuleWidgetError;
  };
};
The error object contains a cause property that holds the underlying error. This provides more specific information about what went wrong during the Travel Rule flow. Provider-specific error references: Example: 
// Basic error handling
widget.on('error', (event: TravelRuleWidgetErrorEvent) => {
  console.error('Travel Rule form error:', event.detail.error);

  widget.unmount();
});

// Advanced error handling with cause inspection
widget.on('error', (event: TravelRuleWidgetErrorEvent) => {
  const { error } = event.detail;
  
  console.error('Error:', error.message);
  
  // Check the underlying provider error for more details
  if (error.cause) {
    console.error('Provider error code:', error.cause.code);
    console.error('Provider error message:', error.cause.message);
    
    // Handle specific error cases (example shown for Notabene provider)
    switch (error.cause.details?.identifier) {
      case 'WALLET_CONNECTION_FAILED':
        // Show user-friendly message about wallet connection
        showUserMessage('Unable to connect to your wallet. Please try again.');
        break;
      case 'SERVICE_UNAVAILABLE':
        // Inform user about service unavailability
        showUserMessage('The service is currently unavailable. Please try later.');
        break;
      default:
        // Generic error handling
        showUserMessage('An error occurred. Please contact support.');
    }
  }
  
  widget.unmount();
});

​
Types

​
TravelRuleWidgetSession

The session object obtained from the Create Session endpoint. 
type TravelRuleWidgetSession = {
  url: string;
  token: string;
  flow: TravelRuleWidgetFlow;
  data: TravelRuleWidgetData;
}

​
TravelRuleWidgetFlow

Represents the different flows supported by the Travel Rule widget. 
type TravelRuleWidgetFlow = 'deposit-form' | 'withdrawal-form';

​
TravelRuleWidgetData

The data object included in the session, containing context for the flow. 
type TravelRuleWidgetData = {
  provider: string; // Currently supported: 'notabene'
  parameters: object;
};

​
TravelRuleResult

The result object returned upon successful completion of the Travel Rule form. 
type TravelRuleResult = object;
The event.detail.value object is an opaque data structure that should be used as-is when resolving RFIs or creating transactions.

​
Usage example

Here’s a complete example showing all events and type safety: 
import { TravelRuleWidget } from '@uphold/enterprise-travel-rule-widget-web-sdk';

// Initialize the widget with type inference
const widget = new TravelRuleWidget<'deposit-form'>(session, { debug: true });

// Handle ready event
widget.on('ready', () => {
  console.log('Travel Rule form is ready');
});

// Handle completion with type-safe result
widget.on('complete', (event) => {
  console.log('Travel Rule form completed:', event.detail.value);

  widget.unmount();
});

// Handle cancellation
widget.on('cancel', () => {
  console.log('Travel Rule form cancelled by user');

  widget.unmount();
});

// Handle errors with cause inspection
widget.on('error', (event) => {
  const { error } = event.detail;
  
  console.error('Travel Rule form error:', error.message);
  
  // Log the underlying provider error details
  if (error.cause) {
    console.error('Provider error:', {
      code: error.cause.code,
      message: error.cause.message,
      details: error.cause.details
    });
  }

  widget.unmount();
});

// Mount the widget
widget.mountIframe(document.getElementById('tr-container'));