transaction:select-withdrawal-destination flow. Your backend then creates the quote and the transaction directly via the REST API.
This guide uses the select flows, where your app builds the amount entry and review screens and handles errors. For a single-session experience where the widget handles the amount, quote and errors, see End-to-end. To compare all flows, see Flows.
The transaction flows were renamed to the
<context>:<action> format. The previous names still work, as aliases with the same behavior and complete payload, but they are deprecated and will be removed in a future release:To migrate, change the
flow of the Create session request and, with the Web SDK, the PaymentWidget generic type. 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.
Walkthrough
Select source account
Card withdrawals can be sourced from any account. If the selected account is not in the card’s currency, the balance will be converted at the time of the transaction using Uphold’s prevailing rate. Make sure the origin asset has the necessary features enabled. Call List accounts to retrieve the user’s accounts and let them pick the one to withdraw from.Link or select a card account
The widget session lets the user link a new card or select an existing one.Create a widget session
Call Create widget session to start thetransaction:select-withdrawal-destination flow. To customize the theme and layout, see Create a session.
session object with a url field that loads the widget. Return response.session to your frontend as is.
Set up the widget
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 Web SDK for the SDK’s native-bundling pattern, or Setup without the SDK for the no-SDK approach that loads the session
url directly as the WebView’s top-level page.Handle the complete event
Thecomplete event fires after the user selects a card. The event payload includes the selected card external account.
Handle cancellations
Handle errors
Theerror event fires for critical unrecoverable errors. Card-specific errors (duplicate card, country mismatch, card limits) are handled by the widget internally.
Create a quote
Call Create quote with the origin account and the selected card external account as destination.Quotes are short-lived. Use
refreshAt to drive re-quoting: if the user hasn’t confirmed by then, create a new quote and show the updated amounts, since there’s no refresh endpoint. The quote’s expiresAt is equal to or later than refreshAt, to give the user time to complete an external action needed to proceed, such as authorizing an APM payment.Confirm and create transaction
Once the user confirms, call Create transaction with the quote ID.account and the destination is the external-account representing the card. The transaction status is initially processing and updates to completed once the transfer settles.
Monitor for settlement
Card withdrawal transactions may remain inprocessing 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
- core.transaction.created —
- Polling (fallback): Get transaction
Notify the user
Display an in-app confirmation when the transaction iscompleted, and send an email if applicable.
You now support card withdrawals via the Payment Widget.