Skip to main content
Version: 2.0.0

Connect Accounts

Objectives
  • 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.
  • A 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.
  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. Create the Widget URL​

Use the POST /widgetUrl endpoint to create a widget URL with your configuration.

Required fields:

  • jobTypes: Comma-separated jobs to gather data. Available types:
    • accountNumber: Account numbers and routing/transit numbers
    • transactionHistory: Set timeframe of transaction history
    • accountOwner: Available customer data
    • transactions: Latest transactions
  • userId: The unique identifier of the user. Must match when calling data endpoints
  • targetOrigin: Your application's origin URL (required for security)

Optional fields:

  • institutionId: UCP ID of a specific institution (skips search and goes directly to authorization)
  • connectionId: For refreshing an existing connection
  • aggregator: The aggregator to use (required when refreshing)

Other parameters are listed in the API reference.

Repair a Connection

To ensure you're retrieving the latest data for an existing connection, include the connectionId in your POST request to /widgetUrl:

This safely passes the sensitive connectionId to the server and handles the refresh connection scenario.

2. Load the Widget in Your Application​

Use the widgetUrl returned from the /widgetUrl endpoint as the src of your iframe.

Example Usage

<iframe src="https://your-widget-url.com/widget?token=abc-123-efg-456-hijk" />

The widget handles the creation of a connection between a user and their financial institution with the selected aggregator and completes the job(s) defined in your request.

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, you can close the widget and retrieve the data.

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": {
    "ucpInstitutionId": "plaidbank",
    "connectionId": "access-sandbox-111111-22222-33333-44444-555555",
    "aggregatorUserId": "tester301",
    "aggregator": "plaid_sandbox"
  }
}

Next Steps​

To learn how retrieve the data once a member is successfully connected, see Fetching Data.