Skip to main content
The Payment Widget handles PayPal selection for withdrawals via the transaction:select-withdrawal-destination flow, where users can select or unlink a previously linked PayPal account directly in the widget. After the user confirms a PayPal withdrawal quote, the Payment Widget creates the transaction and completes the PayPal authorization — whether the account is new or already linked — via the transaction:authorize flow.
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

Walkthrough

The diagram shows a first-time authorization. For an already-authorized account, skip the sign-in — the widget only collects device data and reuses the stored authorization.

Select source account

PayPal withdrawals can be sourced from any account. If the selected account is not in the PayPal account’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.

Select withdrawal method

The Payment Widget’s transaction:select-withdrawal-destination flow presents the available payment methods, letting the user select PayPal when it’s available. It performs selection only: it does not create the quote or the transaction.

Create a widget session

Call Create widget session to start the transaction:select-withdrawal-destination flow. To customize the theme and layout, see Create a session.
The response contains a 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

The complete event fires after the user selects PayPal. The event payload includes the selected PayPal external account — if it has already been previously authorized.
Once you have the selection, proceed to Create a quote.

Handle cancellations

Handle errors

The error event fires for critical unrecoverable errors.
The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.

Create a quote

Call Create quote with the user’s account as the origin and PayPal as the destination. There are two ways to specify the PayPal destination:
  • apm shortcut — use type: "apm" with method: "paypal". This is always accepted, whether or not the user already has a linked PayPal account.
  • external-account reference — if the user already has a linked PayPal account, you can reference it directly with type: "external-account" and its id (from List external accounts):
The example below uses the apm shortcut.
A successful response includes the quote details and a requirements array. If it contains authorize:paypal, the user must authorize PayPal before the transaction can be created.

Present the order summary

Before creating the transaction, display an order summary of the quote — the amount, fees, and the origin and destination — so the user can review it. Here’s an example:
PayPal order summary
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.

Authorize and create the transaction

After the user confirms the PayPal quote, hand off to the Payment Widget’s transaction:authorize flow. It creates the transaction, runs the PayPal authorization, and polls until a terminal status is reached — so the same flow works for both new and already-authorized accounts.

Create an authorize session

Call Create widget session to start the transaction:authorize flow, passing the quoteId and adding authorize:paypal to the requirements array. To customize the theme and layout, see Create a session.
The response contains a session object with a url field that loads the widget. Return response.session to your frontend as is.

Set up the widget

Initialize the widget with the session. The widget interacts with PayPal, creates the transaction, and polls until a terminal status is reached. For a new account the user signs in to PayPal to authorize; for an already-authorized account they do not sign in again — the widget only collects device data and reuses the stored authorization.
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

The complete event does not guarantee success. Always check transaction.status and trigger.reason.
Failure reasons in transaction.statusDetails.reason:

Handle cancellations

The cancel event fires when the user navigates back without completing authorization.

Handle errors

The error event fires for critical unrecoverable errors. Most failures in this flow surface with a generic code: 'error' and a descriptive message. Transaction-creation failures are the exception: they use code: 'authorize_transaction_failed' with event.detail.error.details.reason: 'unable-to-create-transaction'. As with any Widget error, the original failure is preserved in event.detail.error.cause — for unable-to-create-transaction, event.detail.error.cause.code is one of:
The Payment Widget handles most errors internally. For unrecoverable errors, the widget fires an error event. It is the host application’s responsibility to handle these events, present an error message to the user, and unmount the widget.

Monitor for settlement

PayPal withdrawal transactions remain in processing while the payment settles. Monitor until the transaction reaches a terminal state.

Sample transaction

In a successful PayPal withdrawal, the origin is the user’s account and the destination is the external account representing the user’s PayPal account.

Notify the user

After the transaction completes, display the transaction details to the user so they can confirm the withdrawal succeeded. It must include the PayPal logo and the PayPal account email used. Here’s an example:
PayPal transaction completed confirmation

You now support PayPal withdrawals via the Payment Widget.

Request errors

Create quote and Create transaction reject a request with an HTTP error when it can’t go ahead, in which case no transaction is created. The table only lists the errors your integration should act on, such as by showing the user a message. The other errors usually point to an issue in your integration. See the API reference of each endpoint for the full list. The Payment Widget creates the transaction, so the errors of Create transaction reach you through its error event instead: an authorize_transaction_failed error whose event.detail.error.cause is the original error, with the status in httpStatusCode and the same code and details as in the table. The errors of Create quote are returned to your backend as usual.

Failure reasons

A transaction that was created can still fail afterwards: its status becomes failed, or on-hold when information is requested, and statusDetails.reason says why. You learn about it through the core.transaction.status-changed webhook, or by polling Get transaction. The table only lists the reasons your integration should act on, such as by notifying the user.