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
- The user has completed onboarding and has the required capabilities enabled.
- The Payment Widget is set up in your frontend. See Installation and setup.
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 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
Initialize the widget for thetransaction: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
Thecomplete event fires when the user selects a deposit method and completes the flow.
via— is set todeposit-methodwhen the user selects a deposit method and completes the flow.selection— contains theaccountthat will receive the funds and thedepositMethodconfiguration with transfer instructions.
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
Thecancel event fires when the user closes the widget without selecting a deposit method.
Handle errors
Theerror event fires when an error occurs during the deposit method selection process.
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.- Webhook events (recommended):
- core.transaction.created
status: processing→ bank transfer received, pending posting
- core.transaction.status-changed
status: completed→ funds settledstatus: failed→ irrecoverable error
- core.transaction.created
- Polling (fallback): Get transaction
Sample transaction
The sample below shows an ACH deposit. Transactions for other supported networks have the same structure — onlyorigin.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 iscompleted, and send an email if applicable.
You now support ACH, Wire, RTP, and FedNow push bank deposits via the Payment Widget.