Configure Your Connect Widget

LEGACY GUIDEThis guide is for Platform API v2011101. For guidance on the newest version, see Connectivity Integration Guides.

The Connect Widget requires careful configuration for different tasks.

INFOIf you’re looking for guides to implement the widget using one of our SDKs or other implementation methods, see Implementation Guides.

You’ll configure your widget using the Request Widget URL endpoint, which will return a URL that you’ll embed into the SDK. When end users successfully connect to their institutions, the widget will automatically start aggregating data, depending on what you specified in your configuration. You’ll use separate API endpoints to actually read the data the widget has aggregated. If you want to know what data the widget can aggregate, see Data Aggregation.

Configuration Quick Reference

The following table shows the Connect Widget configurations used for common tasks.

INFOFor more guidance, see Configure Your Connect Widget Step-by-Step.

Task	Configuration
Answer MFA for a specific member	Set the `current_member_guid` to a member whose `connection_status` is `CHALLENGED`. The widget will load the MFA view so the end user can respond to the MFA challenge.
Disable search when loading a specific institution	Set `disable_institution_search` to `true` and set `current_institution_code` or `current_member_guid`. The widget will load the login view for the specified institution. You must listen to the Back to Search event to intercept the user navigating back to search during the flow.
Resolve a member’s error(s)	Set `current_member_guid` to a member in an error state. The widget will load in the error view so the end user can resolve the error.
Update a member’s credentials	Set `current_member_guid` to the desired member’s `guid`. If the member’s credentials need to be updated, the widget will load the Update Credentials view for the member.

The section walks you through configuring your widget URL request.

INFOEvery step in this guide requires configuring the Request Widget URL endpoint.

The widget_type configuration ensures the widget URL you’ll receive is for the Connect Widget.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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"
        }
    }'

2. Set the Language

Getting a widget in a specific language requires passing the desired language as a parameter in the Accept-Language header with requests to the Request Widget URL endpoint. Don’t use the locale parameter in the request body; the Accept-Language header is the only available option when embedding the Connect Widget by itself. If no header is provided, the Connect Widget will default to en-US. The following languages are supported in the Connect Widget:

en-CA
en-US
es
fr

The following example sets the language of the Connect Widget that will be returned to Spanish.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/widget_urls \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Accept-Language: es' \
-H 'Content-type: application/json' \
-d '{
        "widget_url": {
            "widget_type": "connect_widget"
        }
    }'

3. Set the Mode

The mode configuration sets which data the widget will later aggregate, sets which events we’ll detect in the widget that you could (or must) handle, and determines how you’ll set some other configurations. The mode defaults to aggregation and can be set to verification, depending on your needs.

If you just need the widget to aggregate account and transaction data, don’t set this configuration. It defaults to aggregation.
If you need the widget to retrieve account numbers and routing/transit numbers, relating to Instant Account Verification (IAV), then set the mode to verification.

4. Set Other Data Configurations

In addition to having the widget aggregate account and transaction data ("mode":"aggregation") or account and routing numbers ("mode":"verification"), you can set some other configurations that also affects which data the widget will aggregate.

Option	Type	Description
`disable_background_agg`	Boolean	This determines whether background aggregation is enabled or disabled for the member created by the Connect Widget. Defaults to `false` in `aggregation` mode and `true` in `verification` mode. A global default for all members can be set by reaching out to MX.
`include_identity`	Boolean	This determines whether account owner identification data (AOI, previously called “identity verification”) aggregates after the data that’s specified by the `mode` finishes aggregating. Defaults to `false`. This can be set in either `aggregation` or `verification` mode. Setting this to `true` will produce the following behaviors: The widget will only search for and display institutions that support the data the `mode` (`aggregation` or `verification`) is aggregating and AOI. The member connected postMessage event will not be sent until both aggregations are complete.
`include_transactions`	Boolean	This determines whether transaction data aggregates. Defaults to `true` in aggregation mode and `false` in verification mode. This can be set in either `aggregation` or `verification` mode. This option doesn’t affect future foreground or background aggregations. When `include_transactions` is set to `true` and the `mode` is set to `verification`, then a single aggregation will return the transactions and account numbers data for the verified accounts only. When `is_being_aggregated` goes to `false` then the aggregation is done.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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",
                "mode": "verification", // defaults to "aggregation".
                "disable_background_agg": true // defaults to `false` in `aggregation` mode and `true` in `verification` mode.
                "include_identity": false // defaults to false in both modes.
                "include_transactions": false // defaults to `true` in `aggregation` mode and `false` in `verification` mode. 
            }
        }'

5. Set Mobile Configuration

If you’re integrating the widget on a desktop platform, you can skip this step. If you’re integrating the widget onto a mobile platform, you’ll want to set:

"is_mobile_webview": true
client_redirect_url

When "is_mobile_webview": true the widget will:

Send events to the WebView via window.location = {scheme}://{event path}?metadata={json encoded metadata} instead of window.postMessage(eventObject).
Set the oauth_referral_source to APP so the OAuth flow will redirect back to a native application instead of sending a postMessage to the opening window.
Prevent the widget from automatically trying to open an OAuth window; instead it will send the OAuth requested postMessage so your app can correctly open the OAuth window in the user agent.

The following table details the configurations in this step.

Option	Type	Description
`client_redirect_url`	String	This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: "APP"`. For more info, see OAuth in WebViews.
`is_mobile_webview`	Boolean	This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates. For more info, see Events in WebViews.

The following example sets is_mobile_webview to true.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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
            }
        }'

6. Set Authentication Configurations

These options are all related to authentication and how it’s handled in different situations, including how some event messages are delivered. If you’re supporting OAuth flows, you’ll want to set:

client_redirect_url or ui_message_webview_url_scheme (we recommend using client_redirect_url if possible)
enable_app2app
oauth_referral_source. This is meant for hybrid webapp integrations. For more info, see OAuth in WebViews.

The following table details the configurations in this step.

Option	Type	Description
`client_redirect_url`	String	This determines the redirect destination at the end of OAuth when used with `is_mobile_webview: true` or `oauth_referral_source: "APP"`. For more info, see OAuth in WebViews.
`enable_app2app`	Boolean	This indicates whether OAuth app2app behavior is enabled for institutions that support it. Defaults to `true`. When set to `false`, the widget will not direct the end user to the institution’s mobile application. This setting is not persistent. This setting currently only affects Chase institutions.
`is_mobile_webview`	Boolean	This configures the widget to render in a mobile WebView. JavaScript event postMessages are replaced with URL updates. For more info, see Events in WebViews.
`oauth_referral_source`	String	This determines how MX will respond to the result of an OAuth flow. When set to `APP`, MX will redirect to the URI specified in the `ui_message_webview_url_scheme`. When set to `BROWSER`, MX will send a postMessage but not redirect. If `is_mobile_webview` is `true`, this defaults to `APP`. If `false`, it defaults to `BROWSER`. For more info, see OAuth in WebViews.
`ui_message_webview_url_scheme`	String	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`. For more info, see OAuth in WebViews.

The following shows an example request for an integration on a mobile app.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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,
                "enable_app2app": true,
                "client_redirect_url": "https://{yoursite.com}?status=success&member_guid={MBR-XXX}"
            }
        }'

You can load the Connect Widget directly to an institution (using the institution’s code or guid) or member (using the member’s guid) to let end users complete specific tasks without manually searching for the institution. If you’re using the widget in verification mode to prompt the end user for verification amounts and to perform other tasks related to microdeposit verifications, set the current_microdeposit_guid to load the widget. For more info, see How to Request a Microdeposit Verification.

WARNINGIf you set current_institution_code, current_institution_guid, or current_member_guid to true, you must set disable_institution_search to true to prevent the end user from accessing the search institution page and manually loading a different institution during the initial connection. You must also listen for the backToSearch postMessage event. See the dropdown that follows for more info.

Required steps if you set `disable_institution_search` to `true`

If you set disable_institution_search to true, you must also listen for the backToSearch event to intercept the user from navigating back to search during the flow.Don’t listen for any Primary Action postMessages when you disable search.

INFOEven if you configure the Connect Widget to disable institution search, you must still listen for the postMessage. All buttons that will take a user to the search institution page are still displayed in the Connect Widget experience and your user can still select them. The postMessage will notify you that the client has taken this action so you can direct your user elsewhere.

This may trigger during several “steps” in the Connect Widget flow:

Connected
MDV/Microdeposits Verified
Login Error
Credentials/OAuth (back button)

The following table details the configurations in this step.

Option	Type	Description
`current_institution_code`	String	Load the widget into the credential view for the specified institution.
`current_institution_guid`	String	Load the widget into the credential view for the specified institution.
`current_member_guid`	String	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`. When you load the Connect Widget with a specific member GUID, it will determine the best course of action based on the state of that member, such as prompting for MFA or resolving an error state. Rather than trying to figure out what do with with each and every connection_status, it is best to configure your request with the `current_member_guid` in question and allow it to automatically determine the best course of action for the end user. You should consider using this configuration with the `disable_institution_search` option to skip the search step. You will want to listen to the backToSearch postMessages to intercept the user navigating back to search during the flow. MX does not recommend using this configuration with the `update_credentials` option.
`current_microdeposit_guid`	String	Load the widget to whichever step the microdeposit process is currently in, which may be the verify amounts step, an error state, and so on.
`disable_institution_search`	Boolean	This determines whether the institution search is displayed within the Connect Widget. This option must be used with `current_institution_code`, `current_institution_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`.
`update_credentials`	Boolean	This option should be used sparingly Load the widget into a view that allows them to update the current member. Optionally used with `current_member_guid`. The best practice is to use `current_member_guid` and let the widget resolve the issue.

The following example will load the Connect Widget to a specific institution. Because in this example we’re loading to an institution directly, the request also disables the ability to search for institutions in the widget.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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",
                "current_institution_code": "bank_code",
                "disable_institution_search": true // since we load the widget to an institution, we must disable search.
            }
        }'

8. Set the Color Scheme

If you want to load the widget in dark mode, set "color_scheme": "dark". It defaults to light.

curl -i -X POST https://int-api.mx.com/users/{USR-guid}/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",
                "color_scheme": "dark" // defaults to "light".
            }
        }'

SUCCESSYou’ve configured your Connect Widget!

Legacy Connectivity Guides

Configure Your Connect Widget

Configuration Quick Reference