Travel Rule deposit via the Travel Rule Widget

This guide walks you through resolving a Travel Rule request for information on an on-hold crypto deposit using the Travel Rule Widget — from detecting the on-hold status to letting the widget collect and submit proof.

Want to collect and submit proof yourself instead of using a managed UI? See Travel Rule deposit via the REST API — it also documents the RFI’s context and proofOptions fields in detail.

Prerequisites

The user has completed onboarding and has the required capabilities enabled.

Walkthrough

Detect the on-hold transaction

When a crypto deposit is placed on hold due to a Travel Rule requirement, Uphold sends a core.transaction.status-changed webhook with status: on-hold and statusDetails.reason: pending-requests-for-information.

{
  "id": "<eventId>",
  "type": "core.transaction.status-changed",
  "createdAt": "2024-07-24T15:22:39Z",
  "data": {
    "transaction": {
      "id": "b97c7f64-1c34-4b6e-a8f2-3d5c4e9a1b72",
      "status": "on-hold",
      "statusDetails": {
        "reason": "pending-requests-for-information"
      }
    }
  }
}

Abbreviated — the transaction object includes additional fields.

If you are using polling instead of webhooks, check for status: on-hold and statusDetails.reason: pending-requests-for-information on the transaction object.

Notify the user

Surface the on-hold status to the user out-of-band (email or push notification) — deposits can sit on-hold indefinitely until resolved.

Resolve the Travel Rule RFI

The Travel Rule Widget allows the user to resolve a Travel Rule RFI for a specific transaction. Create a session tied to the transaction by calling Create session with flow: deposit-form and the data property containing the referenceId — the transaction’s id. No prior call to list RFIs is needed; the widget resolves the pending RFI for that transaction on your behalf.

POST /widgets/travel-rule/sessions
{
  "flow": "deposit-form",
  "data": {
    "referenceId": "b97c7f64-1c34-4b6e-a8f2-3d5c4e9a1b72"
  }
}

A successful response returns the session data needed to initialize the widget.

{
  "session": {
    "flow": "deposit-form",
    "url": "https://travel-rule-widget.enterprise.uphold.com/",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "data": {
      "provider": "notabene",
      "parameters": {
        "init": {
          "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
          "nodeUrl": "https://api.notabene.id"
        },
        "options": {},
        "transaction": {
          "amountDecimal": 0.05,
          "asset": "BTC",
          "source": ["bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"],
          "customer": {
            "name": "John Doe",
            "type": "natural"
          }
        }
      }
    }
  }
}

Widget sessions expire after 2 minutes. If the session expires before the user opens the widget — or while they are mid-form — the widget emits an error event. Create a new session and re-mount to let the user retry.

Initialize the widget using the session returned from the API and mount it into your application. The widget does not unmount itself — always call unmount() after handling any event.

import { TravelRuleWidget } from '@uphold/enterprise-travel-rule-widget-web-sdk';

const widget = new TravelRuleWidget<'deposit-form'>(session, { debug: true });

widget.on('ready', () => {
  // Widget has loaded and is ready for user interaction
});

widget.on('complete', (event) => {
  // Widget has completed successfully — unmount the widget and listen for the webhook to confirm the transaction status change
  widget.unmount();
});

widget.on('cancel', () => {
  widget.unmount();
});

widget.on('error', (event) => {
  console.error('Travel Rule widget error:', event.detail.error);
  widget.unmount();
});

widget.mountIframe(document.getElementById('travel-rule-container'));

<div id="travel-rule-container"></div>

<script>
  // session is `response.session` from your backend
  async function initializeTravelRuleWidget(session) {
    const container = document.getElementById('travel-rule-container');
    const sessionOrigin = new URL(session.url).origin;

    const iframe = document.createElement('iframe');
    iframe.src = session.url;
    iframe.setAttribute('allow', "clipboard-write 'src'; clipboard-read 'src';");
    iframe.style.width = '100%';
    iframe.style.height = '100%';
    iframe.style.border = 'none';

    function teardown() {
      window.removeEventListener('message', onMessage);
      iframe.remove();
    }

    function onMessage(event) {
      if (event.origin !== sessionOrigin) return;

      switch (event.data?.type) {
        case 'load':
          iframe.contentWindow.postMessage({ ...session, options: {}, type: 'init' }, sessionOrigin);
          break;
        case 'ready':
          // Widget has loaded and is ready for user interaction
          break;
        case 'complete': {
          // Widget has completed successfully — unmount the widget, confirm the RFI is resolved, and listen for the webhook to confirm the transaction status change
          teardown();
          break;
        }
        case 'cancel':
          teardown();
          break;
        case 'error':
          console.error('Travel Rule widget error:', event.data.error);
          teardown();
          break;
      }
    }

    window.addEventListener('message', onMessage);
    container.appendChild(iframe);
  }
</script>

Both examples above are for web applications — either creating the iframe yourself or letting the SDK do it. For native apps using a WebView, see Native apps with the SDK for the SDK’s native-bundling pattern, or Setup with JavaScript for the no-SDK approach that loads the session url directly as the WebView’s top-level page.

Handle the complete event

Once the user finishes the form, the widget automatically resolves the RFI by calling Update request for information internally with the collected proof.

Calling Update request for information yourself is only needed if you’re not using the widget and are resolving the Travel Rule requirement directly — not part of this widget-based flow.

When complete fires, unmount the widget and confirm the RFI is resolved before proceeding — whether it is immediately ok or still pending depends on the proof type used:

Synchronous proofs (self-declaration, message signing) — the RFI is fully resolved as soon as complete fires. Proceed directly to Monitoring for settlement to listen for transaction status changes.
Asynchronous proofs (Satoshi test, a small on-chain test transaction) — complete firing does not mean the RFI is resolved yet; resolution depends on the microtransfer settling on-chain and confirmed by Uphold. Wait for it to settle, then proceed to Monitoring for settlement to listen for transaction status changes.

widget.on('complete', () => {
  widget.unmount();
  // Monitor the RFI status via webhook or polling, then monitor the transaction status to confirm the transaction is no longer on-hold
});

// Inside the onMessage switch from Set up the widget
case 'complete':
  teardown();
  // Monitor the RFI status via webhook or polling, then monitor the transaction status to confirm the transaction is no longer on-hold
  break;

Use Get request for information to check which proof type was used and confirm the RFI’s status.

Handle cancellations

The cancel event fires when the user closes the widget without completing the form. The transaction remains on-hold until the RFI is resolved — create a new widget session for the same transaction to let the user retry. See cancel event for the event reference.

widget.on('cancel', () => {
  widget.unmount();
  // Redirect back or show a cancellation message
});

// Inside the onMessage switch from Set up the widget
case 'cancel':
  teardown();
  // Redirect back or show a cancellation message
  break;

Handle errors

The error event fires when an unrecoverable error occurs. See error event for the full error shape and available properties.

widget.on('error', (event) => {
  console.error('Widget error:', event.detail.error);
  widget.unmount();
  // Show a user-friendly error message
});

// Inside the onMessage switch from Set up the widget
case 'error':
  console.error('Widget error:', event.data.error);
  teardown();
  // Show a user-friendly error message
  break;

Monitoring for settlement

After the RFI is resolved, the transaction will move from on-hold to processing and then to either completed or failed. Monitor the transaction status using webhooks (recommended) or polling (fallback):

Webhook events (recommended):
- core.transaction.status-changed
  - status: processing → transaction is being processed
  - status: completed → necessary confirmations reached
  - status: failed → transaction failed
Polling (fallback): Get transaction

When the transaction reaches completed or failed, notify the user of the outcome.

Testing

To trigger a Travel Rule RFI on a deposit, use a GB user account and send 30 XRP from an unhosted (self-custodial) wallet to the user’s Uphold deposit address. Verify the following:

A core.transaction.status-changed webhook is received with status: on-hold and statusDetails.reason: pending-requests-for-information.
Creating a widget session with flow: deposit-form and the transaction id as referenceId succeeds.
After completing the widget flow, the RFI status changes to ok and the transaction moves back to processing.
The transaction status updates from processing to completed within a few minutes, assuming no other blockers.

For the equivalent withdrawal guide, see Travel Rule withdrawal via the Travel Rule Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Travel Rule deposit via the Travel Rule Widget

Prerequisites

Walkthrough

Detect the on-hold transaction

Notify the user

Resolve the Travel Rule RFI

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitoring for settlement

Testing

​Prerequisites

​Walkthrough

​Detect the on-hold transaction

​Notify the user

​Resolve the Travel Rule RFI

​Create a widget session

​Set up the widget

​Handle the complete event

​Handle cancellations

​Handle errors

​Monitoring for settlement

​Testing

Prerequisites

Walkthrough

Detect the on-hold transaction

Notify the user

Resolve the Travel Rule RFI

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitoring for settlement

Testing