> ## 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 withdrawal via the Payment Widget

> Send crypto withdrawals with the Uphold Payment Widget for asset, network and address collection, then create the quote and transaction via the REST API.

The Payment Widget handles crypto asset, network and address collection for withdrawals. Your backend creates the session, then continues with the REST API to create a quote and transaction once the user has provided the destination details.

<Warning>
  The Payment Widget does not create any transaction. Transaction creation must be handled by your backend via the REST API.
</Warning>

## Prerequisites

* The user has [completed onboarding](/developer-guides/user-onboarding/overview) and has the required capabilities enabled.
* The Payment Widget is set up in your frontend. See [Installation and setup](/widgets/payment/installation-and-setup).

## 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 A as Uphold
  participant N as Blockchain Network

  Usr->>U: Start crypto withdrawal
  U->>B: List accounts
  B->>A: GET /core/accounts
  A-->>B: { accounts }
  B-->>U: { accounts }
  Usr->>U: Choose source account
  U->>B: Create widget session
  B->>A: Create widget session (select-for-withdrawal)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  Usr->>P: Select asset, network and enter address
  P-->>U: complete { via: "crypto-network", selection }
  U->>B: Request quote
  B->>A: Create quote
  A-->>B: { quote }
  B-->>U: { quote }
  Usr->>U: Confirm quote
  U->>B: Create transaction
  B->>A: Create transaction
  A-->>B: { transaction }
  A-->>B: webhook: transaction.created (processing)
  A->>N: Broadcast withdrawal
  N-->>A: Confirmations reached
  A-->>B: webhook: transaction.status-changed (completed/failed)
  B-->>Usr: Notify the user
```

***

## Select source account

Crypto withdrawals can be sourced from any account. If the selected account is not in the withdrawal asset, the balance will be converted at the time of the transaction using Uphold's prevailing rate. Make sure the origin asset has the necessary [features enabled](/rest-apis/core-api/assets/introduction#features-and-deposits-/-withdrawals).

Call [List accounts](/rest-apis/core-api/accounts/list-accounts) to retrieve the user's accounts and let them choose one with sufficient balance for the withdrawal.

```http theme={null}
GET /core/accounts?currency=BTC
```

```json theme={null}
{
  "accounts": [
    {
      "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "label": "My BTC account",
      "asset": "BTC",
      "balance": {
        "total": "0.05",
        "available": "0.05"
      }
    }
  ]
}
```

***

## Set a crypto destination

The widget lets the user select a crypto asset, choose a network and enter the destination address.

### Create a widget session

Call [Create widget session](/rest-apis/widgets-api/payment/create-session) to start the `select-for-withdrawal` flow. To customize the theme and layout, see the example [here](/widgets/payment/installation-and-setup#1-create-a-session-on-your-backend).

```http theme={null}
POST /widgets/payment/sessions
{
  "flow": "select-for-withdrawal"
}
```

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

Initialize the widget for the `select-for-withdrawal` flow using the session data returned from the API.

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

  // session is `response.session` from your backend
  const initializeWithdrawalWidget = async (session) => {
    const widget = new PaymentWidget<'select-for-withdrawal'>(session, { debug: true });

    widget.on('ready', () => {
      console.log('Ready');
    });

    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 initializeWithdrawalWidget(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';");
      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':
            // Optional: repeat theme or layout from Create session to avoid a brief flash of defaults
            iframe.contentWindow.postMessage({ options: {}, type: 'init' }, sessionOrigin);
            break;
          case 'ready':
            console.log('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>
  ```
</CodeGroup>

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

### Handle the complete event

The widget lets the user select a crypto asset, choose a network and enter a destination address. If the network requires a destination tag or memo, the widget prompts for it and warns the user if it's missing. When the user completes the selection, the `complete` event fires with `via: "crypto-network"`.

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

    if (via === 'crypto-network') {
      handleCryptoWithdrawal(selection);
    }

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

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

    if (via === 'crypto-network') {
      handleCryptoWithdrawal(selection);
    }

    teardown();
    break;
  }
  ```
</CodeGroup>

The event payload:

* `via` — set to `crypto-network` when the user provides a crypto withdrawal address.
* `selection.asset` — the selected crypto asset code (e.g. `BTC`, `XRP`).
* `selection.network` — the selected blockchain network (e.g. `bitcoin`, `xrp-ledger`).
* `selection.address` — the destination wallet address.
* `selection.reference` — the destination tag or memo, if required by the network.

```json theme={null}
{
  "via": "crypto-network",
  "selection": {
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh",
    "reference": "12345678"
  }
}
```

### Handle cancellations

The `cancel` event fires when the user closes the widget without completing the selection.

<CodeGroup>
  ```javascript Web SDK theme={null}
  widget.on('cancel', () => {
    widget.unmount();
    // Redirect back or show a cancellation message
  });
  ```

  ```javascript Without SDK theme={null}
  // Inside the onMessage switch from Set up the widget
  case 'cancel':
    teardown();
    // Redirect back or show a cancellation message
    break;
  ```
</CodeGroup>

### Handle errors

The `error` event fires when an error occurs during the flow.

<CodeGroup>
  ```javascript Web SDK theme={null}
  widget.on('error', (event) => {
    console.error('Widget error:', event.detail.error);
    widget.unmount();
    // Show a user-friendly error message
  });
  ```

  ```javascript Without SDK theme={null}
  // Inside the onMessage switch from Set up the widget
  case 'error':
    console.error('Widget error:', event.data.error);
    teardown();
    // Show a user-friendly error message
    break;
  ```
</CodeGroup>

## Create a quote

Use the `selection` data from the widget to create a quote via the [Create quote](/rest-apis/core-api/transactions/create-quote) endpoint.

```http theme={null}
POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8"
  },
  "destination": {
    "type": "crypto-address",
    "asset": "XRP",
    "network": "xrp-ledger",
    "address": "rPjTZfLP3Qxwwd2xvXSALJzEFmmf7bEYgh",
    "reference": "12345678"
  },
  "denomination": {
    "asset": "XRP",
    "amount": "10.00",
    "target": "origin"
  }
}
```

<Info>Quotes typically **expire** quickly. Prompt for user confirmation within the expiry window and requote if needed.</Info>

## Handle quote requirements

When the quote is returned, check the `requirements` array. If non-empty, resolve each requirement before creating the transaction.

```json theme={null}
{
  "quote": {
    "id": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0",
    "requirements": [
      "travel-rule"
    ],
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}
```

### Travel Rule

If the `requirements` array contains `travel-rule`, you must collect the required originator and beneficiary information before creating the transaction. For the full step-by-step implementation, see the [Travel Rule withdrawal](/developer-guides/travel-rule/withdrawal/via-api) guide.

## Create a transaction

Once the user confirms the quote, create the transaction using the [Create transaction](/rest-apis/core-api/transactions/create-transaction) endpoint. If the original quote expired during the RFI process, create a new quote and proceed with the transaction using the new quote ID.

```http theme={null}
POST /core/transactions
{
  "quoteId": "623000c8-9bdf-4a2b-aa3d-6a6b44a7f6a0"
}
```

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.

```json [expandable] theme={null}
{
  "transaction": {
    "id": "223c24c5-76c6-4553-91bc-5af519441f03",
    "origin": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "0.00002629253259492961",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "amount": "0.00121023",
      "asset": "BTC",
      "rate": "1",
      "node": {
        "type": "crypto-address",
        "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
        "network": "bitcoin",
        "execution": {
          "mode": "onchain"
        }
      }
    },
    "fees": [],
    "status": "processing",
    "quotedAt": "2024-07-24T15:02:39Z",
    "createdAt": "2024-07-24T15:22:39Z",
    "updatedAt": "2024-07-24T15:22:39Z",
    "denomination": {
      "amount": "100.00",
      "asset": "GBP",
      "target": "origin",
      "rate": "0.00001210225938333485"
    }
  }
}
```

### Execution modes

Crypto withdrawals are executed in one of the following modes, indicated by `destination.node.execution.mode`:

<AccordionGroup>
  <Accordion title="On-chain" icon="link">
    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.
  </Accordion>

  <Accordion title="Off-chain" icon="link-slash">
    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>

  <Accordion title="Simulated" icon="flask">
    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`.
  </Accordion>
</AccordionGroup>

## Monitor for settlement

Prefer **webhooks** for real-time updates, or fall back to **polling** if webhooks are not feasible.

* Webhook events (recommended):
  * [core.transaction.created](/rest-apis/core-api/transactions/webhooks/transaction-created)
    * `status: processing` → initiated but not yet broadcast
  * [core.transaction.status-changed](/rest-apis/core-api/transactions/webhooks/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](/rest-apis/core-api/transactions/get-transaction)

## Notify the user

Display an in-app confirmation when the transaction is `completed`, and send an email if applicable.

<Check>You now support crypto withdrawals via the Payment Widget.</Check>