Travel Rule — deposit flow

Step-by-step guide to resolving a Travel Rule request for information on an on-hold crypto deposit.

This guide walks you through resolving a Travel Rule request for information on an on-hold crypto deposit — from detecting the on-hold status to resolving the RFI and allowing the transaction to proceed.

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.

List transaction RFIs

Call List request for information endpoint to retrieve all RFIs by referenceId (transaction or quote ID), then filter the results to keep only entries where type is “travel-rule”. From that filtered set, check whether any RFI has a status of “pending” — if so, the transaction is still awaiting resolution. The deprecated transaction-nested endpoint still works but should not be used for new integrations.

GET /core/requests-for-information?referenceId={transactionId}

{
  "requestsForInformation": [
    {
      "id": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8",
      "type": "travel-rule",
      "status": "pending",
      "data": {},
      "createdAt": "2024-07-24T15:22:39Z",
      "updatedAt": "2024-07-24T15:22:39Z"
    }
  ]
}

If all travel-rule RFIs have a status of “ok”, the transaction may have already been moved out of on-hold status automatically. Make sure to re-fetch the transaction and check its current status before taking further action.

Resolve the RFI

The Travel Rule Widget allows the user to resolve a travel rule RFI for a specific transaction.

Create a widget session

Create a session tied to the RFI by calling Create session with flow: deposit-form and the data property containing the requestForInformationId. Each session is single-use and bound to a specific RFI.

POST /widgets/travel-rule/sessions
{
  "flow": "deposit-form",
  "data": {
    "requestForInformationId": "3f6d0c1e-a1bf-4b25-9802-2a3ee492d3c8"
  }
}

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.

Set up the widget

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.

Web SDK

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'));

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 data.

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, cryptographic signature) — the RFI is fully resolved as soon as complete fires. Proceed directly to Monitoring for settlement to listen for transaction status changes.
• Asynchronous proofs (micro-transfer, e.g. a small on-chain test transaction) — complete firing does not mean the RFI is resolved yet; resolution depends on the micro-transfer settling on-chain and confirmed by Uphold. Wait for it to settle, then proceed to Monitoring for settlement to listen for transaction status changes.

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

Web SDK

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
});

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 RFI to let the user retry. See cancel event for the event reference.

Web SDK

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

Handle errors

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

Web SDK

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

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:

1. A core.transaction.status-changed webhook is received with status: on-hold and statusDetails.reason: pending-requests-for-information.
2. List requests for information returns an RFI with type: travel-rule and status: pending.
3. After completing the widget flow, the RFI status changes to ok and the transaction moves back to processing.
4. 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 flow.