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-originandon-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-originandoff-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 theauthorize_order_failederror code.
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-originselect-for-withdrawal→transaction:select-withdrawal-destinationauthorize→transaction:authorize
400 request_invalid error:deposit→transaction:deposit-e2ewithdrawal→transaction:withdrawal-e2e
- On-ramp via Payment Widget
- Off-ramp via Payment Widget Coming soon
- Payment Widget flows
- SDK reference
- Create session
- End-to-end sessions: Change
depositandwithdrawaltotransaction:deposit-e2eandtransaction:withdrawal-e2ein 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-withdrawalandauthorizeto the new names in your Create session requests. See Deprecated flow names. - Setups with the SDK: Update to
@uphold/enterprise-payment-widget-web-sdk0.22.0, and change the generic type ofPaymentWidgetto the new flow names.
Crypto transfers in Payment Widget end-to-end flows
SummaryThedeposit 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
completeevent 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
completeevent returns the transaction, as it does for cards and banks.
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.Documentation- Crypto deposit via Payment Widget
- Crypto withdrawal via Payment Widget
- Payment Widget flows
- SDK reference
-
End-to-end
depositsessions: Handle acompletevalue withvia: "deposit-method"anddepositMethod.type: "crypto", or setpaymentMethodsto excludecrypto. -
End-to-end
withdrawalsessions: Crypto is now offered by default. SetpaymentMethodsto excludecryptoto 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-sdkto v0.19.0 or later, which addscamera 'src'to the iframeallowattribute. - Without the SDK: Add
camera 'src'to the iframeallowattribute yourself. - Native apps: Request camera access from the OS, and let the WebView grant it to the page.
- With the Web SDK: Update
Request for information outcome in Travel Rule Widget
SummaryThe Travel Rule Widget now waits for the request for information to resolve before firingcomplete, 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— itsidandstatus(ok,failed, orpendingif it is still being resolved).trigger.reason—request-for-information-status-changedwhen the request for information was resolved, ormax-retries-reachedwhen the Widget stopped polling while it was stillpending, as is common for asynchronous proofs such as the Satoshi test.
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 requiredcompletehandlers: ReadrequestForInformation.statusfrom the event value instead of fetching the request for information right away. Proceed when it isok, and keep monitoring it with Get request for information when it ispending.- Setups with the SDK: Update to
@uphold/enterprise-travel-rule-widget-web-sdk0.10.0 for theTravelRuleCompleteValuetype.
Bank transfers in Payment Widget end-to-end flows
SummaryThedeposit 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
completeevent 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
completeevent returns the transaction, as it does for cards.
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.Documentation- Bank deposit via Payment Widget
- Bank withdrawal via Payment Widget
- Payment Widget flows
- SDK reference
- End-to-end
depositsessions: Handle acompletevalue withvia: "deposit-method"for bank deposits, or setpaymentMethodsto[{ "type": "card" }]to keep card only. - End-to-end
withdrawalsessions: Bank is now offered by default. SetpaymentMethodsto[{ "type": "card" }]to keep card only. - Setups with the SDK: Update to
@uphold/enterprise-payment-widget-web-sdk0.19.0. It also addsweb-share 'src'to the iframeallowattribute, which lets users share the bank transfer instructions through the device’s share sheet. - Setups without the SDK: Add
web-share 'src'to the iframeallowattribute to let users share the bank transfer instructions.
Tax details support in KYC Widget
SummaryThe KYC Widget now supports thetax-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-sdk0.5.0.
End-to-end deposit and withdrawal flows in Payment Widget
SummaryThe Payment Widget now supports thedeposit 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.Documentation- Payment Widget flows
- Create session
- SDK reference
- Card deposit via Payment Widget
- Card withdrawal via Payment Widget
- Setups with the SDK: Update to
@uphold/enterprise-payment-widget-web-sdk0.17.0.
Simplified Widget initialization
SummaryThe KYC, Payment, and Travel Rule Widgets now load fromsession.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
initmessage. - Passing
paymentMethodsormaxAccountsPerAssetto the Payment Widget from your frontend.
- KYC Widget installation and setup
- Payment Widget installation and setup
- Travel Rule Widget installation and setup
- Create session: Move your Widget options to the request body. If you set
themeorlayout, also keep passing them from your frontend for now (KYC, Payment, Travel Rule). - Setups with the SDK: Update to
@uphold/enterprise-kyc-widget-web-sdk0.4.0,@uphold/enterprise-payment-widget-web-sdk0.16.0, or@uphold/enterprise-travel-rule-widget-web-sdk0.9.0. - Setups without the SDK: Stop sending the session object in the
initmessage.
Customer due diligence support in KYC Widget
SummaryThe KYC Widget now supports thecustomer-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.DocumentationGoogle 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.DocumentationCrypto withdrawal RFI support in Travel Rule Widget
SummaryThe Travel Rule Widget now resolves the pending RFI automatically once the user completes thewithdrawal-form flow.Details- RFI resolution: The widget calls Update request for information internally — no backend call needed from your integration.
- Withdrawal flow (updated)
- Create session
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.Theauthorize 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.DocumentationProfile process support for the KYC Widget
SummaryThe KYC Widget now supports theprofile 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.DocumentationPayPal 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.DocumentationResponsive 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.
'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.DocumentationNew 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 sharedWidgetThemeOption 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.DocumentationKYC 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.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. Thecomplete 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.DocumentationDark 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 thetheme option when instantiating it.Theme override support requires @uphold/enterprise-payment-widget-web-sdk version 0.11 or higher.DocumentationACH 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.DocumentationAccount limit per asset in Payment Widget
SummaryIntroduced themaxAccountsPerAsset 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.DocumentationCrypto 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 newpaymentMethods 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