Introduction to Deposit Switch (beta)

Explore API

Deposit Switch (beta) makes it easy for users to change which bank account receives their pay. Using Deposit Switch, consumers can update their payroll direct deposit to point to a new bank account. Within your app, the user will first select to switch their direct deposit to the bank account they have with you. Your app will then display a list of the user's accounts, prompting the user to select the account to which they want to switch their direct deposit. Finally, Link will open and enable the user to authenticate with their payroll provider to confirm the switch.

Deposit Switch can be used with or without a Plaid Exchange integration.

1. In your app or website, the user selects to update their direct deposit to the bank account they have with you.
2. (Optional) You ask the user who their employer is, to verify that they are supported by Deposit Switch.
3. (Optional) Your app or website displays a list of the user's accounts. The user then selects which account they want to switch their direct deposit to.
4. Plaid Link opens, where the user searches by employer or selects their payroll provider, authenticates, and confirms they would like to switch their paycheck to be deposited in the target account.
5. You present a success screen, indicating that the paycheck deposit has been switched to your bank.

Customers not using Plaid Exchange can integrate with Deposit Switch by using the /deposit_switch/alt/create endpoint.

Deposit Switch relies on Link for authentication. Deposit Switch requires that Link be initialized with a Link token configured with ['deposit_switch'] as the product.

1. Create a deposit switch by calling /deposit_switch/alt/create. As the parameters, you will need to provide information about the account being switched to, including its account number and routing number, as well as information about the account owner, including their name and contact information. The response to this call will include a deposit switch ID.

2. Call the /link/token/create endpoint to create a Link token from the deposit switch ID generated in the previous step. Note that the products array must be exactly ['deposit_switch']. Use this newly created token to enable the user to go through Link.

3. Via Link, the user will find their payroll provider, authenticate with their credentials, and confirm the switch.

4. Confirm the deposit switch status and details by calling the /deposit_switch/get endpoint.

1{
2  "target_item_id": "MdRAkq1QikR3BLjDyMfMkVpqLmEm1VR7bX5hE",
3  "target_account_id": "bX5hEMdRAkq1QikR3BLjDyMfMkVpqLmEm1VR7",
4  "deposit_switch_id": "LjDyMfMkVpqLmEm1VR7bQikR3BX5hEMdRAkq1",
5  "state": "completed",
6  "date_created": "2019-11-01",
7  "date_completed": "2019-11-01",
8  "account_has_multiple_allocations": true,
9  "is_allocated_remainder": false,
10  "percent_allocated": 50,
11  "amount_allocated": null,
12  "request_id": "lMjeOeu9X1VUh1F"
13}

Note that the state field in the above object is "completed", which indicates that the target account has been successfully switched to receive direct deposits. If /deposit_switch/get is called prior to the switch being completed, the state field will be "initialized".

Plaid Exchange is used to import user accounts into Plaid's system as well as to identify the account to which the user wishes to switch their direct deposit. Contact your Plaid Account Manager with questions about your Plaid Exchange integration.

Deposit Switch also requires that you have access to the /item/import endpoint. To acquire access to /item/import, contact your Plaid Account Manager. Note that this endpoint does not handle MFA responses.

Deposit Switch relies on Link for authentication. Deposit Switch requires that Link be initialized with a Link token configured with ['deposit_switch'] as the product.

1. (Optional) present the end user with a data entry field to obtain the name of their employer, then use /employers/search to confirm whether their employer is supported by Deposit Switch. If the employer is not supported, route the user to an alternative flow.

2. Provide Plaid with the new account's authentication information via the /item/import endpoint. The response will include an access token that can be used to create a deposit switch.

3. Call the /accounts/get endpoint to retrieve available account IDs for the Item imported in the previous step.

4. Using the access token and account ID obtained from the previous steps, create a deposit switch by calling /deposit_switch/create. The response to this call will include a deposit switch ID.

5. Call the /link/token/create endpoint to create a Link token from the deposit switch ID generated in the previous step. Note that the products array must be exactly ['deposit_switch']. Use this newly created token to enable the user to go through Link.

6. Via Link, the user will find their payroll provider, authenticate with their credentials, and confirm the switch.

7. Confirm the deposit switch status and details by calling the /deposit_switch/get endpoint.

1{
2  "target_item_id": "MdRAkq1QikR3BLjDyMfMkVpqLmEm1VR7bX5hE",
3  "target_account_id": "bX5hEMdRAkq1QikR3BLjDyMfMkVpqLmEm1VR7",
4  "deposit_switch_id": "LjDyMfMkVpqLmEm1VR7bQikR3BX5hEMdRAkq1",
5  "state": "completed",
6  "date_created": "2019-11-01",
7  "date_completed": "2019-11-01",
8  "account_has_multiple_allocations": true,
9  "is_allocated_remainder": false,
10  "percent_allocated": 50,
11  "amount_allocated": null,
12  "request_id": "lMjeOeu9X1VUh1F"
13}

Note that the state field in the above object is "completed", which indicates that the target account has been successfully switched to receive direct deposits. If /deposit_switch/get is called prior to the switch being completed, the state field will be "initialized".

Testing Deposit Switch may require the creation of Items via Plaid Exchange as well as access to payroll accounts, which cannot be generated solely for testing purposes.

In a Sandbox environment, a call to /item/import will resolve to the Plaid Sandbox institution, so your Sandbox account and routing number should be used in the target account within the Deposit Switch flow. user_good and pass_good should be provided for user_id and auth_token respectively. Any payroll provider institution that is selected will also require Sandbox credentials (user_good and pass_good).

In a Development or Production environment, a call to /item/import will create Development or Production Items for your configured production environment. If you want /item/import to resolve to your testing environment, reach out to your Plaid point of contact.

Instead of testing Switch with an employee's account, you may test your Deposit Switch integration with a dummy payroll provider. To do so, test with "Flexible Platypus Payroll Management" (ins_118484) and credentials user_good, pass_good, and January 15, 2000. "Flexible Platypus Payroll Management" is only available in Sandbox and Development environments.

To learn more about building with Deposit Switch, visit the API Reference. For a list of possible error codes associated with Deposit Switch, see Deposit Switch errors.