transaction:select-deposit-origin flow, where users can select or unlink a previously linked PayPal account directly in the widget. After the user confirms a PayPal deposit 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
- The user has completed onboarding.
- The
paypalcapability is enabled. - The Payment Widget is set up in your frontend. See Installation and setup.
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 deposit method
The Payment Widget’stransaction:select-deposit-origin 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 thetransaction:select-deposit-origin 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 PayPal. The event payload includes the selected PayPal external account — if it has already been previously authorized.
Handle cancellations
Handle errors
Theerror event fires for critical unrecoverable errors.
Select destination account
PayPal deposits can target any account. If the selected account is not in the PayPal account’s currency, the amount will be converted at settlement using Uphold’s prevailing rate. Make sure the destination asset has the necessary features enabled.Find an existing account
Call List accounts to retrieve the user’s accounts and let them pick the one they want to fund.Create a new account
If the user has no accounts, create one with Create account before proceeding.Create a quote
Call Create quote with PayPal as the origin and the user’s account as the destination. There are two ways to specify the PayPal origin:-
apmshortcut — usetype: "apm"withmethod: "paypal". This is always accepted, whether or not the user already has a linked PayPal account. -
external-accountreference — if the user already has a linked PayPal account, you can reference it directly withtype: "external-account"and itsid(from List external accounts):
apm shortcut.
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:
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’stransaction: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 thetransaction:authorize flow, passing the quoteId and adding authorize:paypal to the requirements array. 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
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
transaction.statusDetails.reason:
Handle cancellations
Thecancel event fires when the user navigates back without completing authorization.
Handle errors
Theerror 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:
Monitor for settlement
PayPal deposit transactions 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
Sample transaction
In a successful PayPal deposit, the origin is the external account representing the user’s PayPal account and the destination is the user’saccount.
Notify the user
After the transaction completes, display the transaction details to the user so they can confirm the deposit succeeded. It must include the PayPal logo and the PayPal account email used. Here’s an example:
You now support PayPal deposits via the Payment Widget.