<context>:<action> format, where the context is what the flow works on — a transaction, an on-ramp or off-ramp order, or an order — and the action is what the widget does.
Flows fall into three groups:
- Select flows (such as
transaction:select-deposit-originandon-ramp:select-withdrawal-destination) — the widget links or selects a payment method and returns the selection to your app. - Authorize flows (such as
transaction:authorizeandorder:authorize-deposit) — the widget creates a transaction or an order from a quote you supply and handles any authorization challenge. They are the second half of the select flows, but they can also be used on their own. - End-to-end flows (such as
transaction:deposit-e2eandtransaction:withdrawal-e2e) — the widget carries the user all the way to an authorized transaction in a single session. Supports bank, card and crypto.
Available flows
Transaction flows
These flows move funds between the user’s Uphold account and an external payment method, as a transaction.On & Off Ramp flows
These flows move value between fiat and crypto in a single on-ramp or off-ramp order, where both ends are external to Uphold. They only offer the payment methods available for the order type, and only to users with theon-ramp or off-ramp capability.
Off-ramp orders have no authorize flow: the user sends the crypto deposit from their own wallet, so your backend creates the order with the REST API.
Choosing a flow
There are three ways to put these flows together:- End-to-end flows. One session does everything. Your backend creates a single
transaction:deposit-e2eortransaction:withdrawal-e2esession and your app receives the finished transaction. Bank and crypto deposits are the exception: the user sends the funds from their own bank or wallet, so your app receives the deposit method shown (the transfer instructions or deposit address) and learns about the transaction later, through webhooks. - Select flows followed by an authorize flow. The widget returns a selection from a select flow. Your backend then creates the quote with that selection and opens a second session with
transaction:authorize(ororder:authorize-depositfor an on-ramp order), so the widget can create the transaction or order and handle authorization. You build the amount entry and review screens. An on-ramp order uses two select sessions, one for each end of the order. - An authorize flow on its own. If you don’t use the widget to select payment methods — for example, you collect and store them yourself and create quotes through the API — you can still use the widget just to authorize the transaction or the order. The authorize flows only need a quote, so they do not depend on a select flow.
The authorize flows are not an alternative to the select flows or the end-to-end flows. They are the final step of the select flows, or a standalone way to complete a transaction or an order you have quoted yourself. The end-to-end flows already include authorization, so you never create a
transaction:authorize session for them.
Use the end-to-end flows to let the widget handle the whole experience. Use the select flows with an authorize flow to build the amount entry and review screens yourself while the widget manages payment methods. Use an authorize flow alone to manage payment methods yourself and use the widget only for authorization.
For step-by-step guides per payment method, see the Developer Guides, for example bank deposits, bank withdrawals, card deposits, card withdrawals, crypto deposits, crypto withdrawals, on-ramp and off-ramp. Session creation and setup shared by every flow is covered in Installation and setup.
Deprecated flow names
The transaction flows were renamed to the<context>:<action> format. The previous names are still accepted by Create session and the SDK, as aliases with the same behavior, options and complete payload, but they are deprecated and will be removed in a future release.
To migrate an existing integration:
- Change the
flowof your Create session requests to the new name. - With the Web SDK, update to a version that supports the new names and change the generic type of
PaymentWidget, for examplenew PaymentWidget<'transaction:authorize'>(session). - If your app reads
session.flow, or switches on the flow name, handle the new names too.
Removed flow names
The end-to-end flows were also renamed to the<context>:<action> format, with an -e2e suffix. Their previous names were removed, not deprecated: Create session rejects them with a 400 request_invalid error.
To migrate, change the
flow of your Create session requests and, with the Web SDK, the generic type of PaymentWidget, for example new PaymentWidget<'transaction:deposit-e2e'>(session). If your app reads session.flow, handle the new names too. Options and the complete payload are unchanged.