> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto deposit (End-to-end)

> Support crypto deposits in a single Payment Widget session that handles account selection, asset and network selection and the deposit address.

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`](https://developer.uphold.com/developer-guides/crypto-transfers/deposit/via-payment-widget/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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> If you need to build the deposit experience yourself, see the [Select for Deposit](https://developer.uphold.com/developer-guides/crypto-transfers/deposit/via-payment-widget/select-for-deposit.md) guide instead. To compare all flows, see [Flows](https://developer.uphold.com/widgets/payment/flows.md).

## Prerequisites

* The user has [completed onboarding](https://developer.uphold.com/developer-guides/user-onboarding/overview.md) and has the required capabilities enabled.
* The Payment Widget is set up in your frontend. See [Installation and setup](https://developer.uphold.com/widgets/payment/installation-and-setup.md).
* `@uphold/enterprise-payment-widget-web-sdk` is on version 0.19.0 or later.

## Walkthrough

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant Usr as User
  participant U as Your App
  participant B as Your Backend
  participant P as Payment Widget
  participant W as Travel Rule Widget
  participant A as Uphold
  participant C as Blockchain Network

  Usr->>U: Request deposit instructions
  U->>B: Create widget session
  B->>A: Create widget session (deposit)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  Usr->>P: Select destination account and deposit method
  P-->>Usr: Display crypto deposit instructions
  Usr->>C: Send crypto transfer
  C-->>A: Incoming transfer received
  A-->>B: webhook: transaction.created (processing)
  C-->>A: Confirmations reached
  alt on-hold (pending RFI)
    A-->>B: webhook: transaction.status-changed (on-hold)
    B->>A: GET /core/requests-for-information
    A-->>B: { requestsForInformation }
    B->>A: POST /widgets/travel-rule/sessions
    A-->>B: { session }
    B-->>U: { session }
    U->>W: Initialize widget
    Usr->>W: Submit Travel Rule information
    W->>A: PUT /core/requests-for-information/{rfiId}
    A-->>W: RFI resolved
    W-->>U: complete { requestForInformation, trigger }
  end
  A-->>B: webhook: transaction.status-changed (completed/failed)
  B-->>Usr: Notify the user
```

***

## 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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) 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](https://developer.uphold.com/widgets/payment/installation-and-setup.md#1-create-a-session-on-your-backend) and the [SDK reference](https://developer.uphold.com/widgets/payment/sdk-reference.md#options) for all available options.

By default, the end-to-end flows offer bank, card and crypto. To offer crypto only, set `paymentMethods` to `crypto`:

```http theme={null}
POST /widgets/payment/sessions
{
  "flow": "deposit",
  "options": {
    "paymentMethods": [{ "type": "crypto" }]
  }
}
```

> [!NOTE]
>
> 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.

> [!TIP]
>
> 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.

```json theme={null}
{
  "session": {
    "url": "https://payment-widget.enterprise.uphold.com/?sessionToken=..."
  }
}
```

### Set up the widget

```javascript Web SDK [expandable] theme={null}
import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

const initializeDepositWidget = async (session) => {
  const widget = new PaymentWidget<'deposit'>(session, { debug: true });

  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'));
};
```

```html Without SDK [expandable] theme={null}
<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'; payment 'src'; web-share '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':
          iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
          break;
        case '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>
```

> [!NOTE]
>
> 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](https://developer.uphold.com/widgets/payment/installation-and-setup.md#native-apps-with-the-web-sdk) for the SDK's native-bundling pattern, or [Setup without the SDK](https://developer.uphold.com/widgets/payment/installation-and-setup.md#setup-without-the-sdk) for the no-SDK approach that loads the session `url` directly as the WebView's top-level page.

> [!NOTE]
>
> 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.

```javascript Web SDK theme={null}
widget.on('complete', (event) => {
  const result = event.detail.value;

  if ('via' in result) {
    // Bank or crypto deposit: no transaction yet — it is created when the transfer arrives
    const { depositMethod, account } = result.selection;

    if (depositMethod.type === 'crypto') {
      handleCryptoDepositAddressShown(depositMethod, account);
    } else {
      handleBankDepositInstructionsShown(depositMethod, account);
    }
  } else {
    // Card deposit: see the card end-to-end guide
    handleCardDeposit(result.transaction, result.trigger);
  }

  widget.unmount();
});
```

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'complete': {
  const result = event.data.value;

  if ('via' in result) {
    // Bank or crypto deposit: no transaction yet — it is created when the transfer arrives
    const { depositMethod, account } = result.selection;

    if (depositMethod.type === 'crypto') {
      handleCryptoDepositAddressShown(depositMethod, account);
    } else {
      handleBankDepositInstructionsShown(depositMethod, account);
    }
  } else {
    // Card deposit: see the card end-to-end guide
    handleCardDeposit(result.transaction, result.trigger);
  }

  teardown();
  break;
}
```

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.

```json theme={null}
{
  "via": "deposit-method",
  "selection": {
    "account": {
      "id": "8b7c0a1e-2f4d-4c3b-9a6e-5d1f0e2c3b4a",
      "label": "My XRP account",
      "asset": "XRP"
    },
    "depositMethod": {
      "type": "crypto",
      "status": "ok",
      "details": {
        "network": "xrp-ledger",
        "asset": "XRP",
        "address": "rfBtmHiLwwWH5maH2PT78GxubrSydRF9aY",
        "reference": "3457810109"
      }
    }
  }
}
```

> [!WARNING]
>
> `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.

```javascript theme={null}
widget.on('cancel', () => {
  widget.unmount();
  // Return the user to the previous screen
});
```

### Handle errors

> [!WARNING]
>
> 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.

* Webhook events (recommended):
  * [core.transaction.created](https://developer.uphold.com/rest-apis/core-api/transactions/webhooks/transaction-created.md)
    * `status: processing` → detected on-chain but not yet confirmed
  * [core.transaction.status-changed](https://developer.uphold.com/rest-apis/core-api/transactions/webhooks/transaction-status-changed.md)
    * `status: completed` → necessary confirmations reached
    * `status: on-hold` → transaction checks paused (e.g., pending RFIs)
    * `status: failed` → irrecoverable error
* Polling (fallback): [Get transaction](https://developer.uphold.com/rest-apis/core-api/transactions/get-transaction.md)

In sandbox, use the [Simulate crypto deposit](https://developer.uphold.com/rest-apis/core-api/accounts/test-helpers/simulate-crypto-deposit.md) 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.

```json [expandable] theme={null} theme={null}
{
  "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`:

> [accordion] 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.

> [accordion] 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.

> [accordion] Simulated
>
> Used in development environments for testing, see [Simulate crypto deposit](https://developer.uphold.com/rest-apis/core-api/accounts/test-helpers/simulate-crypto-deposit.md). 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](https://developer.uphold.com/developer-guides/travel-rule/deposit/via-api.md) guide.

To let the user provide the Travel Rule information in a Widget, see the [Travel Rule deposit via Widget](https://developer.uphold.com/developer-guides/travel-rule/deposit/via-widget.md) 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.

> [!TIP]
>
> You now support end-to-end crypto deposits via the Payment Widget.
