> ## 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.

# Card withdrawal (Transaction - Select Withdrawal Destination)

> Send card withdrawals with the Uphold Payment Widget for card selection, then create the quote and transaction directly via the REST API to complete payout.

The Payment Widget handles card selection for withdrawals via the `transaction:select-withdrawal-destination` flow. Your backend then creates the quote and the transaction directly via the REST API.

> [!NOTE]
>
> This guide uses the select flows, where your app builds the amount entry and review screens and handles errors. For a single-session experience where the widget handles the amount, quote and errors, see [End-to-end](https://developer.uphold.com/developer-guides/card-transfers/withdrawal/via-payment-widget/end-to-end.md). To compare all flows, see [Flows](https://developer.uphold.com/widgets/payment/flows.md).

> [!NOTE]
>
> The transaction flows were renamed to the `<context>:<action>` format. The previous names still work, as aliases with the same behavior and `complete` payload, but they are **deprecated** and will be removed in a future release:
>
> | Deprecated name | New name |
> | - | - |
> | `select-for-deposit` | `transaction:select-deposit-origin` |
> | `select-for-withdrawal` | `transaction:select-withdrawal-destination` |
> | `authorize` | `transaction:authorize` |
>
> To migrate, change the `flow` of the Create session request and, with the Web SDK, the `PaymentWidget` generic type. See [Flows](https://developer.uphold.com/widgets/payment/flows.md#deprecated-flow-names).

## Prerequisites

* The user has [completed onboarding](https://developer.uphold.com/developer-guides/user-onboarding/introduction.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).

## 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

  Usr->>U: Start card 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 (transaction:select-withdrawal-destination)
  A-->>B: { session }
  B-->>U: { session }
  U->>P: Initialize widget
  Usr->>P: Select card account
  P-->>U: complete { via, selection }
  Usr->>U: Choose amount
  U->>B: Request quote
  B->>A: Create quote (account → card)
  A-->>B: { quote }
  B-->>U: { quote }
  Usr->>U: Confirm
  U->>B: Create transaction
  B->>A: Create transaction
  A-->>B: { transaction }
  A-->>B: webhook: transaction.created (processing)
  A-->>B: webhook: transaction.status-changed (completed/failed)
  B-->>Usr: Notify the user
```

***

## Select source account

Card withdrawals can be sourced from any account. If the selected account is not in the card's currency, 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](https://developer.uphold.com/rest-apis/core-api/assets/overview.md#features-and-deposits-/-withdrawals).

Call [List accounts](https://developer.uphold.com/rest-apis/core-api/accounts/list-accounts.md) to retrieve the user's accounts and let them pick the one to withdraw from.

```http theme={null}
GET /core/accounts
```

```json theme={null}
{
  "accounts": [
    {
      "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
      "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
      "label": "My GBP account",
      "asset": "GBP",
      "balance": {
        "total": "500.00",
        "available": "500.00"
      },
      "createdAt": "2026-06-01T12:00:00Z",
      "updatedAt": "2026-06-01T12:00:00Z"
    }
  ]
}
```

***

## Link or select a card account

The widget session lets the user link a new card or select an existing one.

### Create a widget session

Call [Create widget session](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) to start the `transaction:select-withdrawal-destination` flow. To customize the theme and layout, see [Create a session](https://developer.uphold.com/widgets/payment/installation-and-setup.md#1-create-a-session-on-your-backend).

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

The response contains a `session` object with a `url` field that loads the widget. Return `response.session` to your frontend as is.

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

### Set up the widget

```typescript 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<'transaction:select-withdrawal-destination'>(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 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':
          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.

### Handle the complete event

The `complete` event fires after the user selects a card. The event payload includes the selected card external account.

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

  if (via === 'external-account') {
    // selection is the selected card external account
    // use selection.id as the destination in the quote
    handleCardSelected(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 === 'external-account') {
    // selection is the selected card external account
    // use selection.id as the destination in the quote
    handleCardSelected(selection);
  }

  teardown();
  break;
}
```

Once you have the selected card, prompt the user to select a source account, then create a quote.

### Handle cancellations

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

```javascript Without SDK theme={null}
// Inside the onMessage switch from Set up the widget
case 'cancel':
  teardown();
  // Return the user to the previous screen
  break;
```

### Handle errors

The `error` event fires for critical unrecoverable errors. Card-specific errors (duplicate card, country mismatch, card limits) are handled by the widget internally.

```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;
```

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

***

## Create a quote

Call [Create quote](https://developer.uphold.com/rest-apis/core-api/transactions/create-quote.md) with the origin account and the selected card external account as destination.

```http theme={null}
POST /core/transactions/quote
{
  "origin": {
    "type": "account",
    "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8"
  },
  "destination": {
    "type": "external-account",
    "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7"
  },
  "denomination": {
    "asset": "GBP",
    "amount": "250.00",
    "target": "origin"
  }
}
```

A successful response includes the quote details. Present the quote to the user for confirmation before proceeding.

```json [expandable] theme={null}
{
  "quote": {
    "id": "a91f3c72-1e4b-4c8a-b3e9-9f2d8e4b7c1a",
    "origin": {
      "amount": "250.00",
      "asset": "GBP",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      },
      "rate": "1"
    },
    "destination": {
      "amount": "250.00",
      "asset": "GBP",
      "node": {
        "type": "external-account",
        "via": "card",
        "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
        "network": "visa"
      },
      "rate": "1"
    },
    "denomination": {
      "asset": "GBP",
      "amount": "250.00",
      "target": "origin",
      "rate": "1"
    },
    "fees": [],
    "requirements": [],
    "refreshAt": "2024-07-24T15:22:39Z",
    "expiresAt": "2024-07-24T15:22:39Z"
  }
}
```

> [!NOTE]
>
> Quotes are short-lived. Use `refreshAt` to drive re-quoting: if the user hasn't confirmed by then, create a new quote and show the updated amounts, since there's no refresh endpoint. The quote's `expiresAt` is equal to or later than `refreshAt`, to give the user time to complete an external action needed to proceed, such as authorizing an APM payment.

***

## Confirm and create transaction

Once the user confirms, call [Create transaction](https://developer.uphold.com/rest-apis/core-api/transactions/create-transaction.md) with the quote ID.

```http theme={null}
POST /core/transactions
{
  "quoteId": "a91f3c72-1e4b-4c8a-b3e9-9f2d8e4b7c1a"
}
```

In a successful card withdrawal, the origin is the user's `account` and the destination is the `external-account` representing the card. The transaction status is initially `processing` and updates to `completed` once the transfer settles.

```json [expandable] theme={null}
{
  "transaction": {
    "id": "a1b2c3d4-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    "origin": {
      "asset": "GBP",
      "amount": "250.00",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "destination": {
      "asset": "GBP",
      "amount": "250.00",
      "node": {
        "type": "external-account",
        "via": "card",
        "id": "7d5928c5-8ac4-4b0d-8b45-f332ba6a9de7",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a",
        "network": "visa"
      }
    },
    "status": "completed",
    "quotedAt": "2025-01-10T14:22:15Z",
    "createdAt": "2025-01-10T14:22:45Z",
    "updatedAt": "2025-01-10T14:22:45Z",
    "denomination": {
      "asset": "GBP",
      "amount": "250.00",
      "target": "origin"
    },
    "fees": []
  }
}
```

***

## Monitor for settlement

Card withdrawal transactions may remain in `processing` while the payment settles. Monitor until the transaction reaches a terminal state.

* **Webhook events** (recommended):
  * [core.transaction.created](https://developer.uphold.com/rest-apis/core-api/transactions/webhooks/transaction-created.md) — `status: processing` → transaction created, pending settlement
  * [core.transaction.status-changed](https://developer.uphold.com/rest-apis/core-api/transactions/webhooks/transaction-status-changed.md) — `status: completed` → funds settled; `status: failed` → irrecoverable error
* **Polling** (fallback): [Get transaction](https://developer.uphold.com/rest-apis/core-api/transactions/get-transaction.md)

## Notify the user

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

> [!TIP]
>
> You now support card withdrawals via the Payment Widget.
