Deposit Switching

Redirect payouts to your bank.

After a user connects their payroll account through Link, they can be prompted to direct all or part of their pay to a specified bank account.

Platform support#

To check if a specific Item supports deposit switching:

• Console — In the Coverage tab, filter or search for Items where direct deposit switching (DDS) is supported. Selecting an individual Item will display additional information on the underlying platform's DDS capabilities.
• API - Filter Items using an Item filter or retrieve an individual Item by its ID and check the direct_deposit_switch object to see if deposit_account direct deposit switches are supported.

Embedded Link setup#

Our direct deposit switching (DDS) solution for embedded Link integrations is outlined below.

Structure a target deposit destination#

Target deposit destinations contain the bank account information details used in a deposit switch. The steps outlined in DDS flows show how to construct target deposit destinations for different use cases, such as receiving the entirety or a partial amount of the user's paycheck.

Create a deposit switch customization#

We recommend limiting searchable Items in Link to only those that support deposit switching:

1. Create a new customization using Flows in Console.
2. Enable the setting "Only show Link items that support direct deposit switching."
3. Add additional branding, messaging, or other customizations as needed.
4. After saving your customized Flow, pass in its ID via the flowId parameter in your Link initialization.

Initialize Link for DDS#

Use the optional ddsConfig Link initialization parameter to include an additional step for DDS after a user connects a payroll account.

1"ddsConfig": "<Your Encrypted Target Deposit Destination>"

For user privacy and security, sensitive banking information contained in target deposit destinations must be encrypted using the API's /target-deposit-destinations encryption endpoint before being passed to your Link initialization via the ddsConfig parameter when adding deposit switching flows.

Returning users#

Depending on your use case, you may want users to initially connect their payroll accounts through Link, return to your website or application for additional steps, and then return to Link for DDS.

To initiate the DDS process for a previously connected account:

1. Check the Item's platform supports DDS.

2. Include a ddsConfig in your Link initialization.

3. (Optional)

   

   If you want the returning user to immediately enter the deposit switch flow, include the accountId of the existing account in your Link initialization:

   1accountId: "<ID of the account>"
   

   

   If you want the returning user to directly enter the account status screen, where they can decide whether to begin a deposit switch, include the itemId related to the existing account in an items array to your Link initialization:

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

DDS flows — direct deposits#

Which DDS flow below you would like to perform determines what to include in your target deposit destination.

As mentioned above, target deposit destinations must then be encrypted via the API to protect sensitive banking information before being passed to the ddsConfig Link initialization parameter.

Entire paycheck#

• Users are able to restore and edit previous bank accounts, where they can then allocate part of their paycheck.
• Any unallocated remainder will be sent to the bank account specified in the target deposit destination.

• Users are able to restore and edit previous bank accounts, where they can then allocate part of their paycheck.
• Users can switch between dollar amount or percent allocations (when both types are supported by the underlying payroll platform).
• Any unallocated remainder will be sent to the bank account specified in the target deposit destination.

Partial paycheck#

We recommend including both percent_allocation and amount_allocation with whole number values in your target deposit destination objects used for partial paychecks. Because some payroll systems only support one format, either amount values or percent values, this maximizes the number of payroll systems that will support a deposit switch with your specifications.

If the underlying payroll system supports both amount and percent allocations and both are present in the target deposit destination, adding the following line to your target deposit destination will display an initial screen that allows the user to choose whether they prefer to see and edit their allocations in amounts or percentages:

1"allow_changing_allocation_type": true

You can also suggest an exact percentage or an exact amount exclusively, typically used in connection with loan repayments. In these cases, you would include only percent_allocation or only amount_allocation in your target deposit destination, respectively.

DDS flows — reference table#

The table below contains the required and optional parameters of target deposit destinations for different types of DDS flows.

1{
2    "ach_deposit_account": {
3        "bank_name": "<Any>",                           // optional
4        "routing_number": "<9 digit code>",             // *required*
5        "account_number": "<8 to 17 digit code>",       // *required*
6        "account_type": "checking" or "savings"         // *required*
7    },
8    "entire_paycheck": true,                            // *required*
9    "allow_restoring_destinations": true or false,      // optional
10    "allow_changing_allocation_type": true or false     // optional
11}

Adjust existing direct deposits#

In some situations, such as when a user's final loan payment is lower than the previous payments, you may want to adjust the pay allocations for the bank accounts that have already been added to the user's payroll system:

1. Include an ach_deposit_account object in your target deposit destination as you normally would, and add the new allocation settings you would like the user to accept.

   1{
   2    // Enter the bank account details of the existing allocation.
   3    "ach_deposit_account": {
   4        "bank_name": "YellowHorizon",
   5        "routing_number": "084101234",
   6        "account_number": "9483746361234",
   7        "account_type": "checking"
   8    },
   9    // Enter the new allocation values.
   10    "amount_allocation": {
   11        "value": "200",
   12        "min_value": "200",
   13        "max_value": "200"
   14    }
   15}
   

Remove a bank account#

Using the following steps, users can confirm through Link they would like to remove the designated bank account from their payroll system's direct deposit settings. The user will be able to adjust in Link how pay is allocated to their remaining bank accounts, as well as handle any multi-factor authentication (MFA) requests their payroll system requires.

1. Use the direct login method to directly connect the user to the relevant account.

2. Encrypt the following target deposit destination and pass it to the ddsConfig parameter in your Link initialization:

   1{
   2    "action": "remove-destination",
   3    "deposit_destination": "0181d8c4-31ed-3338-1859-05fc7f1ca501"   // Example ID.
   4}
   

ID's of each deposit_destination (bank account) can be found using the deposit destinations API endpoint.

Sandbox testing#

You can test your target deposit destinations and customizations with Flows in Console. This allows you to simulate a user's deposit switch experience and make any adjustments necessary:

1. Enable Sandbox mode in Console using the toggle.
2. Select a custom or demo Flow.
3. Open the Deposit switch setting below the preview screen.
4. Enable Request deposit switch and select Custom.
5. Copy and paste the encrypted target deposit destination (ddsConfig) you would like to test.

Deposit switch errors can also be simulated by creating unique error-encoded passwords via the API. See error testing in our Sandbox Testing Guide for more information.

Webhooks#

To monitor the progress of deposit switches, we recommend subscribing to our deposit destinations webhooks and direct deposit switches webhooks.

Status monitoring#

You can view the status of any bank account updates:

• Via the API, by checking the direct_deposit_switch object of an account.
• Via Console, by checking the same object using the JSON toggle on the individual user's page.

As a deposit switch progresses, the status value will progress from scanning to updating to success/error.

FAQ#