Link v1 to v2 Migration Guide

On February 12th we launched a new major version of Pinwheel Link, 2.0. The main changes include a UI overhaul, updated callback and error listeners, and support for payroll income and employment data jobs. We also now offer a React npm package for integration with your web app. This document gives you the changes you'll need to make if upgrading from v1 of the product. Earlier versions of Pinwheel SDKs will continue to function as expected.

Documentation for Link 1.0 can be found here.

Link Tokens

In order to take full advantage of the new Income and Employment Data functionality, you may now specify multiples Jobs to be run for each Link token using the required_jobs parameter. When creating a Link token, simply pass in the Jobs that must be run on a user's payroll account.

Employment Data

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "required_jobs": ["employment", "income", "paystubs"]
}

Direct Deposit and Employment Data

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-API-SECRET: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "required_jobs": [
    "direct_deposit_switch",
    "employment",
  ],
  "account_type": "checking",
  "routing_number": "07464755",
  "account_number": "193464372203",
}

When your users launch the Link modal, Employers and Platforms will automatically be filtered by the required_jobs from the Link token. Employers and platforms that do not support all of these jobs will not be visible to the user.

The job parameter is considered deprecated, but will continue working to run a single required job.

Javascript (React, React Native, and JS Script)

The response types in onSuccess, onExit, and onEvent have changed and two new callback listeners have been added - onLogin and onError. All of them are still optional.

You can get details on the new response types here.

You can see the full list of new error types and codes here.

If your application used direct script integration, note that some properties in InitializationParameters used for the Pinwheel.open() method have been deprecated:

  fullScreen?: boolean;
  targetOrigin?: string;
  selectedEmployer?: EmployerPlatformMapping;
  unregisteredEmployer?: string;

The app automatically handles displaying the modal in full screen in a mobile setting, a predefined employer can be specified in the Link token, and the other two parameters are no longer used in Link.

Android

The Android SDK now features new, optional callbacks for onLogin and onError. In addition, the return types for all callbacks have been updated. The new list of callbacks available is:

  val callbacks = object: PinwheelEventListener {
    override fun onLogin(result: PinwheelLoginPayload) {}
    override fun onSuccess(result: PinwheelResult) {}
    override fun onError(error: PinwheelError) {}
    override fun onExit(error: PinwheelError?) {}
    override fun onEvent(eventName: PinwheelEventType, payload: PinwheelEventPayload?) {}
  }

You can see the referenced data types source here.

iOS

The iOS SDK now features new, optional callbacks for onLogin and onError. In addition, the return types for all callbacks has been updated. The new list of callbacks available is:

  public protocol PinwheelDelegate {
    func onEvent(name: PinwheelEventType, event: PinwheelEventPayload?)
    func onExit(_ error: PinwheelError?)
    func onSuccess(_ result: PinwheelSuccessPayload)
    func onLogin(_ result: PinwheelLoginPayload)
    func onError(_ error: PinwheelError)
  }

You can see the referenced data types source here.


Please contact [email protected] for access to our Developer Dashboard.


Did this page help you?