Web SDK

The Web Widget SDK simplifies Connect Widget integrations.

LEGACY SDKThis page documents the legacy Web SDK. For new integrations, see Web SDK.

After completing this guide, your application will display the Connect Widget using the Web Widget SDK, available on GitHub.

PREREQUISITESSign up for a developer account on the Client Dashboard.

Install the SDK at the root of your project using your preferred package manager.

npm
yarn

npm install --save @mxenabled/web-widget-sdk

yarn add @mxenabled/web-widget-sdk

2. Incorporate the SDK

The Web Widget SDK provides multiple modules that you can import and use in your application, depending on your build process.

CommonJS
ES
AMD
UMD

A CommonJS module is exported by this package and available by requiring @mxenabled/web-widget-sdk. Require this module and build your project with a build tool that supports CommonJS modules (such as browserify).

CommonJS

const widgetSdk = require("@mxenabled/web-widget-sdk")
const widget = new widgetSdk.ConnectWidget({
    container: "<CONTAINER SELECTOR>",
    url: "<Widget URL>"
    // additional widget options
})

An ES module is exported by this package and available by importing @mxenabled/web-widget-sdk. Import this module and build your project with a build tool that supports ES modules (such as webpack).

import * as widgetSdk from "@mxenabled/web-widget-sdk"
const widget = new widgetSdk.ConnectWidget({
    container: "<CONTAINER SELECTOR>",
    url: "<Widget URL>"
    // additional widget options
})

The AMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

AMD

<div id="container"></div>

<script src="https://requirejs.org/docs/release/2.3.6/minified/require.js"></script>
<script>
requirejs(["node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js"], function (widgetSdk) {
const widget = new widgetSdk.ConnectWidget({
    container: "#container",
    url: "<Widget URL>"
    // additional widget options
    })
})
</script>

The UMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

UMD

<div id="container"></div>

<script src="node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js"></script>
<script>
const widget = new widgetSdk.ConnectWidget({
    container: "#container",
    url: "<Widget URL>"
    // additional widget options
})
</script>

There are two options to generate the widget URL:

Option A: Using a Platform API endpoint
Option B: Using a proxy server

a. Platform API

Use the Request Widget URL endpoint to get a URL. Note that this url expires after ten minutes or upon first use, so you may need to request it again while following this guide.

Request
Response

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Accept-Version: v20250224' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data-raw '{
  "widget_url": {
    "widget_type":"connect_widget"
    }
  }'

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

Then set the URL from the API response in the url Widget class option. See Class Options for a complete list.

const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/..."
}

b. Proxy Server

The SDK can make requests on your behalf to your backend service that calls the Platform API. Pass the proxy URL to a widget component via the proxy option. See Class Options for a complete list. When using a proxy server, pass the widget’s configurations directly to the widget component.

Configurations List

Configuration option	Description
`colorScheme`	Load the widget with the specified `color_scheme`; options are `light` and `dark`. Defaults to `light`.
`currentInstitutionCode`	Load the widget into the credential view for the specified institution.
`currentInstitutionGuid`	Load the widget into the credential view for the specified institution.
`currentMemberGuid`	Load the widget into a specific member that contains an error or requires multifactor authentication. The widget will determine the best view to load based on the member’s current state. `current_member_guid` takes precedence over `current_institution_code` and `current_institution_guid`.
`disableInstitutionSearch`	This determines whether the institution search is skipped within the Connect Widget. This option must be used with `current_institution_code`, `current_instituion_guid`, or `current_member_guid`. You must listen to the backToSearch postMessages to intercept the user navigating back to search during the flow. Defaults to `false`.
`includeTransactions`	This determines whether transaction data are retrieved. Defaults to `true` in aggregation mode and `false` in verification mode. This can be set in either `aggregation` or `verification` mode. This option does not affect future foreground or background aggregations.
`language`	Load the widget in the specified language. Defaults to `en-US`. For more info, Language Support.
`uiMessageWebviewUrlScheme`	This is a client-defined scheme used in OAuth redirects in WebViews; also used in URL updates when these replace postMessages in WebViews. Defaults to `mx`.
`updateCredentials`	Load the widget into a view that allows them to update the current member. Optionally used with `current_member_guid`. This option should be used sparingly. The best practice is to use `current_member_guid` and let the widget resolve the issue.

const options = {
  container: "#widget",
  proxy: "https://server.com/mx-sso-proxy",
  colorScheme: "dark",
  disableInstitutionSearch: true
}

When you instantiate a widget with options, it mounts itself in the DOM and sets up event listeners. Call the unmount method when closing the widget and before creating a new instance.

const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/...."
}

// Instantiating `new sdk.ConnectWidget(...)` mounts the widget in the DOM
const widget = new widgetSdk.ConnectWidget(options)

// Call `unmount` to remove the element and event listeners
widget.unmount()

SUCCESSYou’ve set up the SDK and embedded the Connect Widget!

Class Options

You can configure the state and behavior of the widget with the following class options.

Options	Description
`container`	CSS selector or node reference to the element where the widget iframe should be mounted.
`iframeTitle`	Sets the title attribute of the iframe.
`proxy`	Proxy server URL.
`style`	Styles applied to the view containing the widget. Default styles: `border: "none"`, `height: "550px"`, `width: "320px"`
`url`	URL returned in the Request Widget URL response. This prop is required.

Troubleshooting

If widget events aren’t triggered, check the following:

Ensure your widget URL request is correctly configured for the Web SDK:
- ui_message_version is set to 4
- is_mobile_webview is set to false
Ensure you use the corresponding widget class for the widget_type in the widget URL request. For example, if you set widget_type to connect_widget, use the ConnectWidget class.

Next Steps

Now that the widget can display in your application, you’ll build some additional flows, specify the data you want to retrieve when a user connects to their financial institution, handle events the widget sends, and more. See Integrate using MX’s Connect Widget.

Legacy Connectivity Guides

1. Install the Web Widget SDK

2. Incorporate the SDK

3. Generate the Widget URL

a. Platform API

b. Proxy Server

4. Mount and Unmount the Widget

Class Options

Troubleshooting

Next Steps

​1. Install the Web Widget SDK

​2. Incorporate the SDK

​3. Generate the Widget URL

​a. Platform API

​b. Proxy Server

​4. Mount and Unmount the Widget

​Class Options

​Troubleshooting

​Next Steps

1. Install the Web Widget SDK

2. Incorporate the SDK

3. Generate the Widget URL

a. Platform API

b. Proxy Server

4. Mount and Unmount the Widget

Class Options

Troubleshooting

Next Steps