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 Link Flow in Console with deep-linking enabled.
2. Apply saved email/SMS template customizations when sending invites, or copy the ID of a saved embedded experience add it via the flowId initialization parameter.

Alternative:

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

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

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.