Skip to main content
The Payment Widget’s withdrawal flow handles the entire crypto withdrawal in one session: the user picks the origin Uphold account, chooses the asset and network, enters the destination address, enters the amount, reviews a live quote, provides any Travel Rule information required, confirms the transaction and sees its status — all without your backend creating a quote, a Travel Rule session or the transaction.
If you need to build the amount entry and review screens yourself, see the Select for Withdrawal guide instead. To compare all flows, see Flows.

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.
  • @uphold/enterprise-payment-widget-web-sdk is on version 0.19.0 or later.

Walkthrough


Complete the withdrawal in the widget

The widget session takes the user from account and destination selection through the amount, quote, Travel Rule and confirmation.

Create a widget session

Call Create widget session to start the withdrawal flow. No data is required — the widget gathers everything from the user. Use options to customize the Widget’s theme and layout, as well as the flow itself. See the example here and the SDK reference for all available options. By default, the end-to-end flows offer bank, card and crypto. To offer crypto only, set paymentMethods to crypto:
Withdrawals can be sourced from any account. If the origin account is not in the asset being withdrawn, the balance is converted at the time of the transaction using Uphold’s prevailing rate.
In the end-to-end flows, use availableAssets to restrict the assets the user can pick. It replaces any assets filter set on the crypto payment method.
The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

Set up the widget

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.
The destination address field offers a Scan QR code action only when the device has a camera and the Widget is allowed to use it. The Web SDK’s mountIframe() grants camera from v0.19.0 onwards. Without the SDK, add camera 'src' to the iframe allow attribute, as in the example above. For the Permissions Policy, HTTPS and native WebView requirements, see Allow camera access for QR code scanning. When the camera is unavailable, the user types or pastes the address instead.

Handle the complete event

The complete event fires when the user closes the terminal status screen. Its value is the authorization result — the transaction plus what triggered the completion, the same as for card withdrawals.
complete is only emitted once the user closes the status screen. A user who abandons the widget there leaves a real transaction behind that your app never hears about. Treat webhooks as the source of truth and complete as a UX signal.

Handle cancellations

The cancel event fires when the user closes the widget before confirming, or after the Travel Rule verification failed. No transaction exists at that point.

Handle errors

The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.
The widget recovers from address validation, quote and transaction failures internally by returning the user to the relevant screen with an appropriate action — correct the address, change the amount, change the payment method, or try again. Insufficient balance is handled this way rather than as an error event. The Travel Rule step is the exception: when the quote requires the Travel Rule, the Widget collects the information itself, and if that step fails and the user closes the Widget instead of trying again, the Widget emits an error event.
To trigger a Travel Rule requirement in sandbox, use a GB user and withdraw 30 XRP to an external address.

Monitor for settlement

  • 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
Unlike a deposit hold, a withdrawal transaction is created right away, so failures surface after creation — either when the Travel Rule payload is rejected at creation time, or when the counterparty VASP later rejects the data. After the transaction is created, the counterparty VASP has a window to review the Travel Rule data. If the data is rejected, Uphold emits a core.transaction.status-changed webhook with status: failed and statusDetails.reason: travel-rule-verification-failed. Common causes are the transaction being created before the RFI was fully resolved, or the beneficiary VASP being unrecognized or invalid. Notify the user and ask them to retry with a different destination.

Sample transaction

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.

Execution modes

Crypto withdrawals are executed in one of the following modes, indicated by destination.node.execution.mode:
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.
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: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.
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.

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.
You now support end-to-end crypto withdrawals via the Payment Widget.