GuidesAPI ReferenceChangelog
Log In
Guides

Jack Henry/Banno Onboarding Guide - Switch Kit

Suggest Edits

Introduction

This guide is for financial institutions ready to integrate the Pinwheel Switch Kit Plugin into their Jack Henry/Banno online banking app. This plugin (henceforth called the Pinwheel plugin) unlocks instant direct-deposit and bill switching for all users of your online banking app. See our Switch Kit product page for more.

Getting the Pinwheel plugin installed on your Banno dashboard involves the following key actions:

  1. Verify your FI is eligible for Switch Kit
  2. Get set up with Pinwheel
  3. Add Pinwheel as an External App in Banno People
  4. Configure the Banno application in Pinwheel’s Customer Dashboard
  5. Create the Pinwheel plugin in Banno People
  6. Test the plugin in sandbox mode
  7. Enable it in production mode

The steps below walk you through each of these in detail.

1. Verify your FI is eligible for Switch Kit

For the bill-switching part of Switch Kit, account holders switch the payment method for their recurring bills and subscriptions to a debit/credit card associated with an account at your FI.

In order to facilitate this, the Pinwheel plugin accesses debit/credit card data through Banno APIs. As a result, FIs eligible for Switch Kit must use certain JH/Banno offerings, as detailed below.

Debit Cards

In order to surface debit cards for use with Switch Kit, Banno’s basic card management feature must be enabled.

Note that Banno supports configuration options to look up cards for a user by their CIF (i.e., by user) or by account number. If cards are returned by account number, then it may be possible for the user to do a bill switch using a card owned by someone else associated with the account (e.g. for joint accounts). As a result, we recommend configuring debit cards to be looked up by CIF, but this is up to the FI.

Credit Cards

Traditional Banks

For traditional banks that offer credit cards through Jack Henry's Full-Service Credit Cards, the FI must also integrate with Banno's advanced card controls (aka MyCardRules), in order for those credit cards to be eligible for use with Switch Kit.

Note that non-Jack-Henry credit cards (aka Miscellaneous Accounts), are not eligible to be used for bill switching.

Credit Unions

Credit unions must have Banno’s basic card management feature enabled, same as for debit cards. This supports in-house credit cards.

Credit cards issued via PSCU but stored in an external loan record and fully integrated into Banno (including transactions) are also able to be used within the plugin.

Onboarding requirements for credit cards

Due to PCI requirements, getting access to full credit card data requires granting the Pinwheel plugin access to an additional API, and there is some extra setup involved. See Jack Henry/Banno Onboarding Guide - jXchange APIs for details.

2. Get set up with Pinwheel

This guide assumes you already have access to our Customer Dashboard. If you don’t have this set up yet, please contact us at [email protected] and let us know you're a Jack Henry/Banno customer.

3. Add Pinwheel as an External App in Banno People

Create the Application

Open the Banno People app. Navigate to the External Applications page, and create a new application that will represent the Pinwheel plugin. In the form that opens up, you'll enter the following values:

For the Name, enter "Pinwheel Switch Kit".

For the Redirect URIs, use a fake value for now - e.g. https://example.com - we'll update it in the next step.

Click Save.

Configure the Application

Re-open your newly created app (by way of the External Applications page). Your client ID should now be viewable, as well as the hidden client secret, which you can unhide.

Redirect URIs

Next, you'll enter two Redirect URIs. For this step, you'll need the Client ID visible at the top of the screen.

The first Redirect URI is https://app.getpinwheel.com/banno/{client_id}/card. But instead of {client_id}, you'll replace it with your Client ID.

For example, if your Client ID is 4d89fac0-1123-430b-ac7c-a44bca71238c, then the redirect URI will be https://app.getpinwheel.com/banno/4d89fac0-1123-430b-ac7c-a44bca71238c/card.

Click the Add button to the right of the first Redirect URI to save it, which will create a new field for you to enter the second one.

The second redirect URI is https://app.getpinwheel.com/banno/{client_id}/launch. The easiest thing to do here is copy the first Redirect URI you just created into the second redirect URI input. Then replace the card at then end with launch.


Application Configuration

  • Client Type: select Confidential.
    • Check “Require PKCE”
    • Leave “User consent required” unchecked

Selecting the Client Type then reveals the following attributes to be configured:

  • Link type: select PluginCard
  • Link title: enter “Account Activation”
  • User type: select All

Claims

  • Locate each claim and check each box for:

    • Accounts with full account numbers
    • Accounts with masked account numbers
    • Debit and credit cards with full card numbers
    • User’s tax ID or social security number (used to check the user's eligibility for PreMatch direct-deposit switching, which bypasses the need for users to log in to their payroll account)
    • Institution routing number
    • Institution details
    • User's first name, or, if missing, username
    • Home, mobile, and work phone numbers (also used to check eligibility for PreMatch direct-deposit switching)
    • Unique customer identifier (CIF or Member Number)
    • Unique identifier for the institution


  • Click the Enabled toggle at the bottom of the page to enable the External Application. Don't worry, this does not enable anything for your customers.

  • Finally, click Save.

Note: For the next step, you'll need the Client ID and the Client Secret (you'll need to unhide the secret), so don't close the tab or window yet.

4. Configure the Switch Kit application in Pinwheel’s Customer Dashboard

Head to your Customer Dashboard and select the Switch Kit tab. If you need access to this, contact your Pinwheel customer success team member for assistance.

Once the Switch Kit tab is open:

  • Enter the Client ID and Client Secret from the previous step.
  • For the Online App URL, enter the URL your end-users use in order to access your online-banking platform. Note: this should be the URL to the banking app your users log in to, not your general marketing website.
  • Leave the Mode on "sandbox".
  • The Link Display Name is optional and can be used to override the default value, which is displayed in gray text. This name is used in the intro screen which says "Let's switch your bills to <Your Bank Name>".

Click Update Config


5. Create the Pinwheel plugin in Banno People

In this step, you'll create the Pinwheel plugin, which is the card that your users will interact with on their dashboard.

In Banno People, open the Dashboard Configuration page and click the "Create a plugin" button.

Return to Banno People and navigate to Dashboard Configuration. Provide the following values for the properties on this screen:

  • Title: Account Activation
  • Description: Switch direct deposit and bill pay instantly to your account.
  • External Application: select “Pinwheel Switch Kit”, which is the name you provided in Step 2 when you created the External Application.
  • Initial Height: 110
  • Icon: circle dollar filled
  • Card action (optional): please leave both Label and External Application empty.
  • Available to everyone: Leave this off for now. You'll turn this on once you are ready to add the plugin for all of your customers. See the Ready for production! section below for more!

👍

You are now ready to test the Pinwheel plugin!

6. Test the plugin in sandbox mode

You can now enable the Pinwheel plugin for test users in your online-banking dashboard and begin testing!

Alternatively, the Pinwheel plugin is available to test directly in the Switch Kit tab on the Customer Dashboard. At this stage, the Pinwheel plugin makes all requests in Sandbox mode. This means simply that we fake connections to merchants and platforms, simulating direct deposit and bill switches. See our docs on Modes for more details.

We use special sandbox credentials to simulate various scenarios, including successful direct deposit and bill switches. Other scenarios that can be simulated include:

  • a payroll platform asking for an MFA token
  • an error with performing the direct deposit switch.
  • payment method declined for a bill switch
  • bill switch merchant returns an error message

Sandbox credentials for these scenarios and others can be found here.

7. Enable it in production mode

Once Sandbox testing is complete, you're ready to enable the Pinwheel plugin for all customers on your platform!

Reach out to your Pinwheel account executive and request access to Production mode. Once access has been granted, head to the Developers tab on the Customer Dashboard to create an API key in Production mode. Click "Create new key" in the Production section. You will be prompted to save your API secret, as this is the only time you will have access to it. As a Banno customer, it's not strictly necessary for you to manage your API secret. To be clear, it is necessary for you to create a key in production mode, as this signals to Pinwheel that you have access to our Switch Kit product.

Next, head back to the Switch Kit tab on the Developer Dashboard and update the Mode to "production". Once this is done, any use of the Pinwheel plugin will make production requests.

Return to Banno People and navigate to Dashboard Configuration. Enable the Available to everyone toggle and click Save.

Finally, add the Pinwheel plugin to the default dashboard for your users in an appropriate place.

🎊

Congratulations, the Pinwheel plugin is now available for all of your users!

Updated about 13 hours ago