About MXconnect

MXconnect is our embeddable widget that simplifies verification and other aggregation-type processes for end users and you, our partners. It takes care of searching for institutions, gathering credentials, creating and connecting members, MFA, and common errors.

For more about MXconnect, see our technical reference and developer guide.

1. Create a User

The first step is to create a user. A user represents your end user in the MX Platform. Make a POST request to the create user endpoint, as shown below.

We recommend that you include a unique id of your choice with the request. You may also include metadata, such as the date the user was created or the end user’s name. Don’t include any sensitive information here, such as credentials.

In the response, the API gives each new user an MX-defined guid (or user_guid when appearing outside the user object). Between your id and the guid, you can map between your system and ours. You’ll need the user guid for nearly every request on the MX API, at least when using basic authorization.

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "user": {
        "id": "partner-2345",
        "is_disabled": false,
        "email": "totally.fake.email@notreal.com",
        "metadata": "Yada yada yada"
      }
    }'

1
2
3
4
5
6
7
8
9
{
  "user": {
    "email": "totally.fake.email@notreal.com",
    "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
    "id": "partner-2345",
    "is_disabled": false,
    "metadata": "Yada yada yada"
  }
}

2. Load MXconnect in Verification Mode

Next, you’ll want to load an instance of MXconnect by first requesting a URL with the unique user GUID returned in the last request, then loading it in either a browser or app environment.

2.1 Request a URL

Set the mode parameter to verification and the widget_type parameter to connect_widget, as shown in the following example. Please see our API reference for complete information on the behaviors and settings affected by verification mode.

Endpoint:

POST /users/{user_guid}/widget_urls

1
2
3
4
5
6
7
8
9
10
11
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "color_scheme": "dark",
        "mode": "verification"
      }
    }'

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "partner-2345"
  }
}

2.2 Load URL in Embedded Environment

Loading the MXconnect URL properly depends on whether it is in a browser or an app, along with a number of other factors. For details on how to do this in both situations, please see our MXconnect developer guide.

3. End Users Interact with MX Connect

MXconnect handles the creation of a member as well as the IAV process and any MFA that may be encountered. It automatically asks end users to search for an institution, give their credentials, and determine which account they’d like to verify. It also deals with any errors along the way.

You’ll need to listen for a couple important event messages from MXconnect: “member status updated” and “member connected”. The first gives you the member_guid and the current connection_status; the second tells you when the member has been successfully connected so you can move on to the next steps.

Alternatively, if the end user closes MXconnect early or some other problem occurs before you see a CONNECTED status, you can simply use the member_guid to immediately check the member’s connection status.

Example when end user closes MXconnect Early

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
{
  "member": {
    "aggregated_at": "2020-05-07T22:01:00Z",
    "connection_status": "CONNECTED",
    "guid": "MBR-3bdc7d6b-efd4-1497-a0af-b23501cf9bd0",
    "is_authenticated": true,
    "is_being_aggregated": false,
    "successfully_aggregated_at": "2020-05-07T22:01:25Z"
  }
}

4. List the Account Numbers

The IAV job is now complete and you can list account and routing numbers. The MX Platform API has two endpoints for this: list account numbers by member and list account numbers by account. We show the first here.