Skip to main content
The Payment Widget’s 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.
Crypto deposits are push transfers: the user sends the funds from their own wallet, so the Widget does not create any transaction. Uphold creates the transaction when the transfer is detected on-chain. Monitoring and processing it must be handled by your backend via webhooks or polling.
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-sdk is 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 the deposit 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.
The Widget starts by asking the user which Uphold account receives the deposit. To skip this screen, set initialSelection to { "destination": { "asset": "BTC" } } (or any other asset), which resolves to the user’s default account for that asset, creating it if needed, or pass that account’s ID as { "destination": { "accountId": "..." } }.
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 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, the complete 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.
For crypto deposits, the event payload contains:
  • via — set to deposit-method.
  • selection — contains the account that will receive the funds and the depositMethod with the deposit address. The user can still change the receiving account from the deposit address screen, so account may differ from the one picked at the start.
The widget presents these details directly to the user, so you don’t need to display them separately. 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.
complete only means the user saw the deposit address, not that they sent the funds. A user can also close the Widget and send the funds later to the same address. 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 reaching the deposit address.

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 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. The error 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. In sandbox, use the Simulate crypto deposit test helper with the depositMethod details from the complete event to simulate the incoming transfer.

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.

Execution modes

Crypto deposits are executed in one of the following modes, indicated by origin.node.execution.mode:
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.
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, 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. 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 is completed, and send an email if applicable.
You now support end-to-end crypto deposits via the Payment Widget.