Direct Deposit

Introduction

Using Link, end-users can update their payroll account direct deposit settings to a bank account specified by your application or provide access to their existing direct deposit allocations. There are three direct deposit jobs supported on our platform.

Direct Deposit Switch

Direct Deposit Switch enables customers to update their direct deposit settings directly in your user experience. In just a few clicks, a user can change where they receive part or all of their paycheck. To complete a direct deposit switch 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 the 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 Pinwheel Link again and set 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_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 an end-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 an end-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:

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": [
    "direct_deposit_switch.added"
  ]
}

The complete guide to webhooks can be found here here.

Step 2: Create a Link token

Create a Link Tokens 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 Tokens reference, and for examples of how to leverage the customization parameters see the Implementation Guide.

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"
  ]
}
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",
  "amount": "50000",
  "required_jobs": [
    "direct_deposit_payment"
  ]
}
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "required_jobs": [
    "direct_deposit_allocations"
  ]
}

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 Jobs later. More detail on storing identifiers can be found here.

{
  "data": {
    "id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "expires": 1583428981,
    "mode": "production",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGci...cyldX8fILelb6A0XKmdWsXZHMH4W1o"
  }
}

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.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.getpinwheel.com/pinwheel-v2.3.js"></script>
    <script>
      Pinwheel.open({
        linkToken: "INSERT LINK TOKEN",
          onSuccess: (result) => {
            console.log("Job succeeded!");
        },
      });
    </script>
  </head>
  <body></body>
</html>

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.

{
  "event": "account.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "created_at": "2021-01-12T02:36:01.287148+00:00"
  }
}

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:

{
  "event": "direct_deposit_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "name": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "amount": null
    }
  }
}
{
  "event": "direct_deposit_payment.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "direct_deposit_payment",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "amount": 50000
    }
  }
}
{
  "event": "direct_deposit_allocations.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "direct_deposit_allocations",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"
  }
}

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.

Request

GET /v1/accounts/449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65/direct_deposit_allocations
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET

Response

{
    "data": {
        "id": "07814454-9163-40b5-9aaa-8a738fa7080b",
        "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
        "created_at": "2021-01-06T15:59:13.530178+00:00",
        "allocations": [
            {
                "account_name": "My Checking Account",
                "account_type": "checking",
                "allocation_type": "amount",
                "amount": 50000,
                "bank_name": "Chase",
                "currency": "USD",
                "masked_account_number": "53",
                "percentage": null,
                "priority": 1,
                "routing_number": "540622601"
            },
            {
                "account_name": "BoA Savings",
                "account_type": "savings",
                "allocation_type": "amount",
                "amount": 5000,
                "bank_name": "Bank of America",
                "currency": "USD",
                "masked_account_number": "3953",
                "percentage": null,
                "priority": 2,
                "routing_number": "021000322"
            },
            {
                "account_name": "Neobank",
                "account_type": "checking",
                "allocation_type": "remainder",
                "amount": null,
                "bank_name": null,
                "currency": "USD",
                "masked_account_number": "83",
                "percentage": null,
                "priority": 3,
                "routing_number": "434957982"
            }
        ]
    }
}

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.

Request

GET /v1/jobs?link_token_id=97f420ff-5d0a-46ee-9cfc-6f17d5d31256
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET

Response

{
  "meta": {
    "count": 1
  },
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
      "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
      "name": "direct_deposit_switch",
      "timestamp": "2021-01-12T02:36:01.287148+00:00",
      "outcome": "success",
      "params": {
        "amount": 50000
      }
    }
  ]
}

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


Did this page help you?