Overview

Many of our banking platform partners are either already reselling Pinwheel services such as Deposit Switch, or are planning to do so in the near term. Unfortunately, our existing model for banking platforms - the one you're using, if you're reading this has two problems:

It does not distinguish between resold customers and customers who contract through Pinwheel.
Customer attribution happens via a schema-less tags construct specified during link token creation.

To address this, we created the Partnership Model, which distinguishes between resold customers and Pinwheel-contracted customers and makes customer attribution a first-class citizen of the link token via the new partner_customer_id field. The Partnership Model is already live and in use by several partners. We are deprecating the current model, and over time, moving all our partners to the Partnership Model.

This technical migration guide is for our banking platform partners who've already built an implementation for Direct Deposit Switch or Switch Kit products. It describes the migration process, including the minor technical changes to your implementation that are required to move to the new Partnership Model.

Do all banking platforms need to make this change?

The Partnership Model accommodates all banking platform partners, whether they resell or not. Supporting two different partnership models when one of them would suffice adds operational complexity and places a burden on our ability to support you, so we are deprecating the current model to keep things as simple as possible.

There is plenty of time to perform the migration, though you'll want to make the change before we sunset the current model.

When will Pinwheel sunset the current model?

The current model will be sunsetted on July 1, 2027. After that date, creating a link token using tags.customer_id will result in an error.

Prerequisites

Before beginning the migration, reach out to your Pinwheel partnerships contact. The first step is to establish timelines around when the migration will start and end.

Before starting work on the required changes, we will enable a special migration mode for your workspace that accepts either the existing model or the Partnership Model without error.

The only technical prerequisite is that you're required to use version v2025-07-08 or later of the API. See Migrating to API version 2025-07-08 if you're currently using an older version of the API.

Performing the Migration

The migration process will follow this outline:

Pinwheel enables migration mode for your workspace. What this does:
1. Link tokens can be created using either model.
2. Webhooks contain both attributions.
Pinwheel designates your workspace a Partnership Model workspace.
You will make the minor technical changes required (see details below).
Pinwheel validates that the technical changes are complete.
Pinwheel disables migration mode.
1. Now, link tokens created using the old tags.customer_id will fail
2. Webhook attributions will no longer contain tags.customer_id.

Required Technical Changes

Link Token Creation

The first change required is in link token creation.

Banking platform partners using the current model specify the customer during link token creation by embedded customer_id as a field of the tags object. To specify the customer using the Partnership Model, partners instead use the first-class partner_customer_id.

You will continue to use the same values for partner_customer_id that you used for tags.customer_id.

Note: while in migration mode, either means of creating the link token will work.

Example:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-Api-Secret: YOUR-API-SECRET
Pinwheel-Version: 2025-07-08
{
  "org_name": "Acme Credit Union",
  "solution": "Deposit Switch",
  "features": [
    "direct_deposit_switch"
  ],
  "end_user_id": "customer_user_12345",

  // existing model: tags.customer_id
  "tags": {
    "customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"
  },

  // other data
  ...
}

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-Api-Secret: YOUR-API-SECRET
Pinwheel-Version: 2025-07-08
{
  "org_name": "Acme Credit Union",
  "solution": "Deposit Switch",
  "features": [
    "direct_deposit_switch"
  ],
  "end_user_id": "customer_user_12345",

  // Partnership Model: partner_customer_id
  "partner_customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980",

  // other data
  ...
}

Webhook Attribution

The second change is webhook processing, and using the correct customer attribution in the webhook payload.

Banking platform partners using the current model receive webhooks with the tags object provided in the webhook payload, which includes the customer_id and any other fields that were specified in the tags object when the link token was created. Using the Partnership Model, the webhook payload instead contains partner_customer_id as a first-class field in the payload, matching how the link token is created.

Note: while in migration mode, you will receive both attributions, regardless of how the link token was created. This allows you the flexibility to implement your webhook processing changes without any dependency on the link token changes. Once migration mode is turned off, the customer_id field in the tags block will no longer be sent.

Example:

{
  "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": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "platform_name": "Justworks",
    "platform_type": "payroll",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active",

    // existing model: tags.customer_id
    "tags": {
      "customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"
    }
  }
}

{
  "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": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "platform_name": "Justworks",
    "platform_type": "payroll",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active",

    // Partnership Model: partner_customer_id
    "partner_customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"
  }
}

{
  "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": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
    "platform_name": "Justworks",
    "platform_type": "payroll",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true,
    "monitoring_status": "active",

    // During migration mode, you'll receive both:
    "partner_customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980",
    "tags": {
      "customer_id": "03a1ae36-7272-488e-8ba7-dc489790a980"
    }
  }
}