Skip to main content
New FeatureBreaking ChangeDeprecatedPayment

On & Off Ramp orders in Payment Widget, and new flow names

SummaryThe Payment Widget now supports On & Off Ramp orders, with new flows that follow a <context>:<action> naming format:
  • on-ramp:select-deposit-origin and on-ramp:select-withdrawal-destination: the user selects the card or APM to pay with, such as Apple Pay or PayPal, and the crypto address that receives the crypto.
  • off-ramp:select-deposit-origin and off-ramp:select-withdrawal-destination: the user selects the crypto asset and network to sell, and the card that receives the payout.
  • order:authorize-deposit: the Widget creates an on-ramp order from a quote, authorizes its card or APM deposit, and completes with the order once the outcome of the deposit is known. Failures to create the order use the authorize_order_failed error code.
The select flows only offer the payment methods available for the order type, to users with the on-ramp or off-ramp capability.Deprecated: The transaction flows were renamed. The previous names still work, as aliases with the same behavior, but will be removed in a future release:
  • select-for-deposit → transaction:select-deposit-origin
  • select-for-withdrawal → transaction:select-withdrawal-destination
  • authorize → transaction:authorize
Breaking change: The end-to-end flows were also renamed, and their previous names were removed. Create session rejects the previous names with a 400 request_invalid error:
  • deposit → transaction:deposit-e2e
  • withdrawal → transaction:withdrawal-e2e
The Widget also no longer applies an option with an invalid value: it drops it and uses the default, and keeps logging the issues to the browser console.DocumentationActions required
  • End-to-end sessions: Change deposit and withdrawal to transaction:deposit-e2e and transaction:withdrawal-e2e in your Create session requests. Sessions with the previous names can no longer be created. See Removed flow names.
  • Select and authorize sessions: Change select-for-deposit, select-for-withdrawal and authorize to the new names in your Create session requests. See Deprecated flow names.
  • Setups with the SDK: Update to @uphold/enterprise-payment-widget-web-sdk 0.22.0, and change the generic type of PaymentWidget to the new flow names.
New FeaturePayment

Crypto transfers in Payment Widget end-to-end flows

SummaryThe deposit and withdrawal flows of the Payment Widget now support crypto transfers, alongside cards and banks.
  • Deposits: the user picks the destination account, the asset and the network, reviews the network instructions and gets the deposit address. As the user sends the funds from their own wallet, the complete event returns the deposit method shown (via: "deposit-method") instead of a transaction, as it does for banks. Uphold creates the transaction when the transfer is detected on-chain.
  • Withdrawals: the user picks the asset and the network, enters or scans the destination address, enters the amount and reviews the quote. When the quote requires the Travel Rule, the widget collects the information with the Travel Rule Widget before creating the transaction. The complete event returns the transaction, as it does for cards and banks.
Sessions without paymentMethods now offer bank, card and crypto. To offer crypto only, set paymentMethods to [{ "type": "crypto" }] in the Create session request. Use availableAssets to restrict the assets, as it replaces the assets filter of crypto.DocumentationThe crypto select flow guides moved to Select for Deposit and Select for Withdrawal.Actions required
  • End-to-end deposit sessions: Handle a complete value with via: "deposit-method" and depositMethod.type: "crypto", or set paymentMethods to exclude crypto.
  • End-to-end withdrawal sessions: Crypto is now offered by default. Set paymentMethods to exclude crypto to keep the previous behaviour.
  • QR code scanning: To let users scan the destination address from a QR code, allow the Widget to use the camera:
    • With the Web SDK: Update @uphold/enterprise-payment-widget-web-sdk to v0.19.0 or later, which adds camera 'src' to the iframe allow attribute.
    • Without the SDK: Add camera 'src' to the iframe allow attribute yourself.
    • Native apps: Request camera access from the OS, and let the WebView grant it to the page.
    See Allow camera access for QR code scanning.
EnhancementBreaking ChangeTravel Rule

Request for information outcome in Travel Rule Widget

SummaryThe Travel Rule Widget now waits for the request for information to resolve before firing complete, and reports the outcome in the event value. After the user submits the form, the Widget polls the request for information for up to about 2 minutes, then fires complete with:
  • requestForInformation — its id and status (ok, failed, or pending if it is still being resolved).
  • trigger.reason — request-for-information-status-changed when the request for information was resolved, or max-retries-reached when the Widget stopped polling while it was still pending, as is common for asynchronous proofs such as the Satoshi test.
This applies to both the deposit-form and withdrawal-form flows, and replaces the previous complete value. The Payment Widget’s end-to-end withdrawal flow uses the same behaviour when it runs the Travel Rule step.DocumentationActions required
  • complete handlers: Read requestForInformation.status from the event value instead of fetching the request for information right away. Proceed when it is ok, and keep monitoring it with Get request for information when it is pending.
  • Setups with the SDK: Update to @uphold/enterprise-travel-rule-widget-web-sdk 0.10.0 for the TravelRuleCompleteValue type.
New FeaturePayment

Bank transfers in Payment Widget end-to-end flows

SummaryThe deposit and withdrawal flows of the Payment Widget now support bank transfers, alongside cards: FPS for UK users, and ACH, FedNow / RTP and Wire (deposits only) for US users.
  • Deposits: the user picks the destination account, sets up their bank details and gets the transfer instructions to use in their banking app. As the user sends the transfer from their own bank, the complete event returns the deposit method shown (via: "deposit-method") instead of a transaction. Uphold creates the transaction when the funds arrive.
  • Withdrawals: the user picks or adds a bank account, enters the amount and reviews the quote with the expected processing time. The complete event returns the transaction, as it does for cards.
Sessions without paymentMethods now offer both card and bank. To offer bank only, set paymentMethods to [{ "type": "bank" }] in the Create session request. Use availableAssets to restrict the assets, as it replaces the assets filter of bank.DocumentationActions required
  • End-to-end deposit sessions: Handle a complete value with via: "deposit-method" for bank deposits, or set paymentMethods to [{ "type": "card" }] to keep card only.
  • End-to-end withdrawal sessions: Bank is now offered by default. Set paymentMethods to [{ "type": "card" }] to keep card only.
  • Setups with the SDK: Update to @uphold/enterprise-payment-widget-web-sdk 0.19.0. It also adds web-share 'src' to the iframe allow attribute, which lets users share the bank transfer instructions through the device’s share sheet.
  • Setups without the SDK: Add web-share 'src' to the iframe allow attribute to let users share the bank transfer instructions.
New FeatureKYC

Tax details support in KYC Widget

SummaryThe KYC Widget now supports the tax-details process for US users. Pass it in the processes array when creating a session and the Widget collects the user’s Taxpayer Identification Number and a W-9 certification with e-signature. For users in other regions, tax details are still collected via the REST API.DocumentationActions required
  • Setups with the SDK: Update to @uphold/enterprise-kyc-widget-web-sdk 0.5.0.
New FeaturePayment

End-to-end deposit and withdrawal flows in Payment Widget

SummaryThe Payment Widget now supports the deposit and withdrawal flows. A single session carries the user from choosing an account and a payment method, through amount entry, quoting and authorization, to a finished transaction. Your app receives one complete event containing the transaction, with no separate quote or authorize session to manage.Customize the experience with the amountSuggestions, availableAssets, fees and initialSelection options in the Create session request.DocumentationActions required
  • Setups with the SDK: Update to @uphold/enterprise-payment-widget-web-sdk 0.17.0.
EnhancementDeprecatedKYCPaymentTravel Rule

Simplified Widget initialization

SummaryThe KYC, Payment, and Travel Rule Widgets now load from session.url alone. Set the Widget options in the Create session request (KYC, Payment, Travel Rule) and load the returned URL.Deprecated: The following still work, but will be removed in a future release:
  • Sending the session object in the init message.
  • Passing paymentMethods or maxAccountsPerAsset to the Payment Widget from your frontend.
DocumentationActions required
  • Create session: Move your Widget options to the request body. If you set theme or layout, also keep passing them from your frontend for now (KYC, Payment, Travel Rule).
  • Setups with the SDK: Update to @uphold/enterprise-kyc-widget-web-sdk 0.4.0, @uphold/enterprise-payment-widget-web-sdk 0.16.0, or @uphold/enterprise-travel-rule-widget-web-sdk 0.9.0.
  • Setups without the SDK: Stop sending the session object in the init message.
New FeatureKYC

Customer due diligence support in KYC Widget

SummaryThe KYC Widget now supports the customer-due-diligence process. Pass it in the processes array when creating a session and the Widget collects the user’s financial profile alongside the other verification steps.Documentation
New FeaturePayment

Google Pay support in Payment Widget

SummaryIntroduced support for Google Pay deposits in the Payment Widget. Users authorize each transfer with the native Google Pay sheet.Documentation
EnhancementTravel Rule

Crypto withdrawal RFI support in Travel Rule Widget

SummaryThe Travel Rule Widget now resolves the pending RFI automatically once the user completes the withdrawal-form flow.DetailsDocumentation
New FeaturePayment

Apple Pay support in Payment Widget

SummaryIntroduced support for Apple Pay deposits and withdrawals in the Payment Widget. Users authorize each transfer with the native Apple Pay sheet.The authorize flow also supports a new headless mode that renders only the Apple Pay button, letting you embed it directly into your own layout. See AuthorizeMode.This feature requires @uphold/enterprise-payment-widget-web-sdk version 0.15.0 or higher.Documentation
New FeatureKYC

Profile process support for the KYC Widget

SummaryThe KYC Widget now supports the profile process, in addition to identity and proof-of-address. You can collect the user’s basic information (name, date of birth, citizenship, and address) directly within the Widget by including profile in the session’s processes.Documentation
New FeaturePayment

PayPal support in Payment Widget

SummaryIntroduced support for PayPal deposits and withdrawals in the Payment Widget.This feature requires @uphold/enterprise-payment-widget-web-sdk version 0.14.0 or higher.Documentation
New FeatureKYCPaymentTravel Rule

Responsive layout on larger screens and the layout option

SummaryUphold Widgets now adapt to the available space. On phones they fill their container, and on larger screens (tablets and up) they render as a centered, fixed-size card. This applies to the KYC Widget, Payment Widget, and Travel Rule Widget.To give applications control over this framing, all three Widgets now accept a new optional layout option:
  • 'boxed' (default): on larger screens (tablets and up), centers the Widget and frames its content as a fixed-size card; on smaller screens it fills its container.
  • 'fluid': renders the Widget so it fills its container, with no frame or centering, so your own container (e.g. a modal) acts as the frame.
This option is optional — the responsive layout is enabled by default ('boxed'), so no code changes are required to adopt it. Set layout: 'fluid' only when you want to provide your own framing.The layout option requires @uphold/enterprise-kyc-widget-web-sdk version 0.3.0, @uphold/enterprise-payment-widget-web-sdk version 0.14.0, or @uphold/enterprise-travel-rule-widget-web-sdk version 0.7.0 or higher.Documentation
New FeaturePaymentTravel Rule

New design system and richer theming for Payment and Travel Rule Widgets

SummaryThe Payment Widget and Travel Rule Widget now run on Uphold’s new design system. This brings a refreshed visual appearance to both Widgets.On top of this, theme customization is now consistent across all Widgets through a shared WidgetThemeOption type. In addition to forcing light or dark mode, applications can now customize brand colors, typography, and per-component styles (button, input, and card border radii) on the Payment and Travel Rule Widgets, matching the customization already available on the KYC Widget. The Travel Rule Widget now also fully respects the selected appearance, including in dark mode.Rich theme customization on the Payment Widget requires @uphold/enterprise-payment-widget-web-sdk version 0.13.0 or higher.Rich theme customization on the Travel Rule Widget requires @uphold/enterprise-travel-rule-widget-web-sdk version 0.6.0 or higher.Documentation
New FeatureKYC

KYC Widget

SummaryIntroduced the KYC Widget, a fully Uphold-managed, embeddable solution for collecting KYC data from your users without building a custom verification interface.
The Widget currently supports the identity and proof-of-address processes. Support for additional processes will be added in future releases.
Documentation
Breaking ChangePayment

Asset selection in crypto withdrawal flow

SummaryThe crypto withdrawal flow in the Payment Widget now supports crypto asset selection, along network and destination address, simplifying the user journey and concentrating all data collection required for a crypto withdrawal inside the Payment Widget. The complete event payload for via: "crypto-network" selections now includes a new selection.asset field containing the selected asset code (e.g. BTC, XRP).The updated CryptoNetworkSelection type ships in @uphold/enterprise-payment-widget-web-sdk version 0.12 or higher — partners should upgrade to that version to get proper TypeScript support for the new selection.asset field.Documentation
New FeaturePayment

Dark mode support in Payment Widget

SummaryIntroduced dark mode support in the Payment Widget. By default, the Widget automatically matches the user’s system appearance preference. Applications embedding the Widget can also force a specific theme by passing the theme option when instantiating it.Theme override support requires @uphold/enterprise-payment-widget-web-sdk version 0.11 or higher.Documentation
New FeaturePayment

ACH support in Payment Widget

SummaryIntroduced support for ACH bank transfers in the Payment Widget, allowing users in the United States to perform ACH deposits and withdrawals.Documentation
New FeaturePayment

Account limit per asset in Payment Widget

SummaryIntroduced the maxAccountsPerAsset option in the Payment Widget, allowing partners to set the number of accounts that can be created per asset when generating bank deposit details. Check the documentation for more details on how this option works.Documentation
New FeaturePayment

Crypto support and payment method filtering in Payment Widget

SummaryIntroduced support for cryptocurrency deposits and withdrawals in the Payment Widget. Users can now generate details for crypto deposits and provide destination addresses for crypto withdrawals.Partners can now configure which payment methods to make available to their users through the new paymentMethods option. This allows filtering by payment type (card, bank, crypto), and for crypto and bank options, filtering which assets are available to the user.Documentation
New FeaturePaymentTravel Rule

Travel Rule Widget

SummaryIntroduced the Travel Rule Widget, a fully Uphold-managed, embeddable solution that enables compliant collection and exchange of originator and beneficiary information for crypto transactions — ensuring adherence to global Travel Rule regulations.
New FeaturePayment

FPS support in Payment Widget

SummaryIntroduced support for Faster Payments Service (FPS) in the Payment Widget, supporting instant push bank deposits and bank withdrawals for users in the United Kingdom and EU.Documentation
New FeaturePayment

Card support in Payment Widget

SummaryIntroduced the Payment Widget, a fully Uphold-managed, embeddable solution that allows partners to support payment methods without implementing the API endpoints.The Payment Widget is launched with support for debit and credit cards.Documentation