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-sdkis 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 thewithdrawal 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:
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.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
Thecomplete 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.
Handle cancellations
Thecancel 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 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 anerror 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.
Monitor for settlement
- Webhook events (recommended):
- core.transaction.created
status: processing→ initiated but not yet broadcast
- core.transaction.status-changed
status: completed→ broadcast and confirmedstatus: on-hold→ transaction checks paused (e.g., pending RFIs)status: failed→ transaction failed, checkstatusDetailsfor more info
- core.transaction.created
- Polling (fallback): Get transaction
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 acrypto-address node reflecting the recipient’s on-chain address.
Execution modes
Crypto withdrawals are executed in one of the following modes, indicated bydestination.node.execution.mode:
On-chain
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
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:
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.assetis the asset of the recipient account associated with the address, which may differ from the one in the quote. - Recipient:
origin.assetis 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
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.Notify the user
Display an in-app confirmation when the transaction iscompleted, and send an email if applicable.
You now support end-to-end crypto withdrawals via the Payment Widget.