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 multiple 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.

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

Note: The end_user_id is your internal reference to the end user. See User Model for more information.

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;
  selectedEmployer?: EmployerPlatformMapping;

The fullScreen parameter handles displaying the modal in full screen in a mobile setting, while the selectedEmployer parameter allows for a predefined employer to be specified in the Link token.

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?