Payment Widget flows

Every Payment Widget session is created for a specific flow, which decides what the widget renders and what your app gets back. Flows fall into three groups:

Select flows (select-for-deposit, select-for-withdrawal) — the widget links or selects a payment method and returns the selection to your app.
Authorize flow (authorize) — the widget creates a transaction from a quote you supply and handles any authorization challenge. It is the second half of a select flow, but it can also be used on its own.
End-to-end flows (deposit, withdrawal) — the widget carries the user all the way to an authorized transaction in a single session.

Available flows

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

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 deposit or withdrawal session and your app receives the finished transaction.
Select flows followed by authorize. The widget returns a selection from select-for-deposit or select-for-withdrawal. Your backend then creates the quote with that selection and opens a second authorize session, so the widget can create the transaction and handle authorization. You build the amount entry and review screens.
authorize 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. The authorize flow only needs a quote, so it does not depend on a select flow.

authorize is not an alternative to the select flows or the end-to-end flows. It is the final step of the select flows, or a standalone way to complete a transaction you have quoted yourself. The end-to-end flows already include authorization, so you never create an authorize session for them.

	End-to-end (`deposit`, `withdrawal`)	Select (`select-for-*`) + `authorize`	`authorize` only
Widget sessions your backend creates	One	Two — `select-for-*` and `authorize`	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 }`)	A selection (`{ via, selection }`), then a transaction	A transaction (`{ transaction, 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 authorize to build the amount entry and review screens yourself while the widget manages payment methods. Use authorize 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 card deposits and card withdrawals. Session creation and setup shared by every flow is covered in Installation and setup.

Payment Widget

Travel Rule Widget

KYC Widget

Topper

Payment Widget flows

Available flows

Choosing a flow

​Available flows

​Choosing a flow

Available flows

Choosing a flow