Connect Widget Implementation
Create a User
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
_10curl -i -X POST https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls.xml \_10 -H 'Content-Type: application/vnd.moneydesktop.sso.v3+xml' \_10 -H 'Accept: application/vnd.moneydesktop.sso.v3+xml' \_10 -H 'MD-API-KEY: :api_key' \_10 -d '<url>_10 <type>connect_widget</type>_10 <mode>verification</mode>_10 </url>'
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.
_10<html>_10 <head>_10 <title>My Web Page</title>_10 <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>_10 </head>_10 <body>_10 </body>_10</html>
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:
_10<html>_10 <head>_10 <title>My Web Page</title>_10 <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>_10 </head>_10 <body>_10 <div id="md-widget"></div>_10 </body>_10</html>
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. |
_30<html>_30 <head>_30 <title>My Web Page</title>_30 <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>_30 <script type="text/javascript">_30 var myWidget = new MoneyDesktopWidgetLoader({_30 url: 'https://widgets.moneydesktop.com/md/connect/XXXXX',_30 width: 850,_30 height: 550_30 });_30 </script>_30 </head>_30 <body>_30 <div id="md-widget"></div>_30 </body>_30</html>_30<html>_30 <head>_30 <title>My Web Page</title>_30 <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>_30 <script type="text/javascript">_30 var myWidget = new MoneyDesktopWidgetLoader();_30 </script>_30 </head>_30 <body>_30 <div id="md-widget' class='md-widget-loaded">_30 <iframe width="850" height="550" border="0" frame="0" frameborder="0" allowtransparency="true" src="https://widgets.moneydesktop.com/md/connect/XXXXX" marginheight="0" marginwidth="0"></iframe>_30 </div>_30 </body>_30</html>
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.
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
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.
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.
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.