GuidesAPI ReferenceChangelog
Log In
Guides

Upgrade to Switch Kit from Deposit Switch

Suggest Edits

Overview

This guide explains how to upgrade to Switch Kit if you've already implemented Pinwheel's Deposit Switch.

Switch Kit allows users to perform an direct deposit switch and switch bills from their existing bank accounts and credit cards in the same session.

For the deposit switch flow, in just a few clicks, users can change where they receive part or all of their paycheck.

For the bill switching phase, the user connects to external bank accounts and credit cards, and Pinwheel automatically identifies which recurring bills & subscriptions are paid out of those accounts. The user can then perform an automated payment method switch to the card or bank account of their choice.

Prerequisites

Link SDK versions

In order to use Bill Navigator, the Link SDKs used in your application must be installed/upgraded to use the following minimum versions:

  • React (web): 3.3.x
  • iOS: 3.4.x
  • Android: 3.4.x
  • React Native: 3.5.x

We recommend upgrading to the latest version for maximum conversion.

API and Webhook Version v2025-07-08

The use of Switch Kit requires upgrading to version v2025-07-08 or higher. Breaking changes for each API version upgrade are listed in our breaking change list. Functionality of older versions can be found by using the API version dropdown in the top left corner of this page.

Upgrading to version v2025-07-08 is pretty simple. The only change associated with this version is in the Link Token creation API:

  • you must now add the solution field, whose value is "Switch Kit" for the purposes of this guide
  • required_jobs is now deprecated, and we have replaced that with features.

Please see Change Management for more details on API versioning, and see Step 2 below for more details on

Step 1: Set up access to external account transactions

In order to identify an end user's recurring bills and subscriptions, Pinwheel needs access to transaction data from external user accounts that those bills are paid out of. Pinwheel supports the Plaid banking aggregator for retrieving transaction data from external bank and credit card accounts.

If you have already incorporated Plaid into your existing solution, Pinwheel can get access to transaction data through your account as a Plaid partner. Plaid partners get access via Plaid Processor tokens, which are tightly scoped to allow a specific partner access to a specific data stream - in this case, transaction data. The benefits of this approach are that you will continue to own and manage the Plaid account, and in most cases if a user has already connected an external account elsewhere in your app, they don't need to reconnect it for Pinwheel. However, there is some extra development work to support this approach. To learn more about this integration path, see Integrating Pinwheel with your Plaid account.

If you do not already use Plaid, then we will simply use our own Plaid account to identify bills and subscriptions.

Step 2: Create a Pinwheel Link token for Switch Kit

Once the banking aggregator endpoints are implemented, you're ready to focus on the real-time Switch Kit user experience.

Start by creating a Link Token for Switch Kit. To do so, you'll need to provide the following:

  • The solution field must be set to "Switch Kit"
  • The features field must specify both "direct_deposit_switch" and "bill_switch"

For Bill Switch, you must also provide the debit card details for the bank account(s) that the user can choose to switch bills to in the cards object of the request.

See Link Token Creation docs for full details on required fields.

Here's an example Switch Kit link token:

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
  "solution": "Switch Kit",
  "features": ["direct_deposit_switch", "bill_switch"],
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "name": "My Checking Account",
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "cards": [
   {
      "card_name": "Card Name",
      "card_number": "12345678912345",
      "cvc": "111",
      "expiration_date": "05/29",
      "name_on_card": "Jane Doe",
      "card_zip_code": "12345",
      "billing_address": "123 Lane St",
      "billing_address2": "Apt 987",
      "city": "New York",
      "state": "NY"
    }
  ],
  // required for PreMatch; otherwise not needed
  "end_user": {
    "platform_matching": {
      "social_security_number": "123456789",
      "mobile_phone_number": "0123456789",
      "home_address_zip_code": "12345",
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1999-12-31",
      "email": "[email protected]"
    }
  },
}

Step 3: Initialize Link

Use the Link token to open the Link modal in your client application, the same as for Deposit Switch.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://cdn.getpinwheel.com/pinwheel-v3.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 success of both direct deposit switches and bill switches and contains metadata about each. It is important to note that multiple switches can be executed within a single Pinwheel link flow.

Example onSuccess result for a bill switch:

{  
  "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",  // user's account on the platform
  "platform_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256", // merchant (e.g. Netflix)
  "job": "bill_switch",  
  "params": {  
    "payment_method": {
      "type": "card",
      "card": {  
        "card_name": "Card Name",
        "card_num_last4": "2345",
      }  
    }  
  }  
}

Step 4: Respond to Webhook Events

Bill Switching

After a user successfully logs into the merchant, an account.added webhook event is published.

Using either the end_user_id or the link_token_id, you can associate the account with the user who logged in with Link. For 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": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "platform_id": "fce3eee0-285b-496f-9b36-30e976194736", // refers to the merchant (e.g. Netflix)
    "platform_name": "Netflix",
    "created_at": "2021-01-12T02:36:01.287148+00:00",
    "connected": true
  }
}

Once the user has completed the deposit switch, a bill_switch.added webhook event is published. For example:

{
  "event": "bill_switch.added",
  "event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
  "payload": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d", // users's account with the merchant
    "end_user_id": "my_user_12345",
    "link_token_id": "97f420ff-5d0a-46ee-9cfc-6f17d5d31256",
    "name": "bill_switch",
    "timestamp": "2021-01-12T02:36:01.287148+00:00",
    "outcome": "success",
    "params": {  
      "payment_method": {
        "type": "card",
        "card": {  
          "card_name": "Card Name",
          "card_num_last4": "2345",
        }  
      }  
    }  
  }
}

Step 5: Returning users

Pinwheel will use end_user_id passed in the Link token to keep track of returning users for recurring transaction monitoring and continued updating. Users who have previously connected an account will maintain their list of recurring transactions. For this use case a link token can be created exactly as above.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2025-07-08
x-api-secret: YOUR-API-SECRET
{
  "solution": "Switch Kit",
  "features": ["direct_deposit_switch", "bill_switch"],
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "allocation": {
    "targets": [
      {
        "name": "My Checking Account",
        "type": "checking",
        "routing_number": "07464755",
        "account_number": "193464372203"
      }
    ]
  },
  "cards": [
   {
      "card_name": "Card Name",
      "card_number": "12345678912345",
      "cvc": "111",
      "expiration_date": "05/29",
      "name_on_card": "Jane Doe",
      "card_zip_code": "12345",
      "billing_address": "123 Lane St",
      "billing_address2": "Apt 987",
      "city": "New York",
      "state": "NY"
    }
  ],
  // required for PreMatch; otherwise not needed
  "end_user": {
    "platform_matching": {
      "social_security_number": "123456789",
      "mobile_phone_number": "0123456789",
      "home_address_zip_code": "12345",
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1999-12-31",
      "email": "[email protected]"
    }
  },
}

Once you've created the Link token, follow Step 3 to initialize Link.

Updated 16 days ago