Skip to main content
The Payment Widget handles deposit method selection across all supported US networks — ACH, Wire, FedNow, and RTP — and displays the necessary transfer instructions to the user. Your backend only needs to create the session and monitor for the incoming transfer. No per-network handling is required.
The Payment Widget does not create any transaction. Monitoring and processing the incoming transfer must be handled by your backend via webhooks or polling.
This guide uses the transaction:select-deposit-origin flow. To offer bank deposits in the same single-session experience as card deposits, with the widget handling the destination account, bank setup 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 deposit method

The widget lets the user select a deposit method and view transfer instructions that work across all supported US networks — ACH, Wire, FedNow, and RTP.

Create a widget session

Call Create widget session to start the transaction:select-deposit-origin 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-deposit-origin 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 deposit method and completes the flow.
The event payload contains two primary properties:
  • via — is set to deposit-method when the user selects a deposit method and completes the flow.
  • selection — contains the account that will receive the funds and the depositMethod configuration with transfer instructions.
The widget presents these details directly to the user, so you don’t need to display them separately. Across supported US rails, the transfer instruction fields such as routing and account details are shared, while depositMethod.details.network indicates the rail selected for this deposit method. No per-network handling is required.
In the API, "fednow" represents both the FedNow and RTP networks.
The optional secondaryNetworks field lists additional supported rails for the same account and transfer instructions, and it’s only present when more than one network is supported.

Handle cancellations

The cancel event fires when the user closes the widget without selecting a deposit method.

Handle errors

The error event fires when an error occurs during the deposit method 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.

Monitor for the incoming transfer

The widget presents the deposit instructions to the user but does not monitor for the incoming transfer. Your application must do this via webhooks or polling.

Sample transaction

The sample below shows an ACH deposit. Transactions for other supported networks have the same structure — only origin.node.network differs: "ach", "fednow" (FedNow and RTP), or "wire". In a successful ACH bank deposit, the origin is represented as a bank-address node. The destination is the user’s default USD account.

Notify the user

Display an in-app confirmation when the transaction is completed, and send an email if applicable.
You now support ACH, Wire, RTP, and FedNow push bank deposits via the Payment Widget.