Introduction

There are cases where you may want to take repeated actions on a payroll account. We recognize that asking the user to log in 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.

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 use case 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.

{
  "event": "account.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true
  }
}

{
  "event": "identity.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload":{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "identity",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"
  }
}

Note: The end_user_id is an optional value you provide when creating a Link Token which we'll return in subsequent webhook events. See User Model for more information.

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.

A webhook event will be sent for indicating success or failure, if you're registered for it.

If performing an On Demand Update re-activated monitoring for an account a account.monitoring_status.updated webhook event will also be sent. You can learn more at Maintain Account Monitoring.

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.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "account_type": "checking",
  "routing_number": "07464755",
  "account_number": "193464372203",
  "required_jobs": [
    "direct_deposit_switch"
  ],
  "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65"
}

Note: it is not necessary to send end_user_id when creating Link tokens for On Demand Update requests.

Please contact [email protected] for access to our Developer Dashboard.