Widget Events

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.

WARNINGDon’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.

Web Widget SDK
React Native SDK
JavaScript Loader
WebView

If you’re using the Web Widget SDK, you’ll listen for widget events by passing a callbacks.onEvent handler to the ConnectWidget constructor. The handler receives an event object with type and metadata fields.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.

import { ConnectWidget } from '@mxenabled/web-widget-sdk'

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      switch (event.type) {
        case 'mx/connect/connected/backToSearch':
          console.log('User guid:', event.metadata.user_guid)
          console.log('Session guid:', event.metadata.session_guid)
          console.log('Context:', event.metadata.context)
          break
      }
    }
  }
})

NOTEIf you’re using our legacy React Native SDK, see the legacy documentation.

The Event callback function (type: (event: Event) => void) is called whenever an event occurs within the widget. It will always contain a type and metadata field.

type Event = {
  type: string // Event type identifier (for example, "mx/connect/oauthRequested")
  metadata: Record<string, unknown> // Event-specific data and context
}

Here’s an example that handles the OAuth Requested event:

const handleEvent = (event: Event) => {
  switch (event.type) {
    case "mx/connect/oauthRequested":
      console.log("OAuth requested with URL:", event.metadata)
      break

    default:
      console.log("Received event:", event.type, event.metadata)
  }
}

<ConnectWidget
  url="https://....."
  onEvent={handleEvent}
/>

When using the JavaScript Loader, events have the following properties:

The mx field (boolean) lets you filter out events coming from MX.
The type field (string) identifies what the event represents.
- Schema: mx/<entity|widget>/<event>
- Example: mx/connect/institutionSelected
The metadata object contains:
- user_guid (string)
- session_guid (string)
- x_callback_payload (returns if the X-CALLBACK-PAYLOAD header was defined in the Platform API widget URL request)

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

function handleEvent(event) {
  if (event.data.mx) {
    // handle the mx widget event using event.data.type and event.data.metadata.
  }
}

window.addEventListener('message', handleEvent)

When embedding the widget in a WebView, events have the following properties:

The mx field (boolean) lets you filter out events coming from MX.
The type field (string) identifies what the event represents.
- Schema: mx/<entity|widget>/<event>
- Example: mx/connect/institutionSelected
The metadata object contains:
- user_guid (string)
- session_guid (string)
- x_callback_payload (returns if the X-CALLBACK-PAYLOAD header was defined in the Platform API widget URL request)

Ensure is_mobile_webview is set to true when requesting a widget URL, which affects the following:

Sends events with window.location = {scheme}://{event path}?metadata={json encoded metadata} instead of window.postMessage(message). You must capture the URLs delivered via window.location = "someurl" calls within the iFrame, parse out the path and query string, then JSON-decode the metadata field. These events will all have the mx:// prefix and the following format: mx://<entity|widget>/<event>?metadata=<metadata as an encodedURI JSON string>.
Sets oauth_referral_source to APP so the OAuth flow will redirect back to a native application instead of sending an event to the opening window.
Prevents the widget from automatically trying to open an OAuth window; instead it will send the OAuth requested event so your app can correctly open the OAuth window in the user agent.

By default, the ui_message_webview_url_scheme will be mx. This can be configured when requesting a widget URL by setting the value to whatever custom string you prefer, for example yourAppScheme.

WARNINGYour app must capture all navigation events to mx:// and custom schemes like yourAppScheme:// so the WebView doesn’t lose the Connect Widget session and the app doesn’t break.

Example Navigation Event Schema

Schema:
{ui_message_webview_url_scheme}://{some/path}?metadata={jsonString}

Default:
mx://connect/loaded?metadata={jsonString}

Custom:
yourAppScheme://connect/institutionSearch?metadata={jsonString}

Suggested Configuration for WebViews

curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-type: application/json' \
-d '{
    "widget_url": {
      "widget_type": "connect_widget",
      "is_mobile_webview": true,
      "ui_message_version": 4,
      "ui_message_webview_url_scheme": "{app_scheme}"
    }
  }'

# Possible navigation events based on the config above:
# `mx://load`
# `yourAppScheme://connect/institutionSearch?metadata={...json...}

{
"widget_url": {
"type": "connect_widget",
"url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
"user_id": "partner-2345"
}
}

Code Examples

Java

public class MainActivity extends AppCompatActivity {
private WebView webView = null;
@Override
protected void onCreate(Bundle savedInstanceState) {
  webView = (WebView) findViewById(R.id.webview);
  webView.setWebViewClient(new ConnectWebviewClient());
  webView.getSettings().setDomStorageEnabled(true);
  webView.getSettings().setJavaScriptEnabled(true);
}
private class ConnectWebviewClient extends WebViewClient {
    @Override
    public boolean shouldOverrideUrlLoading(WebView view, String url) {
        if (url.startsWith("mx://")) {
            return true;
        }
        return false;
    }
}
}

Swift

class ViewController: UIViewController, WKUIDelegate {
override func viewDidLoad() {
  super.viewDidLoad()
  webView.delegate = self
  ...
}

func webView(_ webView: WKWebView, decidePolicyFor
navigationAction: WKNavigationAction,
decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

// Intercept custom URI
let surl = navigationAction.url?.absoluteString
if (surl?.hasPrefix("mx://"))! {
  // Take action here

  // Cancel request
  decisionHandler(.cancel)
  return
}

// Allow request
decisionHandler(.allow)
}
}

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

Widget Event	What To Do
Back to Search	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.
Connect Loaded	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.
Institution Search and Institution Selected	Use 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 Selected	If you don’t want the end user to return to connect more accounts after they connected to one, close the widget.
OAuth Requested	This 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 Ping	Used to keep the widget session alive. See Handling Session Timeouts for more info.

Back to Search

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)

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

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/connected/backToSearch') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/connected/backToSearch") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Context:", event.metadata.context)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/connected/backToSearch",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/loaded') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Initial step:', event.metadata.initial_step)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/loaded") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Initial step:", event.metadata.initial_step)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

The initial_step can be:

Value	Definition
`connected`	The initial step when configured with `current_member_guid` and the member is in a connected state.
`disclosure`	The 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.
`enterCreds`	The initial step when configured with `current_institution_guid` or `current_member_guid`, and `updated_credentials` set to `true`.
`loginError`	The initial step when configured with `current_member_guid` and the member is in an error state.
`mfa`	The initial step when configured with `current_member_guid` and the member has encountered multi-factor authentication.
`search`	The default initial step.
`verifyExistingMember`	The 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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/enterCredentials') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Institution:', event.metadata.institution)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/enterCredentials") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Institution:", event.metadata.institution)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/enterCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Initial Data Ready

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

NOTEThis 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.

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

Institution Search

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/institutionSearch') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Query:', event.metadata.query)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/institutionSearch") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Query:", event.metadata.query)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/institutionSearch",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "query": "MX Bank"
  }
}

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/selectedInstitution') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Code:', event.metadata.code)
        console.log('Guid:', event.metadata.guid)
        console.log('Name:', event.metadata.name)
        console.log('Url:', event.metadata.url)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/selectedInstitution") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Code:", event.metadata.code)
    console.log("Guid:", event.metadata.guid)
    console.log("Name:", event.metadata.name)
    console.log("Url:", event.metadata.url)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/selectedInstitution",
  "mx": true,
  "metadata": {
    "code": "mxbank",
    "guid": "INS-123",
    "name": "MX Bank",
    "session_guid": "ANS-123",
    "url": "www.example.com",
    "user_guid": "USR-123"
  }
}

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:

Value	Definition
`1000`	No demand deposit (DDA) accounts for verification job.

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/invalidData') {
        console.log('Code:', event.metadata.code)
        console.log('Member guid:', event.metadata.member_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('User guid:', event.metadata.user_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/invalidData") {
    console.log("Code:", event.metadata.code)
    console.log("Member guid:", event.metadata.member_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("User guid:", event.metadata.user_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/invalidData",
  "mx": true,
  "metadata": {
    "code": "1000",
    "member_guid": "MBR-123",
    "session_guid": "ANS-123",
    "user_guid": "USR-123"
  }
}

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.

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/invalidData/primaryAction') {
        console.log('Member guid:', event.metadata.member_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('User guid:', event.metadata.user_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/invalidData/primaryAction") {
    console.log("Member guid:", event.metadata.member_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("User guid:", event.metadata.user_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/memberConnected') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/memberConnected") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/connected/primaryAction') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/connected/primaryAction") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/memberError') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member.guid)
        console.log('Connection status:', event.metadata.member.connection_status)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/memberError") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member.guid)
    console.log("Connection status:", event.metadata.member.connection_status)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/memberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member": {
      "guid": "MBR-123",
      "connection_status": 6
    }
  }
}

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/createMemberError') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Institution guid:', event.metadata.institution_guid)
        console.log('Institution code:', event.metadata.institution_code)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/createMemberError") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Institution guid:", event.metadata.institution_guid)
    console.log("Institution code:", event.metadata.institution_code)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/createMemberError",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "institution_guid": "INS-123",
    "institution_code": "mxbank"
  }
}

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/memberDeleted') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/memberDeleted") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

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)

INFOA 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.

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/memberStatusUpdate') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
        console.log('Connection status:', event.metadata.connection_status)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/memberStatusUpdate") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
    console.log("Connection status:", event.metadata.connection_status)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/memberStatusUpdate",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "connection_status": 6
  }
}

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)

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

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.

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

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)

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

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)

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

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)

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

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)

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

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)

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

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/oauthError') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/oauthError") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

OAuth Requested

NOTEThis 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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/oauthRequested') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Url:', event.metadata.url)
        console.log('Member guid:', event.metadata.member_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/oauthRequested") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Url:", event.metadata.url)
    console.log("Member guid:", event.metadata.member_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/oauthRequested",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "url": "https://something.com",
    "member_guid": "MBR-123"
  }
}

Step Change

WARNINGConnect 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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/stepChange') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Previous:', event.metadata.previous)
        console.log('Current:', event.metadata.current)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/stepChange") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Previous:", event.metadata.previous)
    console.log("Current:", event.metadata.current)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/stepChange",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "previous": "search",
    "current": "enterCreds"
  }
}

Possible step values for previous and current can be:

Current/Previous Value	Definition
`addManualAccount`	Where the user creates manual accounts. Manual accounts are not currently offered in the Platform API; partners should not expect to see this value.
`connected`	Where the user lands when they have successfully connected.
`connecting`	Where the user goes while the connection is being attempted.
`disclosure`	Where the user reads the MX privacy policy and agrees by selecting Continue. This is optional and is turned off by default.
`enterCreds`	Where the user enters credentials for a particular institution.
`error`	Where the user lands when the member create was unsuccessful due to user or system error.
`existingMember`	Where the user lands if they are trying to add a member they have previously added.
`loginError`	Where the user lands when they have unsuccessfully connected due to user or system error.
`mfa`	Where the user enters in MFA responses.
`oauth`	Where the user goes instead of enter credentials if the institution and client supports oauth.
`search`	Where the user searches for institutions.
`timeOut`	When 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`.
`verifyExistingMember`	Where 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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/submitMFA') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/submitMFA") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

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

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)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/connect/updateCredentials') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
        console.log('Member guid:', event.metadata.member_guid)
        console.log('Institution:', event.metadata.institution)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/connect/updateCredentials") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
    console.log("Member guid:", event.metadata.member_guid)
    console.log("Institution:", event.metadata.institution)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/connect/updateCredentials",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123",
    "institution": {
      "code": "mxbank",
      "guid": "INS-123"
    }
  }
}

Sent when the app is loaded.

INFOThis 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).

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/load') {
        console.log('Type:', event.type)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/load") {
    console.log("Type:", event.type)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/load",
  "mx": true
}

Used to keep the widget session alive. See Handling Session Timeouts for more info. Fields:

user_guid (string)
session_guid (string)

Web Widget SDK
React Native SDK
JavaScript Loader

const widget = new ConnectWidget({
  containerSelector: '#mx-widget-container',
  url: widgetUrl,
  callbacks: {
    onEvent: (event) => {
      if (event.type === 'mx/ping') {
        console.log('User guid:', event.metadata.user_guid)
        console.log('Session guid:', event.metadata.session_guid)
      }
    }
  }
})

import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk"

const handleEvent = (event: Event) => {
  if (event.type === "mx/ping") {
    console.log("User guid:", event.metadata.user_guid)
    console.log("Session guid:", event.metadata.session_guid)
  }
}

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."
  onEvent={handleEvent}
/>

{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

How to Handle Events

Notable Widget Events

Back to Search

Connect Loaded

Enter Credentials

Initial Data Ready

Institution Search

Institution Selected

Invalid Data

Invalid Data, Primary Action Selected

Member Connected

Member Connected, Primary Action Selected

Member Connection Error

Member Create Error

Member Deleted

Member Status Update

Microdeposit Account Details Submitted

Microdeposit Blocked Routing Number

Microdeposit Come Back, Primary Action Selected

Microdeposit Error, Primary Action Selected

Microdeposit Flow Loaded

Microdeposit Verified

Microdeposit Verified, Primary Action Selected

OAuth Error

OAuth Requested

Step Change

Submit MFA

Update Credentials

Widget Load

Widget Ping

​How to Handle Events

​Notable Widget Events

​Back to Search

​Connect Loaded

​Enter Credentials

​Initial Data Ready

​Institution Search

​Institution Selected

​Invalid Data

​Invalid Data, Primary Action Selected

​Member Connected

​Member Connected, Primary Action Selected

​Member Connection Error

​Member Create Error

​Member Deleted

​Member Status Update

​Microdeposit Account Details Submitted

​Microdeposit Blocked Routing Number

​Microdeposit Come Back, Primary Action Selected

​Microdeposit Error, Primary Action Selected

​Microdeposit Flow Loaded

​Microdeposit Verified

​Microdeposit Verified, Primary Action Selected

​OAuth Error

​OAuth Requested

​Step Change

​Submit MFA

​Update Credentials

​Widget Load

​Widget Ping

How to Handle Events

Notable Widget Events

Back to Search

Connect Loaded

Enter Credentials

Initial Data Ready

Institution Search

Institution Selected

Invalid Data

Invalid Data, Primary Action Selected

Member Connected

Member Connected, Primary Action Selected

Member Connection Error

Member Create Error

Member Deleted

Member Status Update

Microdeposit Account Details Submitted

Microdeposit Blocked Routing Number

Microdeposit Come Back, Primary Action Selected

Microdeposit Error, Primary Action Selected

Microdeposit Flow Loaded

Microdeposit Verified

Microdeposit Verified, Primary Action Selected

OAuth Error

OAuth Requested

Step Change

Submit MFA

Update Credentials

Widget Load

Widget Ping