> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment Widget flows

> Compare the Payment Widget flows — select, authorize and end-to-end, for transactions and for on-ramp and off-ramp orders — and choose the one that fits your integration.

Every Payment Widget session is created for a specific **flow**, which decides what the widget renders and what your app gets back. Flow names follow the `<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-origin` and `on-ramp:select-withdrawal-destination`) — the widget links or selects a payment method and returns the selection to your app.
* **Authorize flows** (such as `transaction:authorize` and `order: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-e2e` and `transaction: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](https://developer.uphold.com/rest-apis/core-api/transactions/overview.md).

| Flow | Group | The widget... |
| - | - | - |
| `transaction:select-deposit-origin` | Select | Links or selects a payment method to deposit from, and returns the selection to your app |
| `transaction:select-withdrawal-destination` | Select | Links or selects a payment method to withdraw to, and returns the selection to your app |
| `transaction:authorize` | Authorize | Creates a transaction from a quote you supply, and handles any authorization challenge |
| `transaction:deposit-e2e` | End-to-end | Owns the whole deposit — account and amount selection, quoting and authorization — in one session |
| `transaction:withdrawal-e2e` | End-to-end | Owns the whole withdrawal in one session |

### On & Off Ramp flows

These flows move value between fiat and crypto in a single [on-ramp or off-ramp order](https://developer.uphold.com/developer-guides/on-off-ramp/introduction.md), where both ends are external to Uphold. They only offer the payment methods available for the order type, and only to users with the `on-ramp` or `off-ramp` capability.

| Flow | Group | The widget... |
| - | - | - |
| `on-ramp:select-deposit-origin` | Select | Links or selects the card or APM, such as Apple Pay or PayPal, the user pays with, and returns the selection to your app |
| `on-ramp:select-withdrawal-destination` | Select | Collects the crypto asset, network and address that receives the crypto, and returns them to your app |
| `off-ramp:select-deposit-origin` | Select | Selects the crypto asset and network the user sells, and returns them to your app, without an address |
| `off-ramp:select-withdrawal-destination` | Select | Links or selects the card that receives the payout, and returns the selection to your app |
| `order:authorize-deposit` | Authorize | Creates an on-ramp order from a quote you supply, authorizes its card or APM deposit, and returns the order once the outcome of the deposit is known |

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](https://developer.uphold.com/developer-guides/on-off-ramp/off-ramp/via-rest-api.md).

## Choosing a flow

There are three ways to put these flows together:

1. **End-to-end flows.** One session does everything. Your backend creates a single `transaction:deposit-e2e` or `transaction:withdrawal-e2e` session 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.
2. **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` (or `order:authorize-deposit` for 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.
3. **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.

> [!NOTE]
>
> 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.

| | End-to-end | Select + authorize | Authorize only |
| - | - | - | - |
| Widget sessions your backend creates | One | Two or more — one per select flow, and one for the authorize flow | One |
| Who selects the payment method | The widget | The widget | Your app |
| Who selects the amount | The widget | Your app | Your app |
| Who creates the quote | The widget | Your backend | Your backend |
| Who refreshes expired quotes | The widget | Your app | Your app |
| Who handles quote and authorization errors | The widget recovers in-flow and only emits `error` for failures it cannot recover from | Your app | Your app |
| `complete` payload | A transaction (`{ transaction, trigger }`), or for bank and crypto deposits the deposit method shown (`{ via, selection }`) | A selection (`{ via, selection }`), then a transaction (`{ transaction, trigger }`) or an order (`{ order, trigger }`) | A transaction (`{ transaction, trigger }`) or an order (`{ order, trigger }`) |
| Control over the amount and review screens | The widget renders them, configured via options | Full — you build them | Full — you build 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.

> [!NOTE]
>
> For step-by-step guides per payment method, see the Developer Guides, for example [bank deposits](https://developer.uphold.com/developer-guides/bank-transfers/deposit/via-payment-widget/end-to-end.md), [bank withdrawals](https://developer.uphold.com/developer-guides/bank-transfers/withdrawal/via-payment-widget/end-to-end.md), [card deposits](https://developer.uphold.com/developer-guides/card-transfers/deposit/via-payment-widget/end-to-end.md), [card withdrawals](https://developer.uphold.com/developer-guides/card-transfers/withdrawal/via-payment-widget/end-to-end.md), [crypto deposits](https://developer.uphold.com/developer-guides/crypto-transfers/deposit/via-payment-widget/end-to-end.md), [crypto withdrawals](https://developer.uphold.com/developer-guides/crypto-transfers/withdrawal/via-payment-widget/end-to-end.md), [on-ramp](https://developer.uphold.com/developer-guides/on-off-ramp/on-ramp/via-payment-widget.md) and [off-ramp](https://developer.uphold.com/developer-guides/on-off-ramp/off-ramp/via-payment-widget.md). Session creation and setup shared by every flow is covered in [Installation and setup](https://developer.uphold.com/widgets/payment/installation-and-setup.md).

## Deprecated flow names

The transaction flows were renamed to the `<context>:<action>` format. The previous names are still accepted by [Create session](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) 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.

| Deprecated name | New name |
| - | - |
| `select-for-deposit` | `transaction:select-deposit-origin` |
| `select-for-withdrawal` | `transaction:select-withdrawal-destination` |
| `authorize` | `transaction:authorize` |

To migrate an existing integration:

1. Change the `flow` of your [Create session](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) requests to the new name.
2. With the Web SDK, update to a version that supports the new names and change the generic type of `PaymentWidget`, for example `new PaymentWidget<'transaction:authorize'>(session)`.
3. 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](https://developer.uphold.com/rest-apis/widgets-api/payment/create-session.md) rejects them with a `400 request_invalid` error.

| Removed name | New name |
| - | - |
| `deposit` | `transaction:deposit-e2e` |
| `withdrawal` | `transaction:withdrawal-e2e` |

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.
