GuidesAPI ReferenceChangelog
Log In
Hey! These docs are for version 2021-07-28, which is no longer officially supported. Click here for the latest version, 2023-07-18!

Direct Deposit

Suggest Edits

Introduction

You can direct your users to make updates to their payroll account's direct deposit settings via Link. An example use case is to have your user create a new allocation to an account that you specify. Our platform currently supports 3 direct deposit functions.

Direct Deposit Switch

Direct Deposit Switch enables users to update their direct deposit settings directly in your native experience. In just a few clicks, a user 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 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 each 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 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_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 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 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 Token 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 Token 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 job results later. More detail on storing identifiers can be found here.

{
  "data": {
    "id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "expires": "2021-01-09T02:52:26+00:00",
    "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",
    "connected": true
  }
}

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. Do not utilize this endpoint to validate direct_deposit_switch job results, as jobs may still be processing.

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

Updated over 1 year ago