> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Widget Implementation
## 1. Create a User
```shell theme={null}
curl -i -X POST https://int-live.moneydesktop.com/:client_id/users.json \
-H "Content-Type: application/vnd.moneydesktop.mdx.v5+json" \
-H "Accept: application/vnd.moneydesktop.mdx.v5+json" \
-H "MD-API-KEY: :api_key" \
-d '{
"user": {
"birthdate": "1959-07-17",
"credit_score": "718",
"email": "example@example.com",
"first_name": "John",
"gender": "MALE",
"id": "U-39XBF7",
"last_name": "Smith",
"metadata": "Additional Information",
"phone": "5055551234",
"zip_code": "87101"
}
}'
```
```json theme={null}
{
"user": {
"id": "U-39XBF7",
"birthdate": "1959-07-17",
"gender": "MALE",
"first_name": "John",
"guid": "USR-c4321d57a-9ae4-1fe3-6c4e-96a84fb92b50",
"last_name": "Smith",
"metadata": "Additional Information",
"credit_score": 718,
"email": "example@example.com",
"phone": "(505) 555-1234",
"zip_code": "87101",
"is_disabled": false,
"logged_in_at": null
}
}
```
## 2. Load the Connect Widget
There are two methods for loading the Connect widget: either getting a URL through the SSO API or using the widget loader script.
In either case, the Connect widget must be loaded with the `mode` configuration option set to `verification`.
### Option A - Use the SSO API
```
curl -i -X POST https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls.xml \
-H 'Content-Type: application/vnd.moneydesktop.sso.v3+xml' \
-H 'Accept: application/vnd.moneydesktop.sso.v3+xml' \
-H 'MD-API-KEY: :api_key' \
-d '
connect_widget
verification
'
```
### Option B - Use the Widget Loader
#### Get a URL
First, get a URL as described in option A above.
#### Add the Widget Loader Script to the Page
Our widgets are loaded onto the page through a custom javascript file we refer to as the "widget loader". This file can be placed anywhere on the page, but as we'll discuss in the next steps, it should be placed before any other code related to the widgets.
```
My Web Page
```
#### Add a Widget Placeholder Element
Next, we need to add a placeholder element that our widget loader will use to embed an iframe containing the widget. The element must have an id of `md-widget`. Building upon our example in Step 1, your code should now look something like this:
```
My Web Page
```
### Load the Widget
Next, we have to tell the widget loader to load the widget into the placeholder element. We do this by creating a new instance of the `MoneyDesktopWidgetLoader` class, which is defined in the widget loader script.
When you instantiate `MoneyDesktopWidgetLoader`, you must pass in an object with at least the required url parameter and possibly one or more optional parameters.
The widget loader will wait until the page has been loaded and then load the widget into the placeholder element. The resulting HTML on the page will look similar to the example on the right.
| Parameter | Default Value | Description | Additional Information | |
| --------- | ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| autoload | optional | `true` | Determines if the widget should load automatically (see Loading widgets at different times). | |
| config | optional | | This contains an object in which you can pass several configuration options specific to a given widget type, such as mode and is\_mobile\_webview. | |
| height | optional | `600` | The height (in pixels or percentage) of the widget. | |
| id | optional | 'md-widget' | Tells the widget loader what element to place the widget in (see Loading more than one widget). | |
| width | optional | '100%' | The width (in pixels or percentage) of the widget. | |
| url | required | | The URL of the widget, received through an SSO request. | |
```
My Web Page
My Web Page
```
## 3. End Users Enter Credentials and Launch Verification Job
The Connect widget handles the creation of a `member` as well as the verification and MFA processes.
Partners need to listen for a couple important event messages from Connect: member status update and member connected. The first will give you the member\_guid and the current connection\_status which will give you an idea of what’s happening with connection process; the second will tell you when the member has been successfully connected so you can move on to the next steps. If your implementation uses WebViews, you’ll need to listen for the same messages, but given through the postMessage alternative for WebViews.
When the `connection_status` value is `CONNECTED`, you can move on to step 4.
Or, alternatively, if the end user closes the Connect widget 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 verification status via Nexus as in step 4.
You may also choose to set up a member webhook which will deliver the information you need as the member's state changes.
## 4. Get an API Token
This endpoint returns an `api_token` which can then be used to open a Nexus session. The `user_id` must match the `id` specified when creating a the `user`.
Each `api_token` is one-time use and expires in ten minutes. A fresh `api_token` must be requested each time a Nexus session is initiated
```shell theme={null}
curl -i https://int-sso.moneydesktop.com/:client_id/users/:user_id/api_token.xml \
-H "Accept: application/vnd.moneydesktop.sso.v3+xml" \
-H "MD-API-KEY: :api_key"
```
```json theme={null}
{
"api_token": {
"token": "VVCFDQY3Iig3ODM3LTlmNDItMmY1OS03NDZhLWIwNTcwNDc2NGRiNXwzZjg1MTQ4YzAyMThkZjI2OTI2ZjFjYmJhNmY1MzU2MTI0MThiNTIyOGVjYjg4YTRjNjljODJhYTQ3MWMwMTQyZGY5ZmM1OGQ2YmU1M2ZiMjNlOWZhZTE3Y2MxNjU4YWYxYmE0NjRiMDg3Nzk4N2U0YzU5ZTE1NjM1MDUwYjEzMTkzYzYyMzhiYjY3MDhmNjEyOGIzNjIyMDIwMmMzZTIzfFlVam1oSmhaOHNMMGVlMTg0YWhBODdmZWlVRmh4YlNKVGhVZUM4RVl5QXc="
}
}
```
## 5. Open a Nexus Session
Use this endpoint to get a session token. This session token must be sent as a header with each Nexus request. Each Nexus session is opened in the context of a single user associated with that session token.
When using the verification endpoints the create session request body should contain `"skip_aggregation":true`, as shown in the example below. This will prevent automatic aggregation being initiated for the user's existing members when the session is opened. Partners can then choose to aggregate the existing member, or to proceed directly to the verify member endpoint.
```shell theme={null}
curl -i -X POST https://int-data.moneydesktop.com/sessions \
-H 'MD-API-TOKEN: VVCFDQY3Iig3ODM3LTlmNDItMmY1OS03NDZhLWIwNTcwNDc2NGRiNXwzZjg1MTQ4YzAyMThkZjI2OTI2ZjFjYmJhNmY1MzU2MTI0MThiNTIyOGVjYjg4YTRjNjljODJhYTQ3MWMwMTQyZGY5ZmM1OGQ2YmU1M2ZiMjNlOWZhZTE3Y2MxNjU4YWYxYmE0NjRiMDg3Nzk4N2U0YzU5ZTE1NjM1MDUwYjEzMTkzYzYyMzhiYjY3MDhmNjEyOGIzNjIyMDIwMmMzZTIzfFlVam1oSmhaOHNMMGVlMTg0YWhBODdmZWlVRmh4YlNKVGhVZUM4RVl5QXc=' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json' \
-d '{"session":{"skip_aggregation":true}}'
```
```json theme={null}
{
"session":{
"token":"de2uS4jEwSYN7W0eoF_ZiLJQ7rtQaDbA9NkCZr_U4gujctbMw_WZYz7u6q3NMDlTYYCSSR7O3ec1fOP2wArN0g"
}
}
```
## 6. Check the Member's Verification Status
Several fields on the `member` give important information about the state of the verification including `connection_status`, `is_being_aggregated`, `successfully_aggregated_at`. These fields are also used for standard aggregation jobs, hence the reference in their names.
A connection status of `CONNECTED` means that the `member` was successfully authenticated and verification has begun. The `is_being_aggregated` field will tell you whether the verification job has completed; the field will be `true` while verification is taking place and returns to `false` when verification is complete. The `successfully_aggregated_at` field will tell you the exact time that the verification job has completed.
You may need to repeatedly poll this endpoint until either an end state or an actionable state is reached.
Depending on the exact state of the member, partners may need to re-load the Connect widget with a specific set of options in order to resolve an actionable member state.
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"member": {
"aggregated_at": "2022-07-01T16:52:07+00:00",
"background_aggregation_is_disabled": "false",
"connection_status": "CONNECTED",
"connection_status_id": 6,
"connection_status_message": "Connected to MX Bank.",
"external_guid": null,
"guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"institution_code": "mxbank",
"institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
"is_being_aggregated": false,
"is_managed_by_user": true,
"is_manual": false,
"is_oauth": false,
"is_user_created": true,
"metadata": "Additional information",
"most_recent_job_guid": "JOB-d6bb804b-6d12-44f1-b0ad-403441c03372",
"name": "MX Bank",
"needs_updated_credentials": false,
"revision": 1412,
"successfully_aggregated_at": "2022-07-01T16:52:11+00:00",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
## 7. Read the Account Numbers
If MX has both an account number and a routing number for at least one of the member's accounts, that information will be returned when calling read account numbers. No information will be returned for accounts that are missing a value for one or both of these fields.
```shell theme={null}
curl -i https://int-data.moneydesktop.com/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/account_numbers \
-H 'MD-SESSION-TOKEN: :session_token' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'
```
```json theme={null}
{
"account_numbers": [
{
"account_guid": "ACT-82ac32b4-06e6-48a9-8440-17e49bb3d720",
"account_number": "1174165092",
"guid": "ACN-e72d3448-0c58-4a9d-a236-f89bdca7eabb",
"institution_number": null,
"member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
"passed_validation": true,
"routing_number": "998007868",
"transit_number": null,
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
]
}
```