Card deposit (End-to-end)

The Payment Widget’s deposit flow handles the entire card deposit in one session: the user picks the destination Uphold account, links or selects a card, enters the amount, reviews a live quote, completes any 3DS challenge and confirms the status of the transaction — 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 Deposit 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 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.

POST /widgets/payment/sessions
{
  "flow": "deposit",
  "options": {
    "layout": "fluid",
    "theme": { "appearance": "dark" },
    "initialSelection": { "destination": { "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 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'));
};

<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';");
    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') {
      // Funds have settled
      handleDepositCompleted(transaction);
    } else if (transaction.status === 'failed') {
      handleDepositFailed(transaction);
    }
  } else if (trigger.reason === 'max-retries-reached') {
    // Polling timed out — the transaction may still be processing
    handleDepositPending(transaction);
  }

  widget.unmount();
});

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

  if (trigger.reason === 'transaction-status-changed' && transaction.status === 'completed') {
    handleDepositCompleted(transaction);
  } else {
    handleDepositPending(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 deposit, the origin is the external-account representing the card and the destination is the user’s account.

{
  "transaction": {
    "id": "f5a6b7c8-3d4e-4f7a-b00c-9d8e7f6a5b4c",
    "origin": {
      "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"
      }
    },
    "destination": {
      "asset": "GBP",
      "amount": "250.00",
      "node": {
        "type": "account",
        "id": "a00507fe-628c-4f27-ae81-e1c40b2a8fb8",
        "ownerId": "e4ce04dc-67b7-4e9f-af91-482cb6f9fc4a"
      }
    },
    "status": "completed",
    "quotedAt": "2025-01-10T11:02:39Z",
    "createdAt": "2025-01-10T11:12:39Z",
    "updatedAt": "2025-01-10T11:13:08Z",
    "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. The error event is reserved for failures the widget cannot recover from. 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 deposit transactions may remain in processing while the payment 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 deposits via the Payment Widget.

User onboarding

Bank transfers

Card transfers

APM transfers

Buy and Sell

Crypto transfers

Travel Rule

Trade & Send

Statements

Resources

Card deposit (End-to-end)

Prerequisites

Walkthrough

Complete the deposit 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 deposit 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 deposit 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