Skip to main content

Widget Events

A list of Connect Widget events, how to handle them, and best practices

When key actions occur in the Connect Widget, widget events are sent to you with the details that you need to respond to the event in your codebase.

warning

Don't use widget events for keeping data in sync between platforms. Webhooks are more reliable when coordinating events between your servers and MX servers.

How to Handle Events​

The way you'll handle widget events depends on your integration method.

If you're using the Web Widget SDK, you'll listen for widget events by passing callback functions in the widget options object to the class. The option names follow this naming scheme.

EventProp
Widgeton<event name>
Entityon<entity><action>

All payloads include the user_guid (string) and session_guid (string) fields.

The following is an example integration that lets you listen to the events we send.


_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onBackToSearch: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Context: ${payload.context}`)
_10
}
_10
})

Notable Widget Events​

The section details important widget events and what to do when you receive them.

Widget EventWhat To Do
Back to SearchIf you disabled the search institution step by setting disable_institution_search: true, listen to this event to know when your user will be navigated to the search step so you can close the widget.
Connect LoadedTrack the start of the user's journey. You can also use this if you intend on hiding the widget from the user until you know it's loaded.
Institution Search and Institution SelectedUse these events to track trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out and loads your users to connect to that institution directly.
Member Connected, Primary Action SelectedIf you don't want the end user to return to connect more accounts after they connected to one, close the widget.
OAuth RequestedThis event only applies if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView. Send the user to the OAuth provider's site, opening the URL (contained in the event's metadata) in the device’s default browser.
Widget PingUsed to keep the widget session alive. See Handling Session Timeouts for more info.

Sent when the user selects a button that navigates to the search step, as defined in the Step Change event. Used in relation with disable_institution_search widget configuration option.

Recommended use: If you disabled the search institution step by setting disable_institution_search: true, listen to this event to know when your user will be navigated to the search step so you can close the widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • (Only for SDKs) context (string)
warning

If you listen for this event, don't listen for any of the Primary Action events. You'll receive a double payload.


_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onBackToSearch: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Context: ${payload.context}`)
_10
}
_10
})

Connect Loaded​

Sent when the Connect Widget loads. It's often useful to know what “step” or view the user started on.

Recommended use: Track the start of the user's journey. You can also use this if you intend on hiding the widget from the user until you know it's loaded.

Fields:

  • user_guid (string)
  • session_guid (string)
  • initial_step (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onLoaded: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Initial step: ${payload.initial_step}`)
_10
}
_10
})

The initial_step can be:

ValueDefinition
connectedThe initial step when configured with current_member_guid and the member is in a connected state.
disclosureThe initial step when configured to display the disclosure screen that shows the MX privacy policy first. This is optional and is turned off by default.
enterCredsThe initial step when configured with current_institution_guid or current_member_guid, and updated_credentials set to true.
loginErrorThe initial step when configured with current_member_guid and the member is in an error state.
mfaThe initial step when configured with current_member_guid and the member has encountered multi-factor authentication.
searchThe default initial step.
verifyExistingMemberThe initial step when configured with data_request.products set to account_verification.

Enter Credentials​

Sent when a user submits credentials for a given institution for the first time.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • institution (object)
    • code (string)
    • guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onEnterCredentials: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Institution: ${payload.institution}`)
_10
}
_10
})

Initial Data Ready​

Deprecated

This event is deprecated and should not be used in new implementations.

note

This event only applies if you're using Platform API version 20250224.

Triggered when some initial data you requested has aggregated and is ready for retrieval.

When you receive this event, you can close the widget and retrieve some initial data to avoid making the user wait until every requested product finishes aggregating.

For more details, including what initial data is sent based on the products you set, see Accessing Priority Data.


_10
{
_10
"type": "mx/connect/initialDataReady",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"member_guid": "MBR-123"
_10
}
_10
}

Sent when the end user searches for an institution. This is useful in determining what users are searching for.

Recommended use: Track this to find trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out the FI directly and loads your users to connect to that institution directly.

Fields:

  • user_guid (string)
  • session_guid (string)
  • query (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onInstitutionSearch: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Query: ${payload.query}`)
_10
}
_10
})

Institution Selected​

Sent when an end user selects an institution from the institution list.

Recommended use: Similar to the Institution Search event. Track this to find trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out the FI directly and loads your users to connect to that institution directly.

Fields:

  • user_guid (string)
  • session_guid (string)
  • code (string)
  • guid (string)
  • name (string)
  • url (string)

_12
const widget = widgetSdk.ConnectWidget({
_12
url: "https://widgets.moneydesktop.com/md/connect/...",
_12
_12
onSelectedInstitution: (payload) => {
_12
console.log(`User guid: ${payload.user_guid}`) // string
_12
console.log(`Session guid: ${payload.session_guid}`) // string
_12
console.log(`Code: ${payload.code}`) // string
_12
console.log(`Guid: ${payload.guid}`) // string
_12
console.log(`Name: ${payload.name}`) // string
_12
console.log(`Url: ${payload.url}`) // string
_12
}
_12
})

Invalid Data​

Sent when there are no valid demand deposit (DDA) accounts on the member.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • code (string)
  • member_guid (string)
  • session_guid (string)
  • user_guid (string)

Conditions

  • "mode": "verification"
  • The member receives an error as one of the codes below.

The code can be:

ValueDefinition
1000No demand deposit (DDA) accounts for verification job.

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
invalidData: (payload) => {
_10
console.log(`Code: ${payload.code}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`User guid: ${payload.user_guid}`)
_10
}
_10
})

Invalid Data, Primary Action Selected​

Sent when there are no valid demand deposit (DDA) accounts on the member and the end user selects Try again on the associated error screen. When the end user selects Try again, the widget will send them to the institution search screen.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • member_guid (string)
  • session_guid (string)
  • user_guid (string)

Conditions

  • data_request.products includes account_verification.
  • disable_institution_search is set to true.
  • The member doesn't have any valid DDA accounts.
  • The user selects Try again on the error screen.

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
invalidDataPrimaryAction: (payload) => {
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`User guid: ${payload.user_guid}`)
_10
}
_10
})

Member Connected​

Sent when a member has successfully connected and the data you requested in your Widget URL request has finished aggregating.

Recommended use: Retrieve the data you requested in your Widget URL request, which has finished aggregating. If you don't want the user to acknowledge they connected to a member in our UI, you could close the widget after receiving this event and present your own success screen.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onMemberConnected: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
}
_10
})

Member Connected, Primary Action Selected​

Sent when the user selects the primary button on the connected step.

Recommended use: If you don't want the end user to return to connect more accounts, close the widget.

Fields:

  • user_guid (string)
  • session_guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onConnectedPrimaryAction: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
}
_10
})

Member Connection Error​

Sent when a member has encountered an error state.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member (object)
    • guid (string)
    • connection_status (number)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onMemberError: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member.guid}`)
_10
console.log(`Connection status: ${payload.member.connection_status}`)
_10
}
_10
})

Member Create Error​

Sent when a member failed to get created when credentials were entered.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • institution_guid (string)
  • institution_code (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onCreateMemberError: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Institution guid: ${payload.institution_guid}`)
_10
console.log(`Institution code: ${payload.institution_code}`)
_10
}
_10
})

Member Deleted​

Sent when a member has been deleted in the widget.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onMemberDeleted: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
}
_10
})

Member Status Update​

Sent when a member’s connection status has changed while connecting.

Recommended use: Useful for determining the current connection status of the member. If the status is CONNECTED, you can start polling to ensure that data is ready for retrieval. If the status is related to an error, you can begin a resolution flow depending on the error.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (string)
  • connection_status (number)
info

A connection_status of 6 (CONNECTED) doesn't mean data is available yet. To ensure that data is available, refer to the member connected event instead.


_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onMemberStatusUpdate: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
console.log(`Connection status: ${payload.connection_status}`)
_10
}
_10
})

Microdeposit Account Details Submitted​

Sent when the end user submits account details for a given institution for the first time and a microdeposit object is created on the MX system.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • microdeposit_guid (string)

_10
{
_10
"type": "mx/connect/microdeposits/detailsSubmitted",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"microdeposit_guid": "MIC-123"
_10
}
_10
}

Microdeposit Blocked Routing Number​

Sent when the end user submits a blocked routing number on the Enter Details step.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • routing_number (string)
  • reason (string). Possible values are:
    • BLOCKED: MX has blocked this routing number. Microdeposit verification can't proceed.
    • CLIENT_BLOCKED: An MX client has requested that this routing number be blocked. Microdeposit verification can't proceed.
    • IAV_PREFERRED: The institution associated with the routing number has an Instant Account Verification (IAV) connection that is preferred over microdeposit verification. The IAV flow will be suggested to the end user.

_10
{
_10
"type": "mx/connect/microdeposits/blockedRoutingNumber",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"routing_number": "123456789", # This is the user-entered routing number
_10
"reason": "BLOCKED",
_10
}
_10
}

Microdeposit Come Back, Primary Action Selected​

Sent when the end user selects the primary button on the Come Back step. This step is visible while the microdeposit is in the REQUESTED status.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • microdeposit_guid (string)

_10
{
_10
"type": "mx/connect/microdeposits/comeBack/primaryAction",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"microdeposit_guid": "MIC-123"
_10
}
_10
}

Microdeposit Error, Primary Action Selected​

Sent when the end user selects the primary button on the Error step. This page is visible after entering deposits and getting a PREVENTED status.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • microdeposit_guid (string)
  • microdeposit_status (string)

_10
{
_10
"type": "mx/connect/microdeposits/error/primaryAction",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"microdeposit_guid": "MIC-123",
_10
"microdeposit_status": "PREVENTED"
_10
}
_10
}

Microdeposit Flow Loaded​

Sent when the microdeposit flow is loaded in the Connect Widget.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • initial_step (string)

_10
{
_10
"type": "mx/connect/microdeposits/loaded",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"initial_step": "enterDetails"
_10
}
_10
}

Microdeposit Verified​

Sent when an end user successfully verifies the microdeposit amounts.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)
  • microdeposit_guid (string)

_10
{
_10
"type": "mx/connect/microdeposits/verified",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123",
_10
"microdeposit_guid": "MIC-123"
_10
}
_10
}

Microdeposit Verified, Primary Action Selected​

Sent when the end user selects the primary button on Verified step. This step is visible after entering the correct deposit amounts.

For guidance, see Microdeposits Workflow in the Connect Widget.

Fields:

  • user_guid (string)
  • session_guid (string)

_10
{
_10
"type": "mx/connect/microdeposits/verified/primaryAction",
_10
"mx": true,
_10
"metadata": {
_10
"user_guid": "USR-123",
_10
"session_guid": "ANS-123"
_10
}
_10
}

OAuth Error​

Sent when the user lands on the OAuth error page.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (optional) (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onOAuthError: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
}
_10
})

OAuth Requested​

note

This event only applies if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView.

Sent when the user navigates to the OAuth provider's site. Note that the redirect doesn't happen in WebViews. The native app will need to use this event to send the user to the URL contained in the metadata.

The URL given in the payload will always be an MX URL. The user will be routed to us first (for example, mx://connect/oauthRequested?metadata={...JSON encoded payload ...}), then to the provider.

Recommended use: Only use if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView.

Fields:

  • user_guid (string)
  • session_guid (string)
  • url (string)
  • member_guid (string)
warning

By passing your own method to this prop, you're overriding the default behavior of the SDK which is to load the OAuth URL in a new browser tab.

If you override this functionality, you must use the device's browser to authenticate the user with OAuth. You cannot use WebViews or iframes. This approach enhances security and leverages saved passwords and password managers. Many OAuth providers also block their web applications from loading in iframes or WebViews. Many OAuth providers also block their web applications from loading in iframes or WebViews.


_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onOAuthRequested: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Url: ${payload.url}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
}
_10
})

Step Change​

warning

Connect flows and steps are constantly being evaluated, updated, and optimized. The steps listed below are subject to change without notice.

Sent when the end user changes from one “step” to another.

Recommended use: Intended for analytics tracking purposes only, and not for controlling or altering the user's experience.

Fields:

  • user_guid (string)
  • session_guid (string)
  • previous (string)
  • current (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onStepChange: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Previous: ${payload.previous}`)
_10
console.log(`Current: ${payload.current}`)
_10
}
_10
})

Possible step values for previous and current can be:

Current/Previous ValueDefinition
addManualAccountWhere the user creates manual accounts. Manual accounts are not currently offered in the Platform API; partners should not expect to see this value.
connectedWhere the user lands when they have successfully connected.
connectingWhere the user goes while the connection is being attempted.
disclosureWhere the user reads the MX privacy policy and agrees by selecting Continue. This is optional and is turned off by default.
enterCredsWhere the user enters credentials for a particular institution.
errorWhere the user lands when the member create was unsuccessful due to user or system error.
existingMemberWhere the user lands if they are trying to add a member they have previously added.
loginErrorWhere the user lands when they have unsuccessfully connected due to user or system error.
mfaWhere the user enters in MFA responses.
oauthWhere the user goes instead of enter credentials if the institution and client supports oauth.
searchWhere the user searches for institutions.
timeOutWhen the user has been connecting for more than 60 seconds without any updates to the member, if the member's connection_status isn't PENDING.
verifyExistingMemberWhere the user can verify existing members when data_request.products includes account_verification.

Submit MFA​

Sent when a user submits an MFA answer.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onSubmitMFA: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
}
_10
})

Update Credentials​

Sent when a user submits credentials while trying to update their existing credentials.

Recommended use: Use as needed for your implementation, or for informational and tracking purposes.

Fields:

  • user_guid (string)
  • session_guid (string)
  • member_guid (string)
  • institution (object)
    • code (string)
    • guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onUpdateCredentials: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
console.log(`Member guid: ${payload.member_guid}`)
_10
console.log(`Institution: ${payload.institution}`)
_10
}
_10
})

Widget Load​

Sent when the app is loaded.

info

This event applies to all MX widgets. For the Connect Widget specifically, there is a separate event—Connect Loaded—that's sent when the widget loads and also includes the initial view the user started on. For more details, see Connect Loaded.

Only contains type (string) and mx (boolean).


_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onLoad: (payload) => {
_10
console.log(`Type: ${payload.type}`)
_10
console.log(`MX: ${payload.mx}`)
_10
}
_10
})

Widget Ping​

Used to keep the widget session alive.

See Handling Session Timeouts for more info.

Fields:

  • user_guid (string)
  • session_guid (string)

_10
const widget = widgetSdk.ConnectWidget({
_10
url: "https://widgets.moneydesktop.com/md/connect/...",
_10
_10
onPing: (payload) => {
_10
console.log(`User guid: ${payload.user_guid}`)
_10
console.log(`Session guid: ${payload.session_guid}`)
_10
}
_10
})

On this page