Introduction

This guide is for banking platforms that wish to add Pinwheel's Deposit Switch solution to their digital banking offering, enabling their customers to improve account primacy by offering instant direct deposit switching to their consumers.

Who is this guide for?

This is a technical implementation guide. Product managers and developers will need the information in this guide to integrate Pinwheel Deposit Switch into their digital banking platform.

Terms

For clarity, we'll define some terms we use in this guide:

• banking platform - A technology vendor used by banks and credit unions to outsource banking operations. The banking operations that are relevant for our purposes are digital banking interfaces such as online and mobile apps, including account opening flows.
• customer - The customer of a banking platform, typically a credit union or regional bank
• end user - For our purposes, a consumer using a customer's digital banking services.
• Link or Link modal - Pinwheel's user interface for enabling automatic direct deposit switches (and other products) that can be easily embedded within a digital banking app.
• Link SDK - Pinwheel's library that allows Link to be embedded within a customer's online and mobile banking app(s).
• workspace - This is the home or repository of all the data and configuration for a customer's implementation with Pinwheel. API keys, team configuration, and some customizations are stored in the workspace. As a banking platform, you will have your own workspace distinct from your customers' workspaces.

High level execution flow

1. The end user accesses their credit union or bank's digital banking app, which is a white-labeled version of the banking platform's digital banking app
2. They choose to make a direct deposit switch into the customer account.
3. The banking platform's app creates and opens the integrated Pinwheel component (known as Link).
4. Pinwheel's Link guides the user through the process of accessing their payroll platform and performs the direct deposit switch.

Implementation summary

Implementation for banking platforms is basically identical to how any of Pinwheel's customers implements Pinwheel products within their online/mobile apps, with a few minor differences that we'll call out below. You can get started with our public documentation:

• Getting Started - Implementation overview.
• Deposit Switch - Deposit Switch product overview.
• Platform Overview - Overview of how you'll work with the Pinwheel platform.
• API Overview - Overview of our API, when you're ready to make your first API call.
• Link - Overview of Link and Link SDK, which allows you to easily embed Pinwheel's Deposit Switch UI into your online/mobile apps.
• Pinwheel Prime - Implementation guide for enabling PreMatch, a credential-less flow that allows end-users to connect to their payroll platforms without requiring them to search for their payroll provider or remember their credentials, resulting in significantly higher conversion rates.
• Direct Deposit Forms - Implementation guide for enabling your customers to use form-based deposit switch as a fallback for when automated deposit switch isn't possible.

Implementation differences

The rest of this guide will simply call out the differences between an ordinary implementation, as described in the above docs, and what you will need to do to enable Pinwheel Deposit Switch for your customers.

In short, there are two differences that you'll need to keep in mind:

• Creating a Link token - passing a customer_id
• Link customization - customization per customer

Creating a Link token

When creating a Link token, which is used to initialize the Link modal, you'll need to let us know which customer you're creating it for. For this, you'll need to send us an immutable customer_id (typically a UUID), which is your internal ID of your customer that will not change. We will use this customer_id to look up your customer's Pinwheel workspace and associate the returned Link token with them. This allows us to bill the customer properly, as well as enable some customizations. When onboarding one of your customers to Pinwheel, you'll send us this customer_id, which will allow us to perform the lookup to the customer when creating link tokens.

When creating a Link token, you'll pass the customer_id by adding it to the tags object in the request body. See Link token for the API reference page.

Here's an example Link token request that includes customer_id in the tags object:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-Api-Secret: YOUR-API-SECRET
Pinwheel-Version: 2023-11-22
{
  "org_name": "CUSTOMER NAME",
  // required - an immutable identifier for the end user - must not be PII
  // note: the end_user_id used here should also be known by your customers.
  // See "Specifying end user data" section below.
  "end_user_id": "customer_user_12345",
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "required_jobs": [
    "direct_deposit_switch"
  ],
  // required for banking platform implementations!
  "tags": {
    "customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"
  },
  // provide end-user PII here to enable credential-less PreMatch flow (see below)
  // See "Specifying end user data" section below.
  "end_user": {
    "platform_matching": {
      "date_of_birth": "2000-01-01",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "home_address_zip_code": "12345",
      "mobile_phone_number": "1234567890",
      "social_security_number": "123456789"
    }
  }
}

Specifying end user data

Two things to keep in mind regarding specifying end user data:

• end_user_id: This is the immutable internal ID of the end user of your customer's digital banking app, and is required. Do not use PII for this value. See the above link token request example.
  • Note: It's important that the end_user_id you choose is also known by your customers, so that they can resolve the end_user_id to an account holder. For instance, customers can download user-level reports from their Pinwheel customer dashboard, and these reports reference only the end_user_id. They contain no PII or any other way to resolve data to specific end users.
• end_user.platform_matching: if you provide the end-user's PII, we will use that data securely to find their account on the payroll platforms that participate in our PreMatch network. If a match is found, the end user will only need to respond to an MFA challenge to the provided mobile_phone_number or email to complete the connection to the payroll platform. See Pinwheel Prime for more.

For more information on any of the other data in this example, see Link token.

Link customization

Our customization options are described in our Link overview. Unlike a typical Pinwheel customer, you will potentially make Deposit Switch requests on behalf of many customers, each with their own brand and design considerations and need for customization.

Some of our customization options involve configurations that are specified when the Link token is created - see the next section for an example. For these customizations, you'll need to specify these options on every Link token request.

Other customizations are configured in the customer's workspace and are typically decided and configured during the onboarding phase for the customer. See Going live with a customer below for more. For these customizations, Pinwheel owns the work - there is nothing for you to do.

Required customizations

One required customization involves specifying the name of the customer's organization or app for display in the Link modal. The org_name parameter in the link token request is used in the intro screen of the Link modal.

For example, the following Link token request will result in the following intro screen:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "Acme Credit Union",
  "required_jobs": ["direct_deposit_switch"],
  "end_user_id": "customer_user_12345",
  tags: {"customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"},
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  // provide end-user PII here to enable credential-less Prime flow
  "end_user": {
    "platform_matching": {
      "date_of_birth": "2000-01-01",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "home_address_zip_code": "12345",
      "mobile_phone_number": "1234567890",
      "social_security_number": "123456789"
    }
  }  
}

Testing

The process for creating link tokens is a bit different for banking platforms, as described above. Banking platforms need to specify a customer_id key/value pair in the tags block of the link token request. However, during the implementation process, no customers have been onboarded to Pinwheel yet, so how can you test creating link tokens?

As part of creating your workspace, we automatically create a Sandbox (fake) customer for you that is associated with your workspace. The name of this fake customer is "Test Credit Union". When creating link tokens, the customer_id associated with this customer is test-credit-union.

Here's an example link token creation request payload using this customer:

{
  "org_name": "Test Credit Union",
  "required_jobs": ["direct_deposit_switch"],
  "end_user_id": "customer_user_12345",
  "tags": {"customer_id": "test-credit-union"},
  "allocation": {
    "targets": [
      {
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  // provide end-user PII here to enable credential-less Prime flow
  // Note: the example below is actual sandbox PII that simulates a
  // user that is eligible for the Workday payroll platform.
  "end_user": {
    "platform_matching": {
      "date_of_birth": "<any DOB>",
      "email": "<any email>",
      "first_name": "user",
      "last_name": "osv",
      "home_address_zip_code": "<any zipcode>",
      "mobile_phone_number": "<any phone number>",
      "social_security_number": "<any ssn>"
    }
  }    
}

Using the Console to test

Pinwheel provides a Console in our Dashboard, which is a great way to familiarize yourself with Link. The Console will allow you to create Link tokens and launch Pinwheel Link. You can see how different Link token configurations affect the front end UI, and test different front-end workflows. In Sandbox, when providing credentials (as the end-user) to a payroll platform, use our sandbox test credentials which can be found in our Sandbox doc. Live credentials will not work in Sandbox.

You can also test Pinwheel Prime credential-less flows by passing sandbox PII in the end_user.platform_matching object (e.g. in the JSON above). More examples of Prime PII that simulate different Prime experiences can be found in the Prime section of the Sandbox

Console for banking platforms

We've tailored the Console for banking platform implementers/testers, because creating link tokens is a bit different from the ordinary customer implementation. Specifically, in place of the usual "org_name" text field, we've replaced it with a drop-down that contains any customers that have been onboarded to Pinwheel. Naturally, during the implementation phase, you won't have onboarded any customers yet, so this will contain only the Test Credit Union customer. Once the implementation is live and customers have been onboarded, they will appear in this drop-down.

We also pre-populate required_jobs with the direct_deposit_switch job for you, as well as some fake target account data. As a result, once you select the Test Credit Union customer, you can create a link token right away, and launch Link.

Viewing the link token creation request

As you work within the Console to create a link token, you can view what the actual request will look like by clicking the "Show Request JSON" button at the bottom of the form. This opens a view of a helpful JSON object that can be helpful in testing and debugging your implementation.

Going live with a customer

Once your implementation has been thoroughly tested against the fake Test Credit Union in sandbox, you're ready to onboard a customer.

The onboarding flow involves the following steps: