Connect Widget Overview - MX Documentation

The Connect Widget lets end users search for and connect to their accounts. It collects users’ credentials, prompts for multifactor authentication, and resolves connection errors between end users and their financial institutions. You’ll embed the widget into your website or mobile app. We offer a React Native SDK for mobile implementations and a Web SDK for desktop implementations.

Integrate using MX's Connect Widget

UI Walkthrough

Retrievable Data

The following are example responses for each product.

Account and transaction data (using our Account Aggregation product)

See Account Aggregation for more info.This sample response shows the data you can expect to get for financial accounts.

{
"accounts": [
{
  "account_number": "5366",
  "apr": 1.0,
  "apy": 1.0,
  "available_balance": 1000.0,
  "available_credit": 1000.0,
  "balance": 1000.0,
  "cash_balance": 1000.0,
  "cash_surrender_value": 1000.0,
  "created_at": "2016-10-13T17:57:37.000Z",
  "credit_limit": 100.0,
  "currency_code": "USD",
  "day_payment_is_due": 20,
  "death_benefit": 1000,
  "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
  "holdings_value": 1000.0,
  "id": "1040434698",
  "imported_at": "2015-10-13T17:57:37.000Z",
  "institution_code": "chase",
  "insured_name": "Frodo Baggins",
  "interest_rate": 1.0,
  "is_closed": false,
  "is_hidden": false,
  "last_payment": 100.0,
  "last_payment_at": "2015-10-13T17:57:37.000Z",
  "loan_amount": 1000.0,
  "matures_on": "2015-10-13T17:57:37.000Z",
  "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
  "member_id": "member-9876",
  "member_is_managed_by_user": false,
  "metadata": "some metadata",
  "minimum_balance": 100.0,
  "minimum_payment": 10.0,
  "name": "Test account 2",
  "nickname": "My Checking",
  "original_balance": 10.0,
  "pay_out_amount": 10.0,
  "payment_due_at": "2015-10-13T17:57:37.000Z",
  "payoff_balance": 10.0,
  "premium_amount": 1.0,
  "routing_number": "68899990000000",
  "started_on": "2015-10-13T17:57:37.000Z",
  "subtype": "NONE",
  "total_account_value": 1.0,
  "type": "SAVINGS",
  "updated_at": "2016-10-13T18:08:00.000Z",
  "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
  "user_id": "partner-2345"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}

This sample response shows the data you can expect to get for transactions.

{
"transactions": [
{
  "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
  "account_id": "account123",
  "amount": 61.11,
  "category": "Groceries",
  "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
  "check_number_string": "6812",
  "created_at": "2016-10-06T09:43:42.000Z",
  "currency_code": "USD",
  "date": "2013-09-23T00:00:00.000Z",
  "description": "Whole foods",
  "extended_transaction_type": "partner_transaction_type",
  "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
  "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
  "is_bill_pay": false,
  "is_direct_deposit": false,
  "is_expense": true,
  "is_fee": false,
  "is_income": false,
  "is_international": false,
  "is_overdraft_fee": false,
  "is_payroll_advance": false,
  "is_recurring": false,
  "is_subscription": false,
  "latitude": -43.2075,
  "localized_description": "This is a localized_description",
  "localized_memo": "This is a localized_memo",
  "longitude": 139.691706,
  "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
  "member_is_managed_by_user": false,
  "memo": "This is a memo",
  "merchant_category_code": 5411,
  "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
  "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
  "metadata": "some metadata",
  "original_description": "WHOLEFDS TSQ 102",
  "posted_at": "2016-10-07T06:00:00.000Z",
  "status": "POSTED",
  "top_level_category": "Food & Dining",
  "transacted_at": "2016-10-06T13:00:00.000Z",
  "type": "DEBIT",
  "updated_at": "2016-10-07T05:49:12.000Z",
  "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
  "user_id": "partner-2345"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
}
}

Account and routing numbers (using our Instant Account Verification product)

See Instant Account Verification for more info.This sample response shows the data you can expect to get for account owners.

{
"account_numbers": [
{
  "account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
  "account_number": "10001",
  "institution_number": null,
  "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
  "routing_number": "091000019",
  "passed_validation": true,
  "transit_number": null,
  "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}

Account owner data (using our Account Owner Identification product)

See Account Owner Identification for more info.This sample response shows the data you can expect to get for account owners.

{
"account_owners": [
{    
  "account_guid": "ACT-82a93692-f756-534f-9b2e-ad10a0f38462",
  "address": "123 This Way",
  "city": "Middlesex",
  "country": "US",
  "email": "donnie@darko.co",
  "first_name": "Donnie",
  "guid": "ACO-63dc7714-6fc0-4aa2-a069-c06cdccd1af9",
  "last_name": "Darko",
  "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
  "owner_name": "Donnie Darko",
  "phone": "555-555-5555",
  "postal_code": "00000-0000",
  "state": "VA",
  "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
],
"pagination": {  
"current_page": 1,
"per_page": 25,
"total_entries": 1,
"total_pages": 1
}
}

Transaction data

You can configure the widget to return transactions when its mode is set to verification.This sample response shows the data you can expect to get for transactions.

{
"transactions": [
{
  "account_guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
  "account_id": "account123",
  "amount": 61.11,
  "category": "Groceries",
  "category_guid": "CAT-9588eaad-90a4-bb5c-66c8-1812503d0db8",
  "check_number_string": "6812",
  "created_at": "2016-10-06T09:43:42.000Z",
  "currency_code": "USD",
  "date": "2013-09-23T00:00:00.000Z",
  "description": "Whole foods",
  "extended_transaction_type": "partner_transaction_type",
  "guid": "TRN-265abee9-889b-af6a-c69b-25157db2bdd9",
  "id": "transaction-265abee9-889b-af6a-c69b-25157db2bdd9",
  "is_bill_pay": false,
  "is_direct_deposit": false,
  "is_expense": true,
  "is_fee": false,
  "is_income": false,
  "is_international": false,
  "is_overdraft_fee": false,
  "is_payroll_advance": false,
  "is_recurring": false,
  "is_subscription": false,
  "latitude": -43.2075,
  "localized_description": "This is a localized_description",
  "localized_memo": "This is a localized_memo",
  "longitude": 139.691706,
  "member_guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
  "member_is_managed_by_user": false,
  "memo": "This is a memo",
  "merchant_category_code": 5411,
  "merchant_guid": "MCH-7ed79542-884d-2b1b-dd74-501c5cc9d25b",
  "merchant_location_guid": "MCL-00024e59-18b5-4d79-b879-2a7896726fea",
  "metadata": "some metadata",
  "original_description": "WHOLEFDS TSQ 102",
  "posted_at": "2016-10-07T06:00:00.000Z",
  "status": "POSTED",
  "top_level_category": "Food & Dining",
  "transacted_at": "2016-10-06T13:00:00.000Z",
  "type": "DEBIT",
  "updated_at": "2016-10-07T05:49:12.000Z",
  "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
  "user_id": "partner-2345"
},
// •••
],
"pagination": {
"current_page": 1,
"per_page": 10,
"total_entries": 243,
"total_pages": 25
}
}

Connection Errors

When the widget is loaded, it automatically chooses the best course of action for resolving a connection error between a user and their financial institution. For more info, see Member Connection Statuses.

Browser Support

MX supports HTML5-compliant browsers that support TLSv1.2 or higher. Older versions of supported browsers aren’t explicitly tested. MX will review issues as reported, but upgrading may be required if compatibility can’t be ensured.

Supported Desktop Browsers

MX tests its web applications on the current version and previous version of the following browsers:

Browser	PC	Mac
Chrome	Yes	Yes
Microsoft Edge	Yes	N/A
Firefox	Yes	Yes
Safari	No	Yes

BLOCKED BROWSERSMX may actively block some browsers from displaying our products when the results would provide an extremely poor user experience. Browsers in Compatibility or Quirks mode may not function and can be blocked if performance is degraded.

Supported Mobile Browsers

MX tests its web applications on the current version and previous version of iOS and Android, using the following browsers:

Browser	iOS	Android
Chrome	No	Yes
Safari	Yes	N/A
WKWebView	Yes	N/A
Android WebView	N/A	Yes

NOTEUIWebView is no longer supported. Apple recommends using WKWebView.

Language Support

To change the display language from English, set the Accept-Language header in the Request Widget URL endpoint to one of these supported languages:

en-CA
es
fr

The Connect Widget uses a responsive design. Layout and styles may adjust based on screen size, and certain elements may become hidden/visible at different widths. The minimum dimensions supported for mobile and desktop platforms are:

Height: 550px
Width: 320px

Design changes may occur at the following width breakpoints, which are based on common device resolutions:

Small: 320px–767px
Medium: 768px–1199px
Large: 1200px and higher

NOTEBreakpoints and layout behavior are subject to change.

OAuth Support

You must register for OAuth before you can use it with real institutions. For institutions using an OAuth flow, the Connect Widget will redirect to that institution’s page or mobile app, where the end user can authorize the accounts they want to connect. See Connect Widget OAuth Workflows.

Handling Session Timeouts

When integrating our Connect Widget, consider the session timeout built into the widget and the session timeout built into your website or mobile app. The widget automatically times out after 15 minutes of inactivity. Reach out to your account representative to customize this duration. Thirty seconds before the timeout, a No recent activity screen appears and prompts the user to select Continue to avoid timing out. If no user activity is detected within those 30 seconds, the widget will timeout and display a Session expired screen.

Member Use Cases

NOTEWork with MX to enable this functionality.

You can opt in to setting the use_cases field in applicable requests so each member has an associated use_case. This ensures only the data associated with the use case for that member (PFM or Money Movement) is returned. It also lets you filter a user’s data through a single use_case, even if data relating to a different use_case is in our system. If you’ve implemented the Connect Widget and have worked with MX to enable member use cases, you must include the use_cases field when requesting your widget URL to ensure:

Each member is associated with a specific use case.
Our Personal Finance Management and Financial Insights products reflect data only for members with the PFM use case.
Members with "use_cases": ["MONEY_MOVEMENT"] do not aggregate transaction data.

In the Connect Widget, this change impacts the flow of new and existing members. For more info about other changes relating to creating members, updating members, and available query parameters for use cases, see the Platform API docs.

New Members

When you request a widget URL with a widget_type of connect_widget or connections_widget, set the use_cases field. The use cases provided in this request will be saved to any member created inside of the widget. For example, if you:

Set use_cases: ["PFM"] in the widget URL request.
Load the Connect Widget using the URL returned from the request.
Successfully create a member.
Read that member, which will have a use_case of PFM as set in step 1.

Existing Members

The widget won’t remove use cases from an existing member, it will only add new ones. For example, let’s assume a member already exists that has use_cases: ["MONEY_MOVEMENT"]:

You set use_cases: ["PFM"] in the widget URL request.
The end user finds their institution and enters their same credentials as before.
The widget will update the existing member so to have use_cases: [“MONEY_MOVEMENT”, "PFM"].

Integrate using MX's Connect Widget

UI Walkthrough

​Retrievable Data

​Connection Errors

​Browser Support

​Supported Desktop Browsers​

​Supported Mobile Browsers​

​Language Support

​Widget Dimensions

​OAuth Support

​Handling Session Timeouts

​Member Use Cases

​New Members

​Existing Members

Retrievable Data

Connection Errors

Browser Support

Supported Desktop Browsers

Supported Mobile Browsers

Language Support

Widget Dimensions

OAuth Support

Handling Session Timeouts

Member Use Cases

New Members

Existing Members