Technical Implementation

This guide explains how to perform a Deposit Switch. For an overview of concepts in the Pinwheel system that are referenced in this doc, review the Platform Overview.

Step 1: Subscribe to Webhook Events

In order to receive timely notifications of when changes to your user's direct deposit settings are made, we recommend that you subscribe to webhook events. You can subscribe to either or both direct_deposit_switch.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 direct deposit webhooks can be found here.

Step 2: Create a Link token

Start by creating a Link Token with the jobs that your application requires specified within the required_jobs parameter. You are also able to combine Income & Employment jobs, if you are interested in pulling down payroll data within the same session. Please note that our search experience filters out results based on required_jobs, ie. we will only return Platforms and Employers that meet your requirements.

For direct_deposit_switch, you will need to provide details for the target bank account that you wish the user to switch their direct deposit to. Each one will need to include type, account_number, and routing_number.

You are able to pass in multiple accounts per Link token. If you do so, the user will be able to decide which one between them that they want to switch into. We recommend that you pass in name when utilizing multiple accounts. This field will be displayed within the Pinwheel Link UI, and returned in the direct_deposit_switch.added webhook so that you're able to determine the selected account.

The token creation examples below display the fields for each use case. To see all configuration options, please see the Link Token reference. For examples of how to leverage the customization parameters, please 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",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "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",
  "end_user_id": "my_user_12345",
  "allocation": {
    "type": "amount",
    "value": "50000",
    "targets": [
      {
        "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",
  "end_user_id": "my_user_12345",
  "required_jobs": [
    "direct_deposit_allocations"
  ]
}

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "required_jobs": [
    "direct_deposit_switch"
  ],
 "disable_direct_deposit_splitting": true
}

Note: The end_user_id is your internal reference to the user. While this field is optional, providing it can simplify your integration and improve coverage. Please see User Model for more information.

The response includes a short-lived token that expires after one hour 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. Note that you should treat the token as opaque and that you should not use or rely on the information encoded in the token as it could change at any time.

{
  "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 pass in several optional 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 successfully logs into their payroll account, an account.added webhook event is published. Using the link_token_id, 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",
    "end_user_id": "my_user_12345",
    "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 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",
    "end_user_id": "my_user_12345",
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "name": "direct_deposit_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {
      "action": "partial_switch",
      "allocation": {
        "type": "remainder",
        "target": {
          "account_type": "checking"
        }
      }
    }
  }
}

{
  "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",
    "end_user_id": "my_user_12345",
    "link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
    "name": "direct_deposit_allocations",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success"
  }
}

If the automated direct deposit job is unsuccessful and the user elects to complete a direct deposit form, you can listen for the following Link events to determine their progress. For more information on Link events, please click here.

name	description	payload
`dd_form_begin`	User has elected to begin the process of creating a direct deposit form	`{}`
`dd_form_create`	User has successfully created the form	`{ url: string }`
`dd_form_download`	User has clicked "share" or "download"	`{}`

Step 5: Query for Job Results

If you are not subscribed to webhook events, or there was an issue handling thedirect_deposit_switch.added or direct_deposit_allocations.added events, you can fetch job results by querying the Jobs endpoint with the link_token_id pertaining to a specific user.

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": {
        "action": "partial_switch",
        "allocation": {
          "type": "amount",
          "value": 5400,
          "target": {
            "account_type": "checking"
          }
        }
      }
    }
  ]
}

Step 6: Performing an On Demand Update

There may be cases where you wish to have your user perform another direct deposit switch. We recognize that asking the user to login multiple times introduces friction, so we've added the ability to re-access the payroll account without needing the user to re-enter credentials.

Enabling this functionality is similar to the way standard Link tokens are created. 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.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "allocation": {
    "targets": [
      {
        "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 pass end_user_id when creating Link tokens for On Demand Updates, as the information is persisted from the initial connection.

Once you've created the Link token, follow Step 3 to initialize Link. When the user is presented with the Pinwheel Link flow, they will be directed to the payroll platform associated with their account, bypassing login if possible.

Note: If multi-factor authentication enabled on their account, user action may be required to complete the login step.

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