Skip to main content
The Payment Widget handles FPS bank account selection. Your backend creates the session, then continues with the REST API to create a quote and transaction once the user selects their destination bank account.
The Payment Widget does not create any transaction. Your backend must create the quote and transaction via the REST API after the user selects their bank account.
This guide uses the select flows, where your app builds the amount entry and review screens and handles errors. For a single-session experience where the widget handles the amount, quote and errors, see End-to-end. To compare all flows, see Flows.
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


Select source account

FPS withdrawals can be sourced from any account. If the selected account is not in GBP, 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 a bank account

The widget lets the user select an existing FPS-linked bank account.

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

Initialize the widget for the transaction:select-withdrawal-destination flow using the session data returned from the API.
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 when the user selects a bank account and completes the flow.
The event payload contains two primary properties:
  • via — set to external-account when the user selects a saved bank account.
  • selection — an external account object with the selected bank details.

Handle cancellations

The cancel event fires when the user closes the widget without selecting a bank account.

Handle errors

The error event fires when an error occurs during the bank account selection process.
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

To initiate the withdrawal, call Create quote with the origin as the user’s account and the destination as the selected FPS external account. Specify the amount and asset for the withdrawal.
A successful response returns a quote object with details about the withdrawal, including fees and expiration.
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.

Confirm and create transaction

After the user confirms the withdrawal, call Create transaction with the quote ID to execute the transfer.
In a successful FPS withdrawal, the origin is the user’s account and the destination is the external-account representing the user’s bank. The transaction status is initially processing and updates to completed once the transfer settles.

Monitor for settlement

The widget does not monitor for settlement. Your application must do this via webhooks or polling.

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.
You now support FPS bank transfer withdrawals via the Payment Widget.