Card withdrawal (End-to-end)

The Payment Widget’s withdrawal flow handles the entire card withdrawal in one session: the user picks the origin Uphold account, links or selects a card, enters the amount, reviews a live quote, confirms the transaction and sees its status — all without your backend creating a quote or a second session.

If you need to build the amount entry and review screens yourself, see Select for Withdrawal 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 a version that supports the end-to-end flows.

Walkthrough

The widget session takes the user from account and card selection through the amount, quote and authorization. Call Create widget session to start the withdrawal 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.

POST /widgets/payment/sessions
{
  "flow": "withdrawal",
  "options": {
    "layout": "fluid",
    "theme": { "appearance": "dark" },
    "initialSelection": { "origin": { "asset": "BTC" } }
  }
}

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

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

import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';

const initializeWithdrawalWidget = async (session) => {
  const widget = new PaymentWidget<'withdrawal'>(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'));
};

<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'; payment '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>

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 SDK for the SDK’s native-bundling pattern, or Setup with JavaScript 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 when the user closes the terminal status screen. Its value is the authorization result — the transaction plus what triggered the completion.

widget.on('complete', (event) => {
  const { transaction, trigger } = event.detail.value;

  if (trigger.reason === 'transaction-status-changed') {
    if (transaction.status === 'completed') {
      handleWithdrawalCompleted(transaction);
    } else if (transaction.status === 'failed') {
      handleWithdrawalFailed(transaction);
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Polling timed out — the transaction may still be processing
    handleWithdrawalPending(transaction);
  }

  widget.unmount();
});

case 'complete': {
  const { transaction, trigger } = event.data.value;

  if (trigger.reason === 'transaction-status-changed' && transaction.status === 'completed') {
    handleWithdrawalCompleted(transaction);
  } else {
    handleWithdrawalPending(transaction);
  }

  teardown();
  break;
}

complete is only emitted once the user closes the status screen. A user who abandons the widget there leaves a real transaction behind that your app never hears about. Treat webhooks as the source of truth and complete as a UX signal.

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.

{
  "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"
    }
  }
}

Handle cancellations

The cancel event fires when the user closes the widget before authorizing. No transaction exists at that point.

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

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 recovers from quote and authorization failures internally by returning the user to the review screen with an appropriate action — change the amount, change the payment method, or try again. Insufficient balance is handled this way rather than as an error event. These are the known errors:

Error	When it happens	What to do
Session could not be loaded	The `sessionToken` in `session.url` is expired, invalid or already used	Create a new session and initialize the Widget again

Monitor for settlement

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

Webhook events (recommended):
- core.transaction.created — status: processing → transaction created, pending settlement
- core.transaction.status-changed — status: completed → funds settled; status: failed → irrecoverable error
Polling (fallback): Get transaction

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 card withdrawals via the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Card withdrawal (End-to-end)

Prerequisites

Walkthrough

Complete the withdrawal in the widget

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitor for settlement

Notify the user

​Prerequisites

​Walkthrough

​Complete the withdrawal in the widget

​Create a widget session

​Set up the widget

​Handle the complete event

​Handle cancellations

​Handle errors

​Monitor for settlement

​Notify the user

Prerequisites

Walkthrough

Complete the withdrawal in the widget

Create a widget session

Set up the widget

Handle the complete event

Handle cancellations

Handle errors

Monitor for settlement

Notify the user