Introduction

Direct Deposit Allocations (DDA) Monitoring alerts you to changes in a user's direct deposit allocations, such as increases and decreases in allocation amounts, the removal of an existing allocation, or the addition of a new allocation.

After a user logs into their payroll account through Link, Pinwheel establishes a persistent connection to the payroll provider. We'll pull direct deposit allocations data from this connection daily and proactively notify you of any changes.

Implementation

Step 1: Enable DDA Monitoring on Your Workspace

Please contact Pinwheel support so we can enable DDA Monitoring for your workspace. Once enabled, Pinwheel will automatically monitor changes to direct deposit allocations for any supported accounts.

Step 2: Subscribe to DDA Webhook Events

The direct_deposit_allocations.added webhook event will be sent whenever new data is available for a payroll account. We currently ignore changes to whitespacing and character casing.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Step 3: Retrieve New Direct Deposit Allocations Data

Using account_id from the direct_deposit_allocations.added webhook event, make a request to Get Direct Deposit Allocations to get the latest direct deposit allocations data for the account. The field data.updated_at is a timestamp of when the data last changed. The field meta.refreshed_at is a timestamp of when the payroll provider was last queried for changes.

Pinwheel always returns a snapshot of the latest direct deposit allocations data. To track these changes over time, you can store snapshots from Pinwheel when you receive them.

Step 4: Maintain Account Monitoring

Accounts can no longer be monitored due to various events such as session expiration, user settings changes, and platform updates. Pinwheel will send an account.monitoring_status.updated webhook event if our ability to monitor an account changes. To reconnect the account for DDA Monitoring, you should have the user re-authenticate via Link. We retrieve new data immediately after users reestablish account monitoring so you can provide updated information to users quickly.

Subscribe to Account Monitoring Status Webhook Events

The monitoring_status field in the account.added webhook event will indicate if a payroll account supports the ongoing integration for DDA Monitoring.

The account.monitoring_status.updated webhook event will be sent if this state changes. For example, the user_action_required value indicates that an account requires On Demand Updates to be triggered to re-establish monitoring.

You can register a webhook endpoint for these events as described in Subscribing to Webhook Events.

Re-Establish Monitoring

We're unable to retrieve data for an account that requires user action until the user has gone through Link again to reestablish monitoring.

You can initiate this user re-authentication flow in Link by creating a Link Token with the account_id field set. You should also provide org_name to personalize the Link flow for your brand. For example:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "account_id": "account_id of the account to reestablish monitoring for"
}

Once launched, Link will ask the user for the minimal amount of information necessary to reestablish monitoring. For example, if the user only needs to complete multi-factor authentication, we will drop them directly into that portion of the flow.

You can also set skip_intro_screen: true to disable the introductory screen shown in Link. See Customization in the Implementation Guide for more info.

You'll get an onLogin callback and receive an account.monitoring_status.updated webhook event when monitoring is successfully reestablished. We'll immediately trigger data refresh jobs once the login completes to get you the latest account data.

Extensions

Disable Monitoring for Individual Accounts

If you'd like to selectively disable all Monitoring for an individual account, use Disable Monitoring. Calling this will send an account.monitoring_status.updated webhook event with current_monitoring_status set to customer_disabled.

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