Skip to main content
Version: 1.0.0

Connect Accounts

Learning goals
  • Establish a connection between a user and their financial institution
  • Know when your requested data is ready for retrieval
  • Refresh a connection to get the latest data

Assumptions​

The following guide assumes that you've already:

  • Installed, configured, and deployed your self-hosted Universal Connect Widget, and have access to the URL for your self-hosted UCW instance.
  • Although optional, we encourage you to add security to restrict usage of your hosted UCW outside of your application.
  • The user has been created on your platform.

Workflow​

To retrieve data for an end user in the Universal Connect Widget, you must first establish a connection using the following workflow:

  1. Configure the widget URL with job type(s) and user id information.
  2. Load the widget for the end user to search for an institution, select that institution, and provide their credentials.
  3. Listen for the memberConnected postMessage.

1. Configure the Widget URL​

To setup the widget to accept data, insert the widget URL into an embedded iframe.

Example Usage <iframe src="www.your-widget-url.com/widget?jobTypes=accountOwner&userId=test-user-id" />

The widget iframe must include the following required parameters in the URL:

  • jobTypes: Combo jobs used to gather data. You may request multiple jobTypes using a comma separated list in the jobTypes query parameter.
    • accountNumber: Account numbers and routing/transit number information.
    • transactionHistory: A set timeframe of transaction history for an account.
    • accountOwner: Available customer data.
    • transactions: Latest transactions.
  • userId: The unique identifier of the user to make or refresh a connection with. The same userId must be used when making calls to the data endpoints.

You can optionally set the UCP ID of a specific institution using the institutionId parameter to skip search, send the user directly to the authorization step for the institution, and hide the back button.

Refresh an existing connection

To ensure you're retrieving the latest data for an existing connection, you must initiate its aggregation again by setting these additional parameters in the URL:

  • connectionId: The connection id of the connection to be refreshed.
  • aggregator: The aggregator of the connection to be refreshed.
  • institutionId: The UCP id of the institution. Setting this will skip search, send the user directly to the authorization step for the institution, and hide the back button.

Example Usage <iframe src="www.your-widget-url.com/widget?jobTypes=accountOwner&userId=test-user-id&connectionId=test-connection-id&aggregator=mx&institutionId=test-institution-id" />

Other parameters, listed in the OAS specification, are optional.

Authentication​

If you have enabled authentication in your environment configuration, the widget will require authorization.

Use the token endpoint to retrieve a one-time-use token to pass into the widget URL in the iframe. The server will set an authorization cookie that the widget will pass to the server for all requests.

For more information, see the /api/token endpoint in our OAS specification.

2. Load the Widget in Your Application​

Load the URL in your application or website. Then, the end user will interact with the widget. The widget handles the creation of a member (which represents the connection between a user and a financial institution) with the selected aggregator. At this point, the UCW facilitates the connection of that member with the aggregator and completes the job defined in the widget URL.

3. Listen for postMessage​

When a member has successfully been connected and the job is completed, the UCW will trigger a memberConnected postMessage. When your application identifies this postMessage, the widget is done and data is available for retrieval.

info

If you configured the widget to refresh a connection, you must still listen for this event to know when data is ready for retrieval.

An example of this event:

{
  "type": "connect/memberConnected",
  "metadata": {
    "aggregator": "sophtron",
    "member_guid": "MBR-345"
  }
}

Next Steps​

To retrieve data, see Fetch Data.