GuidesAPI ReferenceChangelog
Log In
Hey! These docs are for version 2021-07-28, which is no longer officially supported. Click here for the latest version, 2023-11-22!

# Introduction

You can direct your users to make updates to their payroll account's direct deposit settings via Link. An example use case is to have your user create a new allocation to an account that you specify. Our platform currently supports 3 direct deposit functions.

## Direct Deposit Switch

Direct Deposit Switch enables users to update their direct deposit settings directly in your native experience. In just a few clicks, a user can change where they receive part or all of their paycheck. To take advantage of this flow, you will use our `direct_deposit_switch` job.

There are two ways your users can modify their direct deposit settings:

  1. **Full Switch**: Switches the "main" direct deposit account (also referred to as a "balance" or "remainder" account) to the account specified in the Link token.

  2. **Partial Switch**: Allows your user to specify the amount for a fixed amount allocation to the account specified in the Link token. Note: not all platforms support partial switches, in which case your user will only be given the full switch option.

The partial switch option can be disabled when creating a [Link Token](🔗) using the optional `disable_direct_deposit_splitting` parameter. This parameter is specific to `direct_deposit_switch` job.

## Paycheck-linked Loans

Paycheck-linked Loans allows your application to create a fixed amount direct deposit allocation to the account specified in the Link token. With Paycheck-linked Loans, borrowers can opt to have lenders collect payment directly from their paycheck. Here you will leverage our `direct_deposit_payment` job.

In this case, you will be responsible for telling us the amount of each payment. You will pass it to us via the `amount` parameter when creating a [Link Token](🔗). This parameter is specific to the `direct_deposit_payments` job.

The `direct_deposit_payment` job will set up a recurring payment to the specified account. In order to **stop** a payment, have the user go through the Link flow again with `amount: 0`.


If an allocation already exists for the account specified in the Link token, the allocation will be updated to the new amount. For example if the existing allocation is $500, and you run a `direct_deposit_payment` job with `amount` set to $400, the final allocation will be $400, not $900. This is true for both `direct_deposit_switch` and `direct_deposit_payment` jobs.

## Direct Deposit Allocations

Direct Deposit Allocations allows your application to retrieve the existing allocations of a user's payroll account. The `direct_deposit_allocations` job retrieves direct deposit configuration details including bank routing numbers, masked account numbers, amount, and priority of the existing allocations. See the full API reference [here](🔗) .

This job gives visibility into a users account, but does not edit the direct deposit settings. It can be used on its own or in conjunction with `direct_deposit_switch` or `direct_deposit_payment`.

# Implementation

## Step 1: Subscribe to Webhook Events

The most reliable method to receive notifications of when direct deposit changes are successfully made is to subscribe to webhook events. Depending on the job, subscribe to either `direct_deposit_switch.added`, `direct_deposit_payment.added`, or `direct_deposit_allocations.added` events:

The complete guide to webhooks can be found here [here](🔗).

## Step 2: Create a Link token

Create a [Link Token](🔗) specifying the jobs that your application requires using the `required_jobs` parameter. You can specify multiple jobs, but only one of either `direct_deposit_switch` or `direct_deposit_payment`. Please note that this parameter will update our search screen results. We will only return Platforms or Employers that support your `required_jobs`.

For the `direct_deposit_switch` and `direct_deposit_payments` jobs, you will also provide the direct deposit bank account details in the request: `account_type`, `routing_number`, and `account_number`. The token creation examples below display the required fields for each job. To see all configuration options, please see the [Link Token](🔗) reference, and for examples of how to leverage the customization parameters see the [Implementation Guide](🔗).

The response includes a short-lived `token` that expires after 15 minutes and a unique `id`. The `token` will be used to initialize Link. Persist the `id` in your database to query for [job results](🔗) later. More detail on storing identifiers can be found [here](🔗).

## Step 3: Initialize Link

Using the Link token that was created, open the Link modal in your client application. In addition to passing in the token, you can optionally pass in several callback handlers.

The `onSuccess` [callback](🔗) handler is executed on job success and contains metadata about the direct deposit job.

## Step 4: Responding to Webhook Events

After a user logs into their payroll account, an `account.added` webhook event is published. Using the `link_token_id` you persisted earlier, you can associate the account with the user who logged in with Link.

Depending on the job executed, a `direct_deposit_switch.added`, `direct_deposit_payment.added`, or `direct_deposit_allocations.added` webhook event is published. For example:

## Step 5: Retrieving Direct Deposit Allocations data (DDA only)

Upon receiving the relevant webhook event, you will make API requests to retrieve data from the [Get Direct Deposit Allocations](🔗) endpoint. **Do not utilize this endpoint to validate `direct_deposit_switch` job results, as jobs may still be processing.**



## Step 6: Query for Job Results

If your application never subscribed to webhook events, or your application server failed to handle the `direct_deposit_switch.added`, `direct_deposit_payment.added` or `direct_deposit_allocations.added` event, you can query the [Jobs](🔗) endpoint with the ID of the Link token used to initialize Link to fetch the results.