Documentation

Getting StartedWelcomePlatform OverviewAPI SecretsJobsModesSandbox CredentialsLinkAPI Reference

Getting Started

Welcome

Welcome to Pinwheel, the fastest way to securely update direct deposits.

Pinwheel provides a set of SDKs and APIs that allow end-users to authorize 3rd party applications to update their direct deposits on payroll platforms such as ADP, Paychex, Gusto, and many more.

Platform Overview

An end to end integration with Pinwheel involves both server-side and client-side configurations. On the server-side, the application can interface with Pinwheel through a REST API service.

On the client-side, end-users interact with Link. Link provides a modal view that allows the end-user to select their payroll provider, authenticate with their login credentials, and consent to updating their direct deposit.

  1. Your server requests Pinwheel API to generate a short-lived token using your API secret and details about the direct deposit update.
  2. Using the token generated in step 1, your client initializes the Pinwheel SDK to launch the Link modal.
  3. The end user interfaces with the Link modal to choose their payroll provider, input their credentials, and consent to the direct deposit update. Simultaneously, Link sends user input via a web socket to the Pinwheel service which makes the direct deposit update in the user’s payroll provider.

API Secrets

Developers should first create a workspace at https://developer.getpinwheel.com to obtain their API secrets.

api_secret

This private identifier is used to authenticate with the Pinwheel API server. The API secret must be kept private and never exposed publicly on the client-side.

Jobs

There are two types of jobs supported on the platform:

direct_deposit_switch

Sets 100% of an end-user's direct deposit to the specified account. Most commonly used for switching a customer's direct deposits to a new bank account.

direct_deposit_payment

Sets a fixed amount of an end-user's direct deposit to the specified account. Most commonly used for scheduling loan payments directly from a borrower's paycheck.

Modes

There are three Pinwheel modes:

sandbox

Use sandbox mode to build and test your integration. In this mode, you use test credentials to authenticate with payroll platforms, but no actual updates are made to any payroll platform. The sandbox API server is available at https://sandbox.getpinwheel.com.

development

Development mode can be used to test your integration before going live to production. In this mode, you use real credentials to authenticate and direct deposits are actually updated on the payroll platform. The development API server is available at https://development.getpinwheel.com.

production

Use production mode to go live with your integration. Your end users will use their login credentials to authenticate and update direct deposits on payroll platforms. Note, in this environment, all successful direct deposit updates are billed. The production API server is available at https://api.getpinwheel.com.

Sandbox Credentials

In sandbox mode, you can use the following credentials to test Link:

FieldValue
Company IDcompany_good
Usernameuser_good *
Emailuser_good@example.com
Passwordpass_good
SSN123456789
Last 4 of SSN1234
MFA codemfa_code
What street did you grow up on?pinwheel drive

* For USPS ONLY: Username value is "12345678"

For providers that support optional multifactor authentication, use the following credentials to test the mfa flow:

FieldValue
Usernameuser_mfa
Emailuser_mfa@example.com

To test error handling, use the following credentials to trigger an exception:

FieldValue
Usernameuser_crash
Emailuser_crash@example.com