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 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 deposit switch.
• To reduce fraud, you can match the identity of the payroll account owner against your customer prior to allowing a deposit switch.

Implementation

Prerequisites

Link SDK version 2.0

In order to enable On Demand Updates, the Link SDK used in your application must be upgraded to version 2.0 or later. We recommend upgrading to the latest version for maximum conversion.

API and Webhook Version v2023-11-22

To use the latest functionality of On Demand Updates, you should upgrade to v2023-11-22. Breaking changes for each API version upgrade are listed in our breaking change list. Functionality of older versions can be found by using the API version dropdown in the top left corner of this page.

Create a Link token with account_id

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"
  }
}

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 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"
}

It is not necessary to send end_user_id when creating Link tokens for On Demand Updates because the account was associated with your user the first time they logged in.

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