Configure Your Connect Widget
This 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.
If 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.
For 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. |
Configure Your Connect Widget Step-by-Step
The section walks you through configuring your widget URL request.
Every step in this guide requires configuring the Request Widget URL endpoint.
Set the Widget Type
The widget_type configuration ensures the widget URL you'll receive is for the Connect Widget.
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-CAen-USesfr
The following example sets the language of the Connect Widget that will be returned to Spanish.
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
modetoverification.
More on "mode": "verification"
Verification mode is used to gather account and routing numbers, which we call instant account verification (IAV). Setting the mode to verification will change several behaviors for the Connect Widget and for associated members:
- The end user will be prompted to verify an existing connection (if they have one) before going to search.
- Connect will only search for and display institutions that support IAV.
- After gathering credentials, the widget will start aggregating IAV data rather than account and transaction data.
- Because this is for IAV,
include_transactionswill be set to false, so no transaction data will be gathered. If this data is needed, you must explicitly setinclude_transactionstotrue. - Background aggregation will be disabled for members created by the Connect Widget, even if the
include_transactionsparameter is set totrue. For existing connections, the existing background aggregation setting is preserved. - For end users who search for an institution that doesn't support IAV, the microdeposits flow begins and the end user is presented with the option to verify using microdeposits. In the microdeposit flow, no member is created on the MX platform. You must log the
microdeposit_guidin step 5 and use it to load the widget in the correct configuration when the end user returns several days later to verify their deposit amounts. Loading with the correctmicrodeposit_guidensures the widget prompts for verification amounts and perform other tasks related to microdeposit verifications.
If you need to collect account owner identity data in addition to verification or aggregation data, you can set that in the next step. Identity data must be aggregated in addition to either Account Aggregation or Instant Account Verification data.
The following example shows a request where the mode is set to verification.
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:
|
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. Since all the relevant data is already returned, there won't be a second aggregation. |
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": trueclient_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 ofwindow.postMessage(eventObject). - Set the
oauth_referral_sourcetoAPPso 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.
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_urlorui_message_webview_url_scheme(we recommend usingclient_redirect_urlif possible)enable_app2appoauth_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.
Set the Widget's Default View
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.
If 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.
Even 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.
Set the Color Scheme
If you want to load the widget in dark mode, set "color_scheme": "dark". It defaults to light.
You've configured your Connect Widget!