Skip to main content
Complete reference documentation for the @uphold/enterprise-payment-widget-web-sdk package.

​
PaymentWidget Class

The main class for creating and managing Payment Widget instances. It requires a PaymentWidgetSession object that must be created through the API before instantiating the Widget.

​
Constructor

new PaymentWidget<T extends PaymentWidgetFlow = PaymentWidgetFlow>(
  session: PaymentWidgetSession,
  options?: PaymentWidgetOptions
)

​
Parameters

ParameterTypeRequiredDescription
sessionPaymentWidgetSessionYesPayment session object obtained from the Create Session API endpoint
optionsPaymentWidgetOptionsNoConfiguration options for the Widget

​
Generic Type Parameter

The constructor accepts an optional generic type parameter that specifies the flow type. When provided, it enables better type inference for event handlers, particularly the complete event. Examples: 
// Generic flow type (default)
const widget = new PaymentWidget(session);

// Specific flow type for better type inference
const depositWidget = new PaymentWidget<'select-for-deposit'>(session);
const withdrawWidget = new PaymentWidget<'select-for-withdrawal'>(session);
const authorizeWidget = new PaymentWidget<'authorize'>(session);

​
PaymentWidgetOptions

type PaymentWidgetOptions = {
  debug?: boolean;
};
PropertyTypeDefaultDescription
debugbooleanfalseEnable debug mode for additional logging

​
Methods

​
mountIframe()

Mounts the Payment Widget iframe to the specified DOM element. Parameters:
  • element: The HTML element where the Widget should be mounted
Example: 
// Ensure the container has appropriate sizing
const container = document.getElementById('payment-container');
widget.mountIframe(container);
The container element should have explicit dimensions set via CSS. The Widget will fill the entire container. Minimum recommended size is 400px width × 600px height for optimal user experience.

​
unmount()

Unmounts and cleans up the Payment Widget iframe. Example: 
widget.unmount();
The Widget will not unmount itself when a flow is finished, either by successful completion, user cancellation, or unrecoverable error, so it must always be called manually.

​
on()

Registers an event listener for Widget events. Parameters:
  • event: The event name to listen for
  • callback: Function to execute when the event is triggered
Example: 
widget.on('complete', (event) => {
  console.log('Payment completed:', event.detail.value);
});

​
off()

Removes an event listener for Widget events. Parameters:
  • event: The event name to stop listening for
  • callback: The specific function to remove (must be the same reference as used in on())
Example: 
const handleComplete = (event) => {
  console.log('Payment completed:', event.detail.value);
};

// Register the listener
widget.on('complete', handleComplete);

// Remove the listener
widget.off('complete', handleComplete);

​
Events

The Payment Widget emits several events during its lifecycle that you can listen to using the on() method.

​
complete

Fired when the flow is completed. 
type PaymentWidgetCompleteEvent<T = PaymentWidgetFlow> = {
  detail: {
    value: T;
  };
};

​
Complete Event Value by Flow

The structure of event.detail.value depends on the flow type:
  • select-for-deposit flow For deposit selection flows, the value contains the user’s deposit method selection: Example: 
    const depositWidget = new PaymentWidget<'select-for-deposit'>(session);
depositWidget.on('complete', (event) => {
  const result: DepositSelection = event.detail.value;

  if (result.via === 'external-account') {
    // User selected a saved payment method
    console.log('Selected external account:', result.selection);
  } else if (result.via === 'deposit-method') {
    // User selected a bank transfer method
    console.log('Selected deposit method:', result.selection.depositMethod);
    console.log('Target account:', result.selection.account);
  }
});
  • select-for-withdrawal flow For withdrawal selection flows, the value contains the user’s withdrawal method selection: Example: 
    const withdrawWidget = new PaymentWidget<'select-for-withdrawal'>(session);
withdrawWidget.on('complete', (event) => {
  const result: WithdrawalSelection = event.detail.value;

  // result.via is always 'external-account' for withdrawals
  console.log('Selected external account for withdrawal:', result.selection);
});
  • authorize flow For authorization flows, the value contains transaction details and trigger information: Example: 
    const authorizeWidget = new PaymentWidget<'authorize'>(session);
authorizeWidget.on('complete', (event) => {
  const result = event.detail.value;

  if (result.trigger.reason === 'transaction-status-changed') {
    // Check transaction status - it may have succeeded or failed
    if (result.transaction.status === 'completed') {
      console.log('Transaction successful:', result.transaction);
    } else if (result.transaction.status === 'failed') {
      console.error('Transaction failed:', result.transaction);
      // Handle failure case
    }
  } else if (result.trigger.reason === 'max-retries-reached') {
    console.log('Polling timeout reached, transaction may still be processing: ', result.transaction);
    // Implement additional polling or show a message indicating that the transaction is still processing and to try again later
  }
});

​
cancel

Fired when the user cancels the payment flow. 
type PaymentWidgetCancelEvent = {
  detail: {};
}
Example: 
widget.on('cancel', (event: PaymentWidgetCancelEvent) => {
  console.log('Payment cancelled by user');
  widget.unmount();
});

​
error

Fired when an unrecoverable error occurs during the payment flow. 
type PaymentWidgetError = {
  name: string;
  code: string;
  message: string;
  details?: Record<string, unknown>;
  stack?: string;
  cause?: PaymentWidgetError;
  httpStatusCode?: number;
}

type PaymentWidgetErrorEvent = {
  detail: {
    error: PaymentWidgetError;
  };
};
Example: 
widget.on('error', (event: PaymentWidgetErrorEvent) => {
  const { error } = event.detail;
  console.error('Payment error:', error);

  // Handle specific error types
  if (error.code === 'entity_not_found') {
    // Quote expired - redirect to create new quote
    handleExpiredQuote();
  } else if (error.code === 'insufficient_balance') {
    // Not enough funds - show funding options
    handleInsufficientFunds();
  } else {
    // Generic error handling
    showGenericError(error.message);
  }

  widget.unmount();
});

​
ready

Fired when the Payment Widget has finished loading. 
type PaymentWidgetReadyEvent = {
  detail: {};
}
Example: 
widget.on('ready', (event: PaymentWidgetReadyEvent) => {
  console.log('Payment Widget is ready');
});

​
Types

​
PaymentWidgetSession

The session object returned by the Create Session API endpoint. 
type PaymentWidgetSession = {
  url: string;
  token: string;
  flow: PaymentWidgetFlow;
}

​
PaymentWidgetFlow

Represents the different flows supported by the Payment Widget. 
type PaymentWidgetFlow = 'select-for-deposit' | 'select-for-withdrawal' | 'authorize';

​
Complete Event Result Types

​
DepositSelection

Result structure for select-for-deposit flow: 
type ExternalAccountSelection = {
  via: 'external-account';
  selection: ExternalAccount; // See External Accounts API documentation
};

type AccountDepositMethodSelection = {
  via: 'deposit-method';
  selection: {
    depositMethod: AccountDepositMethod; // See Account Deposit Methods API documentation
    account: Account; // See Accounts API documentation
  };
};

type DepositSelection = ExternalAccountSelection | AccountDepositMethodSelection;
For complete type definitions, see the API documentation:

​
WithdrawalSelection

Result structure for select-for-withdrawal flow: 
type ExternalAccountSelection = {
  via: 'external-account';
  selection: ExternalAccount; // See External Accounts API documentation
};

type WithdrawalSelection = ExternalAccountSelection;
For complete ExternalAccount type definition, see the External Accounts API documentation.

​
AuthorizeResult

Result structure for authorize flow: 
type AuthorizeResult = {
  transaction: Transaction; // See Transactions API documentation
  trigger: {
    reason: 'transaction-status-changed' | 'max-retries-reached';
  };
}
For complete Transaction type definition, see the Transactions API documentation.
⌘I