Crypto withdrawal via the Payment Widget

The Payment Widget handles crypto asset, network and address collection for withdrawals. Your backend creates the session, then continues with the REST API to create a quote and transaction once the user has provided the destination details.

The Payment Widget does not create any transaction. Transaction creation must be handled by your backend via the REST API.

Prerequisites

The user has completed onboarding and has the required capabilities enabled.
The Payment Widget is set up in your frontend. See Installation and setup.

Walkthrough

Select source account

Crypto withdrawals can be sourced from any account. If the selected account is not in the withdrawal asset, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them choose one with sufficient balance for the withdrawal.

GET /core/accounts?currency=BTC

{
  "accounts": [
    {
      "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "label": "My BTC account",
      "asset": "BTC",
      "balance": {
        "total": "0.05",
        "available": "0.05"
      }
    }
  ]
}

Set a crypto destination

The widget lets the user select a crypto asset, choose a network and enter the destination address. Call Create widget session to start the select-for-withdrawal flow. To customize the theme and layout, see the example here.

POST /widgets/payment/sessions
{
  "flow": "select-for-withdrawal"
}

The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

{
  "session": {
    "url": "https://payment-widget.enterprise.uphold.com/?sessionToken=..."
  }
}

Initialize the widget for the select-for-withdrawal flow using the session data returned from the API.

import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

// session is `response.session` from your backend
const initializeWithdrawalWidget = async (session) => {
  const widget = new PaymentWidget<'select-for-withdrawal'>(session, { debug: true });

  widget.on('ready', () => {
    console.log('Ready');
  });

  widget.on('complete', (event) => {
    console.log('Complete', JSON.stringify(event.detail.value));
    widget.unmount();
  });

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

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

  widget.mountIframe(document.getElementById('payment-container'));
};

<div id="payment-container"></div>

<script>
  // session is `response.session` from your backend
  async function initializeWithdrawalWidget(session) {
    const container = document.getElementById('payment-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':
          // Optional: repeat theme or layout from Create session to avoid a brief flash of defaults
          iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
          break;
        case 'ready':
          console.log('Ready');
          break;
        case 'complete':
          console.log('Complete', JSON.stringify(event.data.value));
          teardown();
          break;
        case 'cancel':
          console.log('Cancelled');
          teardown();
          break;
        case 'error':
          console.error('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 Web SDK for the SDK’s native-bundling pattern, or Setup without the SDK for the no-SDK approach that loads the session url directly as the WebView’s top-level page.

Handle the complete event

The widget lets the user select a crypto asset, choose a network and enter a destination address. If the network requires a destination tag or memo, the widget prompts for it and warns the user if it’s missing. When the user completes the selection, the complete event fires with via: "crypto-network".

widget.on('complete', (event) => {
  const { via, selection } = event.detail.value;

  if (via === 'crypto-network') {
    handleCryptoWithdrawal(selection);
  }

  widget.unmount();
});

// Inside the onMessage switch from Set up the widget
case 'complete': {
  const { via, selection } = event.data.value;

  if (via === 'crypto-network') {
    handleCryptoWithdrawal(selection);
  }

  teardown();
  break;
}

The event payload:

via — set to crypto-network when the user provides a crypto withdrawal address.
selection.asset — the selected crypto asset code (e.g. BTC, XRP).
selection.network — the selected blockchain network (e.g. bitcoin, xrp-ledger).
selection.address — the destination wallet address.
selection.reference — the destination tag or memo, if required by the network.

{
  "via": "crypto-network",
  "selection": {
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh",
    "reference": "12345678"
  }
}

Handle cancellations

The cancel event fires when the user closes the widget without completing the selection.

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 error occurs during the flow.

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;

Create a quote

Use the selection data from the widget to create a quote via the Create quote endpoint.

POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8"
  },
  "destination": {
    "type": "crypto-address",
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh",
    "reference": "12345678"
  },
  "denomination": {
    "asset": "XRP",
    "amount": "10.00",
    "target": "origin"
  }
}

Quotes typically expire quickly. Prompt for user confirmation within the expiry window and requote if needed.

Handle quote requirements

When the quote is returned, check the requirements array. If non-empty, resolve each requirement before creating the transaction.

{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "requirements": [
      "travel-rule"
    ],
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}

Travel Rule

If the requirements array contains travel-rule, you must collect the required originator and beneficiary information before creating the transaction. For the full step-by-step implementation, see the Travel Rule withdrawal guide.

Create a transaction

Once the user confirms the quote, create the transaction using the Create transaction endpoint. If the original quote expired during the RFI process, create a new quote and proceed with the transaction using the new quote ID.

POST /core/transactions
{
  "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0"
}

In a successful crypto withdrawal, the origin is the source account and the destination is a crypto-address node reflecting the recipient’s on-chain address.

{
  "transaction": {
    "id": "223c24c5-76c6-4553-91bc-5af519441f03",
    "origin": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "0.00002629253259492961",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "1",
      "node": {
        "type": "crypto-address",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "network": "bitcoin",
        "execution": {
          "mode": "onchain"
        }
      }
    },
    "fees": [],
    "status": "processing",
    "quotedAt": "2024-07-24T15:02:39Z",
    "createdAt": "2024-07-24T15:22:39Z",
    "updatedAt": "2024-07-24T15:22:39Z",
    "denomination": {
      "amount": "100.00",
      "asset": "GBP",
      "target": "origin",
      "rate": "0.00001210225938333485"
    }
  }
}

Execution modes

Crypto withdrawals are executed in one of the following modes, indicated by destination.node.execution.mode:

On-chain

The transaction is broadcast to the blockchain network. destination.node.execution.mode is onchain, and destination.node.execution.transactionHash is set once the transaction is completed.

Off-chain

When both the sender and recipient are Uphold users, the transfer is processed within Uphold’s infrastructure instead of the blockchain. This avoids network fees and is faster than on-chain processing.Each side sees the transfer from its own perspective:

	Sender	Recipient
Seen as	Withdrawal	Deposit
`origin.node.type`	`account`	`crypto-address`
`destination.node.type`	`crypto-address`	`account`

When both users belong to the same organization, the execution also identifies the counterpart account: destination.node.execution.accountOwnerId and destination.node.execution.accountId for the sender, and origin.node.execution.accountOwnerId and origin.node.execution.accountId for the recipient.Because funds move between Uphold accounts, the assets may differ from an on-chain transfer:

Sender: destination.asset is the asset of the recipient account associated with the address, which may differ from the one in the quote.
Recipient: origin.asset is the asset of the sender’s account, which may differ from the network’s asset or even be one the network doesn’t support, such as a fiat asset.

Simulated

Used in development environments for testing. The transaction appears processed without affecting blockchain state, although user balances are updated. destination.node.execution.mode is simulated.

Monitor for settlement

Prefer webhooks for real-time updates, or fall back to polling if webhooks are not feasible.

Webhook events (recommended):
- core.transaction.created
  - status: processing → initiated but not yet broadcast
- core.transaction.status-changed
  - status: completed → broadcast and confirmed
  - status: on-hold → transaction checks paused (e.g., pending RFIs)
  - status: failed → transaction failed, check statusDetails for more info
Polling (fallback): Get transaction

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.

You now support crypto withdrawals via the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Crypto withdrawal via the Payment Widget

Prerequisites

Walkthrough

Select source account

Set a crypto destination

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Create a quote

Handle quote requirements

Travel Rule

Create a transaction

Execution modes

Monitor for settlement

Notify the user

​Prerequisites

​Walkthrough

​Select source account

​Set a crypto destination

​Create a widget session

​Set up the widget

​Handle the complete event

​Handle cancellations

​Handle errors

​Create a quote

​Handle quote requirements

​Travel Rule

​Create a transaction

​Execution modes

​Monitor for settlement

​Notify the user

Prerequisites

Walkthrough

Select source account

Set a crypto destination

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Create a quote

Handle quote requirements

Travel Rule

Create a transaction

Execution modes

Monitor for settlement

Notify the user