Account Connections

​

Search

• Step 1
• Step 2
• Step 3
• Step 4

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

If the user cannot find their source of income from this general list, they will be prompted to search from a list of only payroll providers that service multiple employers.

These payroll providers are searchable in step 1, but we have found narrowing the search focus to payroll providers improves the connection success rate for users.

If the user successfully finds their source of income, they are taken to its respective login screen. From the login screen, the user can enter their login credentials to connect their account.

• If the user cannot remember their login credentials, the login screen provides a link to the platform’s username/password reset process.
• Each login screen is tailored to match the input fields used by the underlying payroll system. For example, some systems require a username and password, others an email and password, while others may use SSO methods to login. You can preview the login screen for any employer or payroll system in Console using Flows.

If the user cannot ultimately find their source of income, they are asked to submit a response form and list their employers or payroll providers.

​

Common customizations

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

Note on groupings:

Certain Items are used to “group” other individual Items, and may or may not support payroll connections themselves. These Items will have a Grouping tag in Console’s Coverage page.Groupings can be:

• Payroll providers that support login credentials for multiple employers.
• Employers that utilize multiple payroll providers.
• Common employers such as franchises that allow individual locations or regions to independently choose third-party payroll systems for their employees.

When a user selects a grouping that does not directly support payroll connections, a dropdown menu of individual Items that do support payroll connections and are related to the particular grouping are shown.

​

List

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:
   Report incorrect code

   Copy

   Ask AI

   flowId: "<ID of the embedded experience>"
   

1. Add an array of Item ID’s directly within your Link initialization:
   Report incorrect code

   Copy

   Ask AI

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

​

Direct login

• 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:
  Report incorrect code

  Copy

  Ask AI

  flowId: "<ID of the Flow>"
  

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

   Copy

   Ask AI

   items: ["<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

• 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:
  Report incorrect code

  Copy

  Ask AI

  items: ["<ID of Item 1>"]
  flowId: "<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.
  Report incorrect code

  Copy

  Ask AI

  accountId: "<ID of the account>"
  

​

Sample app

​

Doc upload

​

Completing MFA

• 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

• 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

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

​

Customizations