Integrate using MX's Connect Widget
By the end of this guide, you'll be able to connect a user to their financial institution, resolve connection errors, and retrieve financial data using the Platform API and Connect Widget.
If you're using Platform API v2011101, see Legacy Guides.
Prerequisites
Before using this guide, ensure the following:
- You've signed up for the Client Dashboard and can access your API keys
- Your IP addresses are whitelisted in the Client Dashboard
- Users exist on the MX system or you've created a user
- You have registered for OAuth, unless you're using our test institution
- You have set up how you'll send held data to MX (if your institution has held data)
Get the Widget URL
To open the Connect Widget, you'll use the Request Widget URL endpoint to retrieve a unique URL. The parameters you set in this request determine how the widget behaves.
The URL expires after ten minutes or upon first use, whichever occurs first. You'll need to obtain a new URL each time the page loads or reloads.
In this request, set widget_type to connect_widget and data_request.products to include the products you want to aggregate.
Considerations
Setting products
The products you set in your widget URL request (through the data_request.products) determine what data will be aggregated and which institutions appear in the widget search results.
You can define the products using the following values.
Balance data is always included and doesn't need to be set.
| Product | Value |
|---|---|
| Instant Account Verification | account_verification |
| Account Owner Identification | identity_verification |
| Account Aggregation | transactions |
| Extended History | transaction_history |
| Statements | statements |
| Investments | investments |
| Rewards | rewards |
Not every field will populate for each product, as data availability depends on what the institution provides.
Impact of setting multiple products
Specifying multiple products restricts the widget to show only institutions that support all the requested products. This filtering affects conversion in the following ways:
- Fewer Available Institutions: Many institutions support only one product. More products requested means fewer institutions displayed to users. For example, requesting both
account_verificationandidentity_verificationwill only show institutions that are capable of providing both products. - OAuth Consent Requirements: For OAuth institutions, users must grant permission for all requested products. If they decline any permission, the connection will fail and they'll need to restart the OAuth flow.
Balance your data needs against potential reduction in available institutions and connection success rates.
Embed the Connect Widget
The following guides are available to help you embed the widget, depending on your needs:
- Web Widget SDK
- React Native SDK
- Embed in a browser using the JavaScript Loader
- Embed in a Webview
Follow our best practices to enhance the user experience and improve conversion.
Handle Widget Events
To let you know what's happening inside the widget as the widget takes the user through the connection process, MX sends widget events. For example, the Connect Loaded event tells you when the widget loads.
While you can leverage some events for data-tracking purposes, others you must handle. The way you'll handle these events depends on the method you chose to embed the widget.
For a list of all events and how to handle them, see Widget Events.
Considerations
Notable widget events
For a list of important widget events and what to do when you retrieve them, see Notable Widget Events.
Handling events in WebViews
Your native app must intercept all widget events and decide to either block or allow the event and send the user to the browser (like when a user is trying to visit a bank's site or trying to authenticate via OAuth).
For an example of handling events, see the iOS and Android demo apps.
Failure to appropriately handle navigation events in a WebView can lead to broken behavior, like replacing the Connect Widget with the bank's website with no way for the user to get back.
Build an OAuth Flow
Before you can use OAuth with real institutions, you must register for OAuth and request production access. If you haven't registered yet, you can still use our test institutions.
OAuth is a secure and standardized way to perform authentication without exchanging sensitive credentials like usernames and passwords.
To connect a user to their financial institution using OAuth, you'll follow this general workflow:
- Send the user to the financial institution's site
- Return the user to the Connect Widget
Follow our separate guide to connect users to institutions that require OAuth.
You can use the MXCU test institution to test a more realistic OAuth flow. See Testing OAuth with MXCU.
(Optional) Build a Microdeposits Flow
If you're using the widget to verify account details, you can use Microdeposits so users can still verify their details with institutions that don't support Instant Account Verification.
For more info, see Microdeposits Workflow in the Connect Widget.
Monitor Connection Statuses
When a user connects to an institution, a member is created in the MX system.
To proactively resolve connections issues that may arise, such as MFA challenges or credential changes, you must monitor the connection_status of each member that belongs to a user.
For guidance on how to handle each possible status, see Member Connection Statuses.
Ensure Data Aggregated
If the member has a connection_status of CONNECTED and the is_being_aggregated field is false, you're ready to retrieve the data from this connection.
When the widget is open, the Member Connected widget event will signal to you when the connection between the user and the financial institution has been successfully established.
To handle cases where the user initiated a connection to their institution then closed the widget before it finished aggregating, you must implement a polling workflow:
- Request the Read Member Status endpoint.
- In the response, check the
connection_statusandis_being_aggregatedfields. - If
connection_statusisCONNECTEDandis_being_aggregatedisfalse, exit this workflow and retrieve the data. If not, we recommend waiting 3 seconds before repeating this polling workflow.
Retrieve Data
If the member has a connection_status of CONNECTED and the is_being_aggregated field is false, you're ready to retrieve the data from this connection.
Consider checking the successfully_aggregated_at field. Depending on when the member last aggregated successfully, you can choose to aggregate the member again.
The following table shows you how to retrieve the data you set in your widget URL request. For your convenience, some data may have multiple endpoints for its retrieval.
| Requested Data | How to Retrieve It |
|---|---|
accounts or transactions | List Accounts, List Accounts by Member, Read Account, Read Account by Member, List Transactions by Account, List Transactions, or Read Transaction |
identification | List Account Owners by Member |
verification | List Account Numbers by Member or List Account Numbers by Account |
statements | 1. List Statements by Member or Read Statement by Member 2. (Optional) Download Statement PDF |
transaction_history | 1. List Accounts by Member, Read Account, or another GET accounts endpoint and save the resulting guid 2. Use the guid from the previous response in List Transactions by Account |
investments | List Holdings by Member, List Holdings by User, List Holdings by Account, or Read Holding |
rewards | List Rewards or Read Reward |
You've embedded our widget and can now retrieve data from a user's connection to their financial institution!