# Introduction
Users can make updates to their payroll account's direct deposit settings within your application with Pinwheel. After users connect their account, the settings can be updated with a new allocation or adjusted for an existing allocation to an account you specify.
# Use Cases
## Direct Deposit Switch
Direct Deposit Switch enables users to update their direct deposit settings directly in your native experience. In just a few clicks, users 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 types of allocations users can choose from:
**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.
**Partial Switch**: Allows users to switch a fixed amount or percentage to the account specified in the Link token. _Note: not all platforms support partial switches, in which case users will only be given the full switch option._
Fixed amount: allows users to specify a specific dollar amount from each paycheck (e.g. $500).
Percentage: allows users to allocate a proportion of each paycheck (e.g. 20%).
The partial switch options 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_switch` job and pass in the `amount` parameter when creating a [Link Token](🔗). When this parameter is passed in, users will not be able to edit the amount and is great for scenarios with a fixed payment amount.
The `direct_deposit_switch` 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`.
Note
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_switch` job with `amount` set to $400, the final allocation will be $400, not $900.
## 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 user's account, but does not edit the direct deposit settings.
# 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` or `direct_deposit_allocations.added` events:
The complete guide to webhooks can be found [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 Income and Employment jobs in addition to `direct_deposit_switch`. Please note that the search screen results will only return Platforms or Employers that support your `required_jobs`.
For the `direct_deposit_switch` job, 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 fields for each use case. 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](🔗).
Note: The `end_user_id` is your internal reference to the end user. See [User Model](🔗) for more information.
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` or `direct_deposit_allocations.added` webhook event is published. For example:
## Step 5: Query for Job Results
If your application never subscribed to webhook events, or your application server failed to handle the `direct_deposit_switch.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.
**Request**
**Response**
# On Demand Updates
There are cases where you may want to take different actions on a payroll account. We recognize that asking the user to login multiple times introduces friction, so we've added the ability to re-access the payroll account without needing the user to re-enter credentials.
_If the user has multi-factor authentication enabled on their account, user action may be required to complete the login step._
**Sample use cases**
To increase share of wallet, you can incentivize users to increase their direct deposit allocation after an initial direct deposit switch. Users may initially allocate a small amount into the account, but with the right incentives, they may be willing to increase that amount.
To help with underwriting decisions, you can leverage income and employment data before asking the user to complete a direct deposit switch.
To reduce fraud, you can match the identity of the payroll account owner against your customer prior to allowing a direct deposit switch.
**Implementation**
Enabling this functionality is similar to the way [standard Link tokens](🔗) are created today. When creating the Link token, pass in the `account_id` parameter from a prior [account.added](🔗) webhook event or from the `login` [client side event in Link](🔗). The `account_id` can be preserved and passed in any time you have it for a user.
Taking the 3rd example above where you match the identity of the payroll account owner against that of your user, you would first create the Link token with `identity` as the required job. Once your customer logs in and the job completes successfully, you will receive both the `accounts.added` and `identity.added` webhooks.
You can then query for `full_name`, `date_of_birth`, and `last_four_ssn` in addition to other fields to determine if the payroll account owner is the same person as your user. For more info, please see the Income & Employment guide [here](🔗).
Once you have successfully completed the verification, you can create another Link token to initiate the direct deposit switch using the same `account_id`. In doing so, we will attempt to bypass the need for the user to re-enter credentials. Note that there are some cases, eg. where MFA is enabled, where the user will have to take an action to complete login.
Note: it is not necessary to pass `end_user_id` when creating Link tokens for On Demand Updates. Webhooks returned from On Demand Updates will contain the `end_user_id` you specified when the user first connected to their payroll account.
Please contact [[email protected]](🔗) for access to our [Developer Dashboard](🔗).