Account Connections

How users connect payroll accounts through Link.

Search#

Search is the default user experience in Link.

Step 1Step 2Step 3Step 4

The user searches from a general list of potential incomes sources. This includes employers, government entities, and payroll services.

Common customizations

• Excluding specific Items or Item categories (employers, gig platforms, payroll providers, or government benefits).
• Limiting search to Items that support deposit switching.

List#

As an alternative to search, Link also supports custom lists:

1. Create a custom list using Flows in Console.

2. Apply saved email/SMS template Flows when sending invites, or copy the ID of a saved embedded experience and add the following line to your embedded Link initialization:

   1flowId: "<ID of the embedded experience>"
   

Alternative:

1. Add an array of Item ID's directly within your Link initialization:

   1items: ["<ID of Item 1>", "<ID of Item 2>", "..."]
   

Direct login#

Directly connect users to a specific Item in Link, bypassing search entirely.

• The direct login method has the highest percentage of users that successfully connect a payroll account.
• Recommended whenever the user's employer or payroll provider is already known.

New connections#

1. Create a customized Flow in Console with "Direct login" selected in the Search and connect section.
2. You customizations will:
   • Automatically be applied to the Shareable URL after saving the Shareable URL Flow.
   • Be applied when sending invites if the saved Email/SMS Template Flow is selected from the dropdown.
   • Be applied when embedding Link by copying the ID of a saved Embedded Experience Flow and including it within the optional flowId initialization parameter in your Link initialization:

     1flowId: "<ID of the Flow>"
     

Alternative:

1. Add an items array to your embedded Link initialization with only one Item.

   1items: ["<ID of Item 1>"]
   

2. (Optional) If you are embedding Link and want to allow users to return to Link's full search experience from the login screen:
   • Create a "New Flow" in the Flows area of Console and select "Embedded Experience"
   • In the Search and connect section, select "Search" and adjust the search experience for your users
   • Next, in the same Search and connect section, select "Direct Login"
   • Enable the "Allow users to access full Search experience" toggle
   • Select one employer in the "Search to select income sources" selection box
     The Item you input in the items array (see below) will override this employer when Link is initialized.

   • Save the Flow and copy the Flow ID from the main Flows page
   • Add both an items array with only one Item, and the copied flowId string to your embedded Link initialization:

     1items: ["<ID of Item 1>"]
     2flowId: "<ID of the Flow>"
     

Existing connections#

• If you originally invited the user through Console's send invites feature, follow the steps in our Email/SMS Flows Guide for reconnecting existing users.

• If you are embedding Link, use the optional accountId initialization parameter and pass in the ID of the account.

  1accountId: "<ID of the account>"
  

Sample app#

If you are embedding Link, check out our Employer Search sample app (Demo) (Github) (Documentation) to see an example project that showcases the direct login method.

In the sample app, a simple employer search bar lets users search for their employer. After making a selection, the user is sent directly to that Item's login screen in Link.

Doc upload#

Directly connect users to the document upload screen in Link, bypassing the payroll account connection process. Visit our Document Upload Guide for more information.

Completing MFA#

Most payroll systems require multi-factor authentication (MFA) when a user logs in or takes action such as updating their direct deposit settings.

• The MFA process can be completed directly within Link.
• Link is designed to be persistent, meaning users can exit Link to retrieve their authentication information, and return to Link seamlessly without their session or the MFA process being interrupted.

Troubleshooting#

Connection pending#

Link will display "Connection pending" if an account connection is experiencing significant delays.

• Users will be able to exit Link or return to the search screen to connect additional accounts.
• You can monitor the account's connection status via the API, through the Connections section of Console, or by subscribing to the accounts.updated webhook. The account will have an initial status of connecting (API) or "Attempted" (Console) until the connection successfully completes or an account connection error occurs.

Expired user token#

If a user delays completing the MFA process for too long, they may encounter the expired_user_token Link error. Users tokens allow users to exit and return to Link without interruption, but to ensure security, user tokens expire after one hour.

To re-activate Link for the user, create a new user token and either:

• Re-initialize Link with the new user token.
• Pass the user token to the onTokenExpired callback.

Customizations#

For more information on customizing the connection process in Link, visit our Flows Guides.