deposit flow offers every deposit method (crypto, card and bank) in a single session. When the user picks crypto, the Widget first asks which Uphold account should receive the funds. You can skip this step by presetting the account with initialSelection. It then shows the same asset, network and deposit address screens as the select-for-deposit flow.
Use this flow when you want one deposit integration for every payment method. If you only offer crypto deposits, the select-for-deposit flow gives the same result.
If you need to build the deposit experience yourself, see the Select for Deposit 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 deposit in the widget
The widget session takes the user from account selection through asset and network selection to the deposit address.Create a widget session
Call Create widget session to start thedeposit 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, both as the receiving account and as the crypto asset to deposit. 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 deposit address screen offers a Share action that opens the device’s share sheet, only when the browser supports the Web Share API and the iframe allows
web-share. The Web SDK’s mountIframe() grants web-share. Without the SDK, add web-share 'src' to the iframe allow attribute, as in the example above. When sharing isn’t available, the action is hidden and the user can still copy the address and the destination tag or memo.Handle the complete event
Like bank deposits, thecomplete event of a crypto deposit carries a selection rather than a transaction: it fires when the user closes the deposit address screen, with via: "deposit-method" and the deposit method that was shown.
The deposit flow can complete with a card transaction or a deposit-method selection for bank or crypto. Check via first, then depositMethod.type ('bank' or 'crypto') to tell bank and crypto apart. If your session only offers crypto, you can skip the second check.
via— set todeposit-method.selection— contains theaccountthat will receive the funds and thedepositMethodwith the deposit address. The user can still change the receiving account from the deposit address screen, soaccountmay differ from the one picked at the start.
depositMethod.details contains the network, the asset, the address and, for networks that use one, the destination tag or memo in reference. For assets with several address formats, addressFormats lists them all and address is the default one, even if the user chose to display another format.
Handle cancellations
Thecancel event fires when the user closes the widget before reaching the deposit address.
Handle errors
The widget handles deposit method issues in-flow — for example, assets without a deposit rail are shown as unavailable, and the receiving account and its deposit address are created when the user doesn’t have them yet. Theerror event is reserved for failures the widget cannot recover from.
Monitor for the incoming transfer
The widget presents the deposit address to the user but does not monitor for the incoming transfer. Your application must do this via webhooks or polling.- Webhook events (recommended):
- core.transaction.created
status: processing→ detected on-chain but not yet confirmed
- core.transaction.status-changed
status: completed→ necessary confirmations reachedstatus: on-hold→ transaction checks paused (e.g., pending RFIs)status: failed→ irrecoverable error
- core.transaction.created
- Polling (fallback): Get transaction
depositMethod details from the complete event to simulate the incoming transfer.
Sample transaction
In a successful crypto deposit, the origin is represented as acrypto-address node reflecting the sender’s on-chain address. The destination is the account that was set up to receive the deposit.
Execution modes
Crypto deposits are executed in one of the following modes, indicated byorigin.node.execution.mode:
On-chain
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
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, 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 placedon-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.
To let the user provide the Travel Rule information in a Widget, see the Travel Rule deposit via Widget guide. Unlike withdrawals, the Payment Widget does not handle the Travel Rule for deposits, because the transaction only exists after the Widget closes.
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 deposits via the Payment Widget.