Use this file to discover all available pages before exploring further.
The Payment Widget handles card linking and selection for deposits. Users can add a new card or pick an existing one directly in the widget. If the resulting quote requires card authorization, a second widget session handles it and creates the transaction. If authorization is not required, your backend creates the transaction directly.
The Payment Widget handles card linking, selection, and authorization. When authorization is not required, your backend must create the transaction via the REST API.
The complete event fires after the user selects a card. The event payload includes the selected card external account.
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 origin in the quote handleCardSelected(selection); } widget.unmount();});
Once you have the selected card, prompt the user to select a destination account, then create a quote.
The error event fires for critical unrecoverable errors. Card-specific errors (duplicate card, country mismatch, card limits) are handled by the widget internally.
widget.on('error', (event) => { console.error('Widget error:', event.detail.error); widget.unmount(); // Show a user-friendly error message});
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.
Card deposits can target any account. If the selected account is not in the card’s currency, the amount will be converted at settlement using Uphold’s prevailing rate. Make sure the destination asset has the necessary features enabled.
If confirmationUrl is present on the origin node, card authorization is required. Use the Authorize widget flow — the widget creates the transaction, handles the authentication challenge, and polls until a terminal status is reached.
The error event fires for critical unrecoverable errors. Card-specific errors (duplicate card, country mismatch, card limits) are handled by the widget internally.
The operation is not permitted (e.g. duplicate withdrawal, card unauthorized)
user_capability_failure
The user lacks the required capability for this operation
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.
import { PaymentWidget } from '@uphold/enterprise-payment-widget-web-sdk';const initializeAuthorizeWidget = async (session) => { const widget = new PaymentWidget<'authorize'>(session, { debug: true }); widget.on('complete', (event) => { const { transaction, trigger } = event.detail.value; handleAuthorizeComplete(transaction, trigger); widget.unmount(); }); widget.on('cancel', () => { widget.unmount(); // Return the user to the previous screen }); widget.on('error', (event) => { const { code, details } = event.detail.error; handleAuthorizeError(code, details); widget.unmount(); }); widget.mountIframe(document.getElementById('payment-container'));};const handleAuthorizeComplete = (transaction, trigger) => { if (trigger.reason === 'transaction-status-changed') { if (transaction.status === 'completed') { // Show success — transaction is settled } else if (transaction.status === 'failed') { handleTransactionFailure(transaction.statusDetails.reason); } } else if (trigger.reason === 'max-retries-reached') { // Widget stopped polling — continue monitoring via webhooks or polling }};const handleTransactionFailure = (reason) => { switch (reason) { case 'card-declined-by-bank': case 'card-permanently-declined-by-bank': // Prompt the user to try a different card break; case 'card-expired': // Prompt the user to update their card break; case 'card-unauthorized': // 3DS authentication was not completed break; case 'card-unsupported': // Card type is not supported for this operation break; case 'insufficient-funds': // User does not have enough funds break; case 'provider-maximum-limit-exceeded': case 'velocity': // Transaction blocked by limits — inform the user break; default: // Unhandled reason — show a generic error message break; }};const handleAuthorizeError = (code, details) => { switch (code) { case 'entity_not_found': // Quote expired — prompt user to start over break; case 'insufficient_balance': // Origin account has insufficient balance break; case 'operation_not_allowed': // Operation not permitted (e.g. duplicate withdrawal, card unauthorized) break; case 'user_capability_failure': // User lacks the required capability break; default: // Unexpected error — show a generic error message break; }};
