Crypto deposit via the Payment Widget

The Payment Widget handles crypto network selection and displays the deposit address to the user. Your backend only needs to create the session and monitor for the incoming transfer.

The Payment Widget does not create any transaction. Monitoring and processing the incoming transfer must be handled by your backend via webhooks or polling.

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 deposit method

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

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

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-deposit 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 initializeDepositWidget = async (session) => {
  const widget = new PaymentWidget<'select-for-deposit'>(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 initializeDepositWidget(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 complete event fires when the user selects a deposit method and the widget displays the deposit address.

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

  if (via === 'deposit-method') {
    const { depositMethod, account } = selection;

    if (depositMethod.type === 'crypto') {
      handleCryptoDeposit(depositMethod, account);
    }
  }

  widget.unmount();
});

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

  if (via === 'deposit-method') {
    const { depositMethod, account } = selection;

    if (depositMethod.type === 'crypto') {
      handleCryptoDeposit(depositMethod, account);
    }
  }

  teardown();
  break;
}

The event payload:

via — set to deposit-method when the user completes the crypto network selection.
selection.account — the account that will receive the deposit.
selection.depositMethod — the deposit method with crypto transfer instructions.

The widget presents the deposit address and reference directly to the user. The depositMethod.details contains:

{
  "type": "crypto",
  "status": "ok",
  "details": {
    "network": "xrp-ledger",
    "asset": "XRP",
    "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
    "reference": "3457810109"
  }
}

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;

Monitor for the incoming transfer

The widget presents the deposit instructions to the user but does not monitor for the incoming transfer. Your application must do this via webhooks or polling. Prefer webhooks for real-time updates, or fall back to polling if webhooks are not feasible.

Webhook events (recommended):
- core.transaction.created
  - status: processing → detected on-chain but not yet confirmed
- core.transaction.status-changed
  - status: completed → necessary confirmations reached
  - status: on-hold → transaction checks paused (e.g., pending RFIs)
  - status: failed → irrecoverable error
Polling (fallback): Get transaction

Sample transaction

In a successful crypto deposit, the origin is represented as a crypto-address node reflecting the sender’s on-chain address. The destination is the account that was set up to receive the deposit.

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

Execution modes

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

On-chain

The transaction is received from the blockchain network. origin.node.execution.mode is onchain, and origin.node.execution.transactionHash holds the transaction hash, as in the example above.

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, see Simulate crypto deposit. The transaction appears processed without affecting blockchain state, although user balances are updated. origin.node.execution.mode is simulated.

Handle on-hold transactions

If the crypto deposit is placed on-hold with reason pending-requests-for-information, resolve the pending RFIs before the deposit can complete. For the full step-by-step implementation, see the Travel Rule deposit flow guide.

Notify the user

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

You now support crypto deposits via the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Crypto deposit via the Payment Widget

Prerequisites

Walkthrough

Select deposit method

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitor for the incoming transfer

Sample transaction

Execution modes

Handle on-hold transactions

Notify the user

​Prerequisites

​Walkthrough

​Select deposit method

​Create a widget session

​Set up the widget

​Handle the complete event

​Handle cancellations

​Handle errors

​Monitor for the incoming transfer

​Sample transaction

​Execution modes

​Handle on-hold transactions

​Notify the user

Prerequisites

Walkthrough

Select deposit method

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitor for the incoming transfer

Sample transaction

Execution modes

Handle on-hold transactions

Notify the user